Skip to main content
GET
List and search contacts

Authorizations

Authorization
string
header
required

HTTP Basic Authentication. Use your API Access Key ID as the username and your API Access Key Secret as the password. Generate keys in the CloudTalk Dashboard under Account -> Settings -> API Keys (https://dashboard.cloudtalk.io/menu/account/settings/API-keys).

Query Parameters

limit
integer
default:20

Page size, 1 to 100. Out-of-range values are clamped and the value used is echoed in pagination.limit. A value that is not a whole number, such as abc or 1.5, is rejected with 400 VALIDATION.INVALID_PARAMETER.

Example:

20

cursor
string

Opaque cursor from a previous page's pagination.next. Pass it back unchanged. Send it with the same filters: a cursor from a list with updatedSince (ordered by update time) is rejected on a list without it, and the other way round. A cursor this API did not issue, or one sent with different filters, is rejected with 400 PAGINATION.INVALID_CURSOR.

Full-text search, 2 to 200 characters. See How search matches above.

Required string length: 2 - 200
Example:

"acme"

tagIds
string

1 to 20 comma-separated contact tag ids from List contact tags. A contact matches when it has any of them. Integration tag ids match nothing.

Example:

"123,131"

type
enum<string>

contact or lead. Default: both.

Available options:
contact,
lead
updatedSince
string<date-time>

RFC 3339 time. Only contacts whose updatedAt is at or after it. Without search, the list is then ordered by updatedAt, most recently updated first. A contact updated while you page moves to the top of that order, so the next run with a later updatedSince picks it up.

Example:

"2026-11-01T00:00:00Z"

Response

One page of contacts.

data
object[]
required
pagination
object
required
requestId
string
required