Home API and integrations | Keys, endpoints and webhooks How to create, update, and delete contacts via API

How to create, update, and delete contacts via API

Last updated on Oct 02, 2026

The most up-to-date documentation for the Cloud Humans APIs is at docs.cloudhumans.com/api-reference. If this article and the reference differ, the reference prevails.

When to use

  • You need to create, look up, update, or delete a specific contact in Cloud Chat via API
  • You want to change only some fields of a contact without erasing the others
  • You are integrating Cloud Chat with another system that manages contacts individually

Prerequisites

This article covers operations on one contact at a time through the standard REST endpoint. To import or update multiple contacts at once, use How to bulk import contacts via API. To only read data, see How to query contacts, tickets, and messages in real time via API.

Permissions by operation

Operation Minimum permission
Create, look up, update Any agent profile
Delete contact Administrator
Look up by email (/contacts/email) Administrator

If you can create and update but get 403 Forbidden when deleting, your token belongs to an agent. Use an administrator user token to delete contacts.

Create contact

POST https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts

The body is a simple JSON object — at least one of email, phone_number, or identifier:

{
  "name": "Maria Silva",
  "email": "[email protected]",
  "phone_number": "+5511999998888",
  "identifier": "CRM-123",
  "additional_attributes": { "company_name": "Acme" },
  "custom_attributes": { "plano": "premium" }
}

  • Optional: send inbox_id (and source_id) to link the contact to an inbox right away.

  • Response 200 with the created contact, including the id.

Look up contact

By id:

GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}

By exact email (requires administrator):

GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/[email protected]

To search by free text (name, phone, company, partial), use the search endpoint — see How to query contacts, tickets, and messages in real time via API, section "Buscar contatos por texto livre" (Search contacts by free text).

Update contact

PUT https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}

Send only the fields you want to change:

{
  "name": "Maria S. Silva",
  "custom_attributes": { "plano": "enterprise" }
}

Unlike the bulk import with upsert: true, the individual update does not erase the fields you don't send.

  • custom_attributes are merged with the existing ones (the others are not cleared).

  • To remove a specific custom attribute:

POST https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}/destroy_custom_attributes

{ "custom_attributes": ["plano"] }
  • Response 200 with the updated contact.

Delete contact

DELETE https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}

  • Requires an administrator user.

  • Response 200 on success.

If the contact is online at the time of the call, the deletion is blocked and returns 422. Try again when the contact is not active.

To remove only tags from contacts (without deleting the contact), see How to bulk remove tags from contacts via API.

Request example (update)

curl -X PUT \
  'https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}' \
  --header 'content-type: application/json' \
  --header 'api_access_token: SEU_TOKEN' \
  --data '{ "name": "Maria S. Silva" }'

Common errors

Status Meaning
403 Forbidden Token without permission (deleting requires administrator)
422 Unprocessable Entity Invalid data, or attempt to delete an online contact
404 Not Found Contact not found in the account

Where to find the parameters

  • CLOUDCHAT_DOMAIN — domain visible in the browser URL

  • ACCOUNT_ID — in "Configurações da conta" (Account Settings)

  • API_TOKEN — at https://{CLOUDCHAT_DOMAIN}/app/accounts/{ACCOUNT_ID}/profile/settings

Notes