List or look up contacts
This endpoint has two modes.
Lookup by identifier — pass email and/or phone to fetch a single contact by its normalized email address or phone number. items contains the matching contact (including custom_fields) or is empty; pagination is omitted. When both identifiers are supplied, an email match wins and the phone is only consulted if no contact has that email. Empty identifier values are ignored.
Paginated listing — without email/phone, returns a page of contacts sorted by sort/order, optionally narrowed by search and updated_after (contacts updated strictly after an ISO 8601 timestamp — useful for incremental syncs). Listing items do not include custom_fields; fetch a single contact with GET /v1/contacts/{contactId} for those. Unrecognized query parameters are rejected in listing mode.
Authorizations
Workspace API key, e.g. Authorization: Bearer tented_.... Create keys in Workspace Settings → API Keys.
Query Parameters
Lookup mode: return the contact whose normalized email matches. Supplying this (non-empty) switches the endpoint to lookup mode and listing parameters are ignored.
Lookup mode: return the contact whose normalized phone matches. Consulted after email when both are given. Supplying this (non-empty) switches the endpoint to lookup mode.
Listing mode: page number, starting at 1.
x >= 1Listing mode: results per page (1–100).
1 <= x <= 100Listing mode: sort key.
created_at, updated_at, last_activity_at, display_name, first_name, last_name, normalized_email, original_source Listing mode: sort direction.
asc, desc Listing mode: case-insensitive substring match against display name, email, phone, company, first name, and last name.
255Listing mode: only return contacts updated strictly after this ISO 8601 timestamp.
Response
Matching contacts. Lookup mode returns 0 or 1 items (with custom_fields) and no pagination; listing mode returns a page of contacts (without custom_fields) plus pagination.