List contacts
Returns a paginated list of contacts, with optional filters, sorting and a free-text search.
Endpoint
GET/contacts
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
organization_id | integer | No | Only contacts of this organization. Required when you use searchTerm. |
| any contact field | mixed | No | Filter with Feathers syntax, e.g. email=jane@example.com, system_type=lead, owned_by_user_id[$in][]=789, created_at[$gte]=2026-01-01. |
tag_ids[] | integer[] | No | Only contacts that have at least one of these tag IDs. |
searchTerm | string | No | Free-text search (at least 3 characters). Requires organization_id and searchIn. |
searchIn | string | With searchTerm | Where to search: all, name, phone, email or custom_field. |
custom_field_name | string | With searchIn=custom_field | Name of the custom field to search in. |
view_id | integer | No | Apply the filters of a saved contacts view. |
fastJoinForContactList | string | No | Set to true to embed company and owner objects in each contact. |
$limit | integer | No | Page size. Default 10, max 50. |
$skip | integer | No | Number of records to skip. |
$sort[field] | 1 | -1 | No | Sort ascending or descending, e.g. $sort[created_at]=-1. |
$select[] | string | No | Only return these fields. |
Request
Search by phone:
Response
json
Each item is a full contact object; it is shortened here.
Notes
- With
searchTerm, results are sorted byfirst_nameunless you pass$sortonfirst_name,last_name,email,created_atorupdated_at. Terms shorter than 3 characters (or a lone+or digit) return an empty page. searchIn=allalso matches custom field values when the term has 4 or more characters.
Report an issue with this documentation
Please log in to report issues with our documentation.