Sparse Fieldsets

Overview

Sparse fieldsets allow you to optimize API responses by requesting only the data you need. Instead of receiving all available fields, you can specify exactly which relationships and optional data to include in the response.

How It Works

By default, API endpoints return core entity data without loading related resources. You can use the include query parameter to request additional data relationships.

Query Parameter Format:

?include=relationship1,relationship2,relationship3

Benefits

Performance Optimization

• Reduced Payload Size: Smaller responses transfer faster over the network
• Database Efficiency: Only queries data you actually need
• Bandwidth Savings: Important for mobile and limited bandwidth scenarios

Flexible Data Loading

• On-Demand Loading: Request related data only when needed
• Custom Views: Different endpoints can request different data sets
• Progressive Loading: Load summary first, details on-demand

Common Use Cases

Product Endpoints

Basic Product Info (Default): GET /api/v1/operations/products/{id}

Returns: id, name, SKU, basic pricing

Product with Pricing Details: GET /api/v1/operations/products/{id}?include=pricing

Returns: Basic info + cost_price, margin, price_tiers

Product with Inventory: GET /api/v1/operations/products/{id}?include=inventory

Returns: Basic info + stock levels, warehouse locations

Product with Full Details: GET /api/v1/operations/products/{id}?include=pricing,inventory,variants,attributes

Returns: All available data

Customer Endpoints

Basic Customer Info (Default): GET /api/v1/crm/customers/{id}

Returns: id, name, email, phone

Customer with Order History: GET /api/v1/crm/customers/{id}?include=orders

Returns: Basic info + recent orders

Customer with Full Context: GET /api/v1/crm/customers/{id}?include=orders,activities,opportunities,contacts

Returns: Complete customer profile

Available Includes by Module

Operations Module

Products:

• pricing - Cost price, margin, price tiers
• inventory - Stock levels, warehouse locations
• variants - Product variants and configurations
• attributes - Product attributes (EAV data)
• category - Product category details
• brand - Brand information
• supplier - Primary supplier details

Purchase Orders:

• line_items - PO line items with product details
• supplier - Full supplier information
• warehouse - Destination warehouse details
• activities - Activity log and history
• payments - Payment records

Inventory:

• product - Full product details
• warehouse - Warehouse information
• movements - Recent stock movements

CRM Module

Leads:

• activities - Activity history
• opportunities - Related opportunities
• assigned_to - User assignment details

Customers:

• orders - Order history
• activities - Activity timeline
• opportunities - Sales opportunities
• contacts - Customer contacts
• invoices - Invoice history

Opportunities:

• customer - Customer details
• activities - Activity log
• products - Related products
• quotes - Generated quotes

Best Practices

Request Only What You Need

Don't automatically include all relationships. Assess what data is actually required for your use case.

Good:

GET /products/{id}?include=pricing

Only loads pricing when needed

Avoid:

GET /products/{id}?include=pricing,inventory,variants,attributes,category,brand

Loads everything regardless of need

Consider Query Performance

Some includes require additional database queries. Requesting many relationships may impact response time.

Performance Tips:

• Load heavy relationships on-demand (separate requests)
• Use pagination for list endpoints with includes
• Cache responses when appropriate

Use Consistent Includes

For similar UI views, use the same include parameters to benefit from client-side caching.

Handle Missing Relationships

Not all entities have all relationships. Your application should gracefully handle:

• Null relationship values
• Empty arrays for one-to-many relationships
• Missing optional fields

Response Structure with Includes

Included data appears within the main entity response, not as separate top-level keys.

Without Includes:

{
  "data": {
    "id": 123,
    "name": "Product Name",
    "sku": "PROD-123"
  }
}

With Includes:

{
  "data": {
    "id": 123,
    "name": "Product Name",
    "sku": "PROD-123",
    "pricing": {
      "cost_price": 10.00,
      "selling_price": 15.00,
      "margin": 5.00
    },
    "inventory": {
      "total_stock": 100,
      "available_stock": 85,
      "reserved_stock": 15
    }
  }
}

Pagination with Includes

When using sparse fieldsets with paginated endpoints, includes apply to all items in the collection:

GET /products?include=pricing&per_page=20

Returns 20 products, each with pricing data included.

Performance Note: Including relationships on list endpoints can impact performance. Consider:

• Using smaller page sizes
• Loading relationships for selected items only
• Implementing progressive loading

Combining with Other Query Parameters

Sparse fieldsets work alongside other query parameters:

GET /products?
  status=active&
  category_id=5&
  include=pricing,inventory&
  sort_by=name&
  per_page=20

Query parameters are applied in order:

1. Filters applied (status, category_id)
2. Sorting applied
3. Pagination applied
4. Includes loaded for results

Error Handling

Invalid Include Names

Requesting non-existent includes will be ignored without error. Check API documentation for valid include names per endpoint.

Permission-Based Includes

Some includes may be restricted based on user permissions. If you lack permission, the include will be silently omitted.

Related Resources

• API Reference - Valid include parameters for each endpoint
• Authentication - Required for all API requests
• Error Handling - Handling API errors