Pagination, filtering and sorting

List endpoints return one page of records at a time. Most of them page by number, filter with query parameters and sort with sortBy and sortOrder.

For the main lists (leads, contacts, companies, deals, activities, projects, tasks and products), the API reference lists every query parameter the endpoint accepts. For other lists it does not list them yet. This page explains the common pattern and the exceptions.

Page through resultsCopy Anchor Link

Most list endpoints take two query parameters:

They answer with the records in items and the totals next to them:

{
  "items": [ ... ],
  "total": 128,
  "page": 2,
  "pageSize": 50,
  "pageCount": 3
}

total counts every record that matches your filters, not only the ones on this page. pageCount is the number of pages at this pageSize. A few endpoints call it totalPages instead, and GET /api/products returns both.

To read everything, request pages until page reaches pageCount (or until items comes back empty):

curl "https://<your-workspace>.apros.app/api/contacts?page=2&pageSize=100" \
  -H "Authorization: Bearer $APROS_API_KEY"

Page size limitsCopy Anchor Link

• The default page size depends on the endpoint: 20 for leads, 50 for contacts, companies, deals and tasks, for example. Set pageSize explicitly so you do not depend on it.
• The largest page size is 100 on most endpoints. GET /api/tasks allows up to 500.
• Endpoints differ in what they do with a larger value: some answer 400 (for example /api/leads, /api/contacts, /api/companies, /api/deals), others quietly use their maximum. Do not ask for more than 100.

ExceptionsCopy Anchor Link

Check each endpoint's response keys in the reference: they are listed for every operation.

FilterCopy Anchor Link

List endpoints filter with query parameters named after the field: for example GET /api/leads?status=QUALIFIED&temperature=HOT. Common ones:

You always get only the records the key's owner is allowed to see; filters narrow that further.

Custom fieldsCopy Anchor Link

Leads, contacts, companies and deals can be filtered by your workspace's custom fields with parameters prefixed cf_ and the field's name:

On contacts, companies and deals, a cf_ parameter that matches no custom field is refused with 400 and the code UNKNOWN_CUSTOM_FIELD_FILTER.

Unknown parameters are refusedCopy Anchor Link

Contacts, companies, deals, projects, tasks, products, files, custom entity records and the lead duplicate endpoints check their query string strictly. A parameter they do not accept, or a single-value parameter given twice, answers 400 instead of being ignored:

{
  "error": "Unknown query parameter(s): limit. Accepted: page, pageSize, ...",
  "code": "UNKNOWN_QUERY_PARAM",
  "details": {
    "unknownParams": ["limit"],
    "acceptedParams": ["page", "pageSize", "..."]
  }
}

The example is shortened; in a real response details.acceptedParams is the full list of what the endpoint takes. Other endpoints, /api/leads among them, still ignore parameters they do not know, so a misspelled filter there returns an unfiltered list. Check parameter names against the reference.

SortCopy Anchor Link

Most list endpoints sort with two parameters:

Without them, lists come in a default order, usually newest first (createdAt, desc).

The main lists (leads, contacts, companies, deals, projects, tasks and products) accept only the sortBy fields the reference lists for them and refuse any other with 400. Not every endpoint checks sortBy, so sort only by fields you know the endpoint supports.