Skip to main content
The Contacts API at https://api.cloudtalk.io/v1 reads and changes the same contacts you see under Contacts in the Dashboard. Use it to keep CloudTalk in step with your CRM, add leads from a web form, or find the contact behind a phone number before a call. It covers three resources: contacts (/contacts), the contact tag catalogue (/contact-tags) and the custom field catalogue (/contact-fields). The older /contacts/*.json and /tags/*.json endpoints on https://my.cloudtalk.io/api keep working unchanged. The reference lists them under Contacts (LEGACY) and Contact tags (LEGACY), marked LEGACY.
Requests authenticate with an API key, like the rest of the CloudTalk API. The key acts as a company admin: it sees and changes every contact in your account, and no header names a user.

​
Quick start

1

Read the custom fields and tags you can set

A field’s name is the key you use in customFields. A tag’s id is what tagIds takes. A create never makes a tag by accident: to use a new tag, create it first with Create a contact tag.
2

Create a contact, or update the one that matches

The answer is 201 with the new contact. With matchBy set, a contact that matches is updated instead and the answer is 200. When several contacts match, the most recently created one is updated and the others stay as they are.
3

Find a contact by phone or email

Lookup matches exactly. To search by name or text, use List and search contacts with search.
4

Change only what you send

Fields you leave out stay as they are. null clears a text field other than name, or removes one custom field key.

​
Operations

Lists return { "data": [...], "pagination": { "limit": 20, "next": "..." }, "requestId": "..." }. Set ?limit= (default 20, at most 100) and pass pagination.next as ?cursor= with the same filters to get the next page. next is null on the last page. One contact, tag or field comes back as a bare object.

​
Keeping another system in step

  • Changes as they happen. Subscribe to the contact.created, contact.updated and contact.deleted webhooks. Changes made through this API send them too.
  • Catching up. Call List and search contacts with updatedSince set to the time your previous run started. The list then comes most recently updated first. Some changes do not move updatedAt, for example Dashboard bulk edits and CRM list sync. The reference lists them. To pick those up too, list all contacts without updatedSince from time to time, and again after you miss webhook events or run a bulk sync.
  • Read-only tags. Integration tags, and tags that contacts get through a CRM integration, show readOnly: true. You can read them but not add, remove, rename or delete them here (422 CONTACTS.TAG_READ_ONLY).
  • Text is cleaned up. On create, bulk upsert, update, and when you create or rename a tag, emojis and other characters that take 4 bytes in UTF-8, and control characters such as line breaks and tabs, become a space. Repeated whitespace becomes one space, and spaces at the start and end are removed. This happens before lengths are checked, the same as in the CloudTalk Dashboard and the existing API. It applies to name, title, company, industry, website, address, city, state, zip, custom field values and tag names, not to emails or phone numbers. Compare cleaned values, not the raw ones you sent, when you check what was stored.

​
API fields and webhook fields

The API uses camelCase. The contact.* webhook payloads use snake_case and keep their own names, so the same contact reads differently in each. Use this table to map one onto the other. contact.deleted carries only id.

​
Safe retries

A network error on POST /contacts leaves you not knowing whether the contact was created. Send an Idempotency-Key header (up to 255 characters) and retry with the same key and the same body:
  • The contact was created: you get the original status with the contact as it is now.
  • The first request is still running: 409 IDEMPOTENCY.REQUEST_IN_PROGRESS. Retry it shortly.
  • The same key with a different body: 422 IDEMPOTENCY.KEY_REUSED. A key names one create.
  • The contact was deleted since: the same key creates a new one.
Keys are kept for 24 hours. Bulk upsert contacts takes no key. It always matches, so retrying the same call with the same matchBy updates the rows that were already written.

​
Errors

Errors share one shape:
Requests are rate limited per company. Over the limit you get 429 with X-CloudTalkAPI-Limit, X-CloudTalkAPI-Remaining and X-CloudTalkAPI-ResetTime, and no error body. Branch on code. message is for people and can change, and it never repeats a value you sent. Quote requestId when you contact support. Each operation’s reference page lists the codes it can return, and Error codes covers the shape.