Skip to main content
GET
Search contacts

Authorizations

Authorization
string
header
required

The id_token from POST /auth/v1/signin, sent as Authorization: Bearer <id_token>. Not the access_token — that one does not carry the identity Cloud Chat authorizes on.

Headers

cloudchat-instance
integer
required

Your Cloud Chat instance ID — an integer, fixed for your company, told at onboarding. The API overview explains how instances work, how to find yours, and the errors a wrong or missing value produces.

Example:

1

Path Parameters

accountId
integer
required

Your Cloud Chat account. It has to be an account your token grants membership on, and it has to live on the instance in the cloudchat-instance header — the two travel together. Account numbers are only unique within an instance, so the same number is a different company on another instance. Usually a mismatched pair fails closed with a 401, because your user does not exist on the other instance — but if your identity happens to exist on both, the call succeeds against the other company's data, silently. Read it and you are looking at the wrong help center; write it and you have stored into the wrong account. Send the two values that were given to you together, and never try a number to see what answers.

Example:

1

Query Parameters

The text to look for: a name, an email address, a phone number or an identifier. From 3 to 200 characters; a leading + and extra spaces are ignored, and % and _ are matched literally. Missing, shorter than 3 characters, longer than 200, or sent as an array (search[]=) answers 400, with error.details naming search.

Example:

"maria.silva@example.com"

per_page
integer
default:20

How many contacts to return. Clamped, never rejected: above 20 you get 20, below 1 you get the default, which is also 20.

Required range: 1 <= x <= 20
Example:

20

Response

The contacts that match, with meta.has_next telling whether more match than data holds.

The contacts that match the search text.

data
object[]
required

At most 20 contacts, in no particular order.

meta
object
required

Whether the search found more than it returned. There is no total and no next page.