Skip to main content
POST
Search contacts

Authorizations

Authorization
string
header
required

A workspace API token (sk_live_...) or an OAuth access token (oat_live_...). Create workspace tokens in Settings > API. Send either as Authorization: Bearer <token>.

Headers

Idempotency-Key
string

A unique value (a UUID works) that makes retrying this request safe. A repeat with the same key and body within 24 hours returns the original response instead of acting twice; the same key with a different body is a 409 idempotency_key_reused.

Maximum string length: 255

Body

application/json

Body for POST /v1/contacts/search.

Unknown keys are rejected, so a misspelled filter fails instead of silently returning every contact.

cursor
string | null
expand
string | null
fields
string | null
filter
FilterGroup · object

A set of conditions combined with and / or. Groups may nest.

limit
integer
default:50
Required range: 1 <= x <= 200
q
string | null

Free text across name, email and phone.

sort
string | null

Same syntax as the sort query parameter.

Response

Successful Response

A page of contacts.

data
Contact · object[]
required
meta
PageMeta · object
required