List Contacts

Retrieve a paginated list of contacts with advanced filtering, sorting, searching, field selection, and relationship inclusion.

Authentication

Required Scope: contacts:read

Query Parameters

Pagination

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	15	Items per page (max: 100)

Sorting

Parameter	Type	Description
`sort`	string	Comma-separated sort fields. Prefix with `-` for descending order

Allowed sort fields: id, firstname, lastname, created_at, updated_at

Examples:

sort=firstname — ascending by first name

sort=-created_at — descending by creation date

sort=firstname,-created_at — multiple sort fields

Searching

Parameter	Type	Description
`search`	string	Search across firstname, lastname, email, phone, company (partial match)
`q`	string	Alias for `search`

Filtering

Use filter[field] for exact match or filter[field][operator] for complex filters.

Allowed filter fields:

Filter	Type	Description
`filter[type]`	string	Contact type: `lead`, `customer`, `guest`
`filter[status_id]`	integer	Status ID
`filter[source_id]`	integer	Source ID
`filter[assigned_id]`	integer	Assigned user ID
`filter[created_at]`	date/datetime	Creation date (supports operators)
`filter[group_id]`	integer	Group ID (JSON contains match)

Complex filter operators:

Operator	Alias	Example	Description
`gte`	`>=`	`filter[created_at][gte]=2025-01-01`	Greater than or equal
`lte`	`<=`	`filter[created_at][lte]=2025-12-31`	Less than or equal
`gt`	`>`	`filter[created_at][gt]=2025-01-01`	Greater than
`lt`	`<`	`filter[created_at][lt]=2025-12-31`	Less than
`ne`	`!=`	`filter[status_id][ne]=3`	Not equal
`like`	—	`filter[type][like]=lea`	Partial match (wraps with %)
`in`	—	`filter[status_id][in]=1,2,3`	Match any value in list
`not_in`	—	`filter[status_id][not_in]=4,5`	Exclude values in list
`between`	—	`filter[created_at][between]=2025-01-01,2025-12-31`	Between two values
`null`	—	`filter[assigned_id][null]=true`	Check if field is null (true/false)

Relationships

Parameter	Type	Description
`include`	string	Comma-separated list of relationships to include

Allowed includes: groups, source, status

Field Selection

Parameter	Type	Description
`fields`	string	Comma-separated list of fields to return

Note: Critical fields (id, tenant_id, created_at, updated_at, type, status_id, source_id, email, phone, description, city, state, zip, address, country_id, assigned_id, group_id, is_opted_out, firstname, lastname, company) are always included regardless of selection.

Response Fields

Field	Type	Description
`id`	integer	Contact ID
`firstname`	string	First name
`lastname`	string	Last name
`company`	string\|null	Company name
`type`	string	Contact type: `lead`, `customer`, `guest`
`email`	string\|null	Email address
`phone`	string\|null	Phone number
`status_id`	integer	Status ID
`source_id`	integer	Source ID
`description`	string\|null	Description
`city`	string\|null	City
`state`	string\|null	State
`zip`	string\|null	ZIP/postal code
`address`	string\|null	Street address
`country_id`	integer\|null	Country ID
`assigned_id`	integer\|null	Assigned user ID
`group_id`	array	Array of group IDs
`is_opted_out`	boolean	Opt-out status (default: false)
`created_at`	string	ISO 8601 datetime
`updated_at`	string	ISO 8601 datetime
`groups`	array	Groups data (when `include=groups`)
`source`	object	Source data (when `include=source`)
`status`	object	Status data (when `include=status`)

Pagination Meta

The meta.pagination object contains:

Field	Type	Description
`total`	integer	Total contacts matching filters
`count`	integer	Number of contacts on current page
`per_page`	integer	Items per page
`current_page`	integer	Current page number
`total_pages`	integer	Total number of pages
`has_more`	boolean	Whether more pages exist

Example Requests

GET /v2/contacts?per_page=20&sort=-created_at
GET /v2/contacts?filter[type]=customer&search=john
GET /v2/contacts?filter[created_at][gte]=2025-01-01&filter[created_at][lte]=2025-12-31
GET /v2/contacts?filter[group_id]=5&include=groups,source
GET /v2/contacts?fields=id,firstname,phone&sort=firstname&per_page=50&page=2

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Authentication#

Query Parameters#

Pagination#

Sorting#

Searching#

Filtering#

Relationships#

Field Selection#

Response Fields#

Pagination Meta#

Example Requests#

Request

Responses