List contacts | AskElephant | API Documentation

Returns workspace contacts using cursor pagination ordered by updated_at descending by default. filter[crm_associations][eq] supports only CRM objects with object_type=contact. This endpoint accepts limit, cursor, search, order_by, filter[crm_associations], and filter[updated_at] only; expand and legacy top-level aliases are not supported. Requires the contacts:read scope.

Returns workspace contacts using cursor pagination ordered by `updated_at` descending by default. `filter[crm_associations][eq]` supports only CRM objects with `object_type=contact`. This endpoint accepts `limit`, `cursor`, `search`, `order_by`, `filter[crm_associations]`, and `filter[updated_at]` only; `expand` and legacy top-level aliases are not supported. Requires the `contacts:read` scope.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Query parameters

limitintegerOptional1-100Defaults to 25

Maximum number of results to return. Defaults to 25 and is capped at 100.

cursorstringOptional

Keyset cursor from a previous list response. Cursors encode the sort key and record id tie-breaker from the last row on the prior page — they are not offset tokens and do not isolate a point-in-time snapshot.

For order_by on updated_at, cursors use the pa_uac_1_ prefix and encode { "id", "updatedAt" }. For GET /v2/engagements with order_by on start_at, cursors use the pa_sac_1_ prefix and encode { "id", "startAt" }. A cursor is bound to the sort field, not the direction. An updated_at cursor cannot be used with order_by=start_at:* (or the reverse). Reusing a cursor with the opposite direction for the same field is accepted, but can skip or repeat records.

Live keyset pagination can re-deliver a row whose sort key moved forward during the walk (design sync jobs to upsert by id) and can skip a row whose sort key moved backward.

Keyset cursor from a previous list response. Cursors encode the sort key and record `id` tie-breaker from the last row on the prior page — they are not offset tokens and do not isolate a point-in-time snapshot. For `order_by` on `updated_at`, cursors use the `pa_uac_1_` prefix and encode `{ "id", "updatedAt" }`. For `GET /v2/engagements` with `order_by` on `start_at`, cursors use the `pa_sac_1_` prefix and encode `{ "id", "startAt" }`. A cursor is bound to the sort field, not the direction. An `updated_at` cursor cannot be used with `order_by=start_at:*` (or the reverse). Reusing a cursor with the opposite direction for the same field is accepted, but can skip or repeat records. Live keyset pagination can re-deliver a row whose sort key moved forward during the walk (design sync jobs to upsert by `id`) and can skip a row whose sort key moved backward.

searchstringOptional

Free-text search string matched against contact full names and email addresses. This does not search phone numbers, descriptions, or company data.

order_byenumOptional

Sort order for the list. Defaults to updated_at:desc.

Allowed values:

filter[crm_associations][eq]stringOptional

Filter resources by CRM associations. For readability, docs examples use indexed bracket syntax such as filter[crm_associations][eq][0][id]=123 plus filter[crm_associations][eq][0][object_type]=<supported-object-type>. The API also accepts a JSON-encoded array string with objects containing id and object_type. CRM source is inferred from the workspace’s connected CRM state. Supported object_type values depend on the endpoint. Supports up to 20 objects.

Filter resources by CRM associations. For readability, docs examples use indexed bracket syntax such as `filter[crm_associations][eq][0][id]=123` plus `filter[crm_associations][eq][0][object_type]=<supported-object-type>`. The API also accepts a JSON-encoded array string with objects containing `id` and `object_type`. CRM source is inferred from the workspace's connected CRM state. Supported `object_type` values depend on the endpoint. Supports up to 20 objects.

filter[updated_at][gt]datetimeOptional

Return resources updated strictly after the provided ISO-8601 UTC timestamp.

filter[updated_at][gte]datetimeOptional

Return resources updated at or after the provided ISO-8601 UTC timestamp.

filter[updated_at][lt]datetimeOptional

Return resources updated strictly before the provided ISO-8601 UTC timestamp.

filter[updated_at][lte]datetimeOptional

Return resources updated at or before the provided ISO-8601 UTC timestamp.

Response headers

X-RateLimit-Limitinteger

Maximum number of authenticated requests allowed for the workspace in the current 60-second window. The limit is 1000 and applies to all /api/v2 resource routes (GET, POST, PATCH, and DELETE), shared across every credential for the workspace.

X-RateLimit-Remaininginteger

Number of requests remaining in the current window before the limit is exceeded.

X-RateLimit-Resetinteger

Unix epoch seconds when the current rate-limit window resets.

X-Api-VersionstringOptional

Response

Paginated contacts list.

objectenum

Resource discriminator for list responses.

datalist of objects

Contact records in the current page.

has_moreboolean

Indicates whether another page of contacts is available.

next_cursorstring or null

Keyset cursor for the next page (same pa_uac_1_ format as the cursor query parameter), or null when there are no more results.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error

Live keyset pagination can re-deliver a row whose sort key moved forward during the walk (design sync jobs to upsert by id) and can skip a row whose sort key moved backward.