Skip to main content
ContactsVersion: v3New

Lookup Contact By Email Or Phone

GET/contacts/lookup

Look up contacts matching an exact email or phone, scoped to a location, up to limit contacts (max 20) per page. Also matches against a contact's additional emails and additional phone numbers. Exactly one of email or phone must be provided. Paginate with nextCursor. Returns an empty contacts array if no contact matches. Requires the Version header set to at least v3; earlier versions return 400. Available to OAuth access tokens and Private Integration Tokens.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your access token.

Scope:contacts.readonly
Auth methods:OAuthPrivate Integration
Token type:Sub-Account Token

Request​

Headers

Versionstringrequired

API Version. Send v3.

Available optionsv3
Example:v3

Query Parameters

locationIdstringrequired

Location Id. Must be a non-empty string.

Example:ve9EPM428h8vShlRW1KT
emailstring

Exact email to look up (case-insensitive), mutually exclusive with phone.

phonestring

Exact phone number to look up, in E.164 format, mutually exclusive with email.

Example:+1423164516
nextCursorstring

Opaque pagination cursor returned as nextCursor by a previous request.

Example:eyJkYXRlQWRkZWQiOjE3MDAwMDAwMDAwMDAsImlkIjoiYy1sYXN0In0=
limitinteger

Max number of contacts to return per page. Defaults to 20, capped at 20.

Example:20

Response

Successful response

contactsobject[]

Contacts matching the given email or phone, up to the requested limit (max 20)

nextCursorstring

Opaque cursor to fetch the next page. Present whenever the current page is full (limit results returned); a follow-up request with this cursor may return an empty contacts array if that was the last page.

Example:eyJkYXRlQWRkZWQiOjE3MDAwMDAwMDAwMDAsImlkIjoiYy1sYXN0In0=