Pagination

Overview

All list endpoints in the Adva API support pagination through limit and offset query parameters. Responses include the total count of matching records so you can calculate page numbers or detect when you have reached the end.

Pagination Parameters

Parameter	Type	Default	Range	Description
limit	integer	50	1 — 100	Maximum number of records to return
offset	integer	0	0+	Number of records to skip

Basic Example

Fetch the first page of customers (default: 50 records):

curl -X GET "https://api.getadva.ai/api/v1/core/customers" \
  -H "Authorization: Bearer $TOKEN"

Fetch the second page:

curl -X GET "https://api.getadva.ai/api/v1/core/customers?limit=50&offset=50" \
  -H "Authorization: Bearer $TOKEN"

Fetch a smaller page (10 records):

curl -X GET "https://api.getadva.ai/api/v1/core/customers?limit=10&offset=0" \
  -H "Authorization: Bearer $TOKEN"

Response Format

Every list endpoint returns a consistent envelope:

{
  "customers": [
    { "contact_id": "...", "display_name": "John Smith", ... },
    { "contact_id": "...", "display_name": "Jane Doe", ... }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0
}

Field	Type	Description
<resource>	array	The array of records (key name matches the resource, e.g., customers, proposals, jobs)
total	integer	Total number of records matching the current filters (before pagination)
limit	integer	The limit that was applied
offset	integer	The offset that was applied

Iterating Through All Pages

async function fetchAllCustomers(token) {
  const limit = 100;
  let offset = 0;
  let allCustomers = [];

  while (true) {
    const response = await fetch(
      `https://api.getadva.ai/api/v1/core/customers?limit=${limit}&offset=${offset}`,
      { headers: { Authorization: `Bearer ${token}` } },
    );
    const data = await response.json();

    allCustomers = allCustomers.concat(data.customers);

    if (allCustomers.length >= data.total) break;
    offset += limit;
  }

  return allCustomers;
}

Sorting

Most list endpoints support sorting through sort_by and sort_order query parameters:

Parameter	Type	Default	Description
sort_by	string	varies by endpoint	Field to sort by
sort_order	asc or desc	varies by endpoint	Sort direction

Example

Sort customers by name, descending:

curl -X GET "https://api.getadva.ai/api/v1/core/customers?sort_by=display_name&sort_order=desc" \
  -H "Authorization: Bearer $TOKEN"

Sort proposals by creation date:

curl -X GET "https://api.getadva.ai/api/v1/sales/proposals?sort_by=created_at&sort_order=asc" \
  -H "Authorization: Bearer $TOKEN"

Filtering

List endpoints support domain-specific filters as query parameters. Filters vary by resource. Here are common patterns:

Core: Customers

Parameter	Type	Description
lifecycle_status	string	Filter by status (e.g., active, lead, prospect)
territory_id	UUID	Filter by territory
assigned_rep_id	UUID	Filter by assigned sales rep
search	string	Full-text search across customer fields

curl -X GET "https://api.getadva.ai/api/v1/core/customers?lifecycle_status=active&search=smith" \
  -H "Authorization: Bearer $TOKEN"

Sales: Appointments

Parameter	Type	Description
deal_id	UUID	Filter by deal
customer_role_id	UUID	Filter by customer role
status	string	Filter by status (scheduled, completed, cancelled, no_show, rescheduled)
search	string	Search across appointment fields

Operations: Equipment

Parameter	Type	Description
equipment_id	UUID	Filter by specific equipment
crew_id	UUID	Filter crew equipment by crew
job_id	UUID	Filter job equipment by job
maintenance_type	string	Filter maintenance logs by type
active	boolean	Filter crew equipment by active status

Combining Filters with Pagination

All filters, sorting, and pagination parameters can be combined:

curl -X GET "https://api.getadva.ai/api/v1/core/customers?lifecycle_status=active&territory_id=550e8400-e29b-41d4-a716-446655440000&sort_by=display_name&sort_order=asc&limit=25&offset=0" \
  -H "Authorization: Bearer $TOKEN"