Pagination, Filtering, Sorting, and Includes

List endpoints return records in a data array and pagination details in meta.

Pagination

Use:

• page for the current page. Invalid or missing values default to 1.
• per_page for page size. Invalid or missing values default to 25.

per_page is clamped between 1 and 100.

Example:

curl "$AGILED_API_BASE_URL/public/v1/contacts?page=2&per_page=50" \
  -H "Authorization: Bearer $AGILED_API_TOKEN"

Meta Shape

List responses include:

{
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 25,
    "total": 68
  }
}

Sorting

Use:

• sort_by
• sort_direction=asc
• sort_direction=desc

If a sort field is not supported for that resource, the endpoint falls back to the resource default.

Includes

Some resources support include for related records. Pass comma-separated values:

curl "$AGILED_API_BASE_URL/public/v1/contacts?include=accounts,assigned_user" \
  -H "Authorization: Bearer $AGILED_API_TOKEN"

Unsupported include values are ignored.

Common Filters

Available filters depend on the resource. Examples include:

• Contacts: email, full_name, created_after, updated_after
• Accounts: name, email
• Deals: name, status
• Tickets: subject, status, priority, account_id, contact_id
• Projects: name, status
• Tasks: title, status, project_id
• Invoices: invoice_number, status
• Products: search, type, category_id, is_active
• Files: search, file_type, parent_id, uploader_id

Sync Job Pattern

For incremental syncs, page through results with a stable sort and store the last successfully processed timestamp or cursor in your integration. Start with small pages while testing, then raise per_page only after error handling and retry behavior are proven.

When using updated_after, allow a small overlap window and deduplicate by record ID. This prevents missing records when updates happen during a running sync.

Include Strategy

Use includes for screens, dashboards, or one-off lookups where related context improves the response. For bulk sync, start without includes and fetch related records only when needed.

Large include payloads make retries and logs harder to inspect. Keep the sync payload as small as possible until you know which relationships the downstream system truly needs.

Related Docs

• CRM Endpoints
• Finance Endpoints
• Productivity Endpoints