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 remove tags from multiple contacts at once without opening each contact manually
- You are running a tag cleanup or correction routine on your contact base
- You want to keep your base organized after a campaign or migration
Prerequisites
-
API Key (
API_TOKEN) at hand — see How to find your API Key in Cloud Chat -
The account's
ACCOUNT_ID -
Each contact must have at least one identifier among
identifier,emailorphone_number
Endpoint
DELETE https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/contacts/delete_tags
Headers
| Header | Value |
|---|---|
content-type |
application/json |
api_access_token |
Your API token |
Request body
The body must contain a single field, contacts, which is an array of objects. Each object represents a contact and must contain:
| Field | Required | Description |
|---|---|---|
identifier |
At least 1 of the 3* | Unique identifier of the contact |
email |
At least 1 of the 3* | Contact's email |
phone_number |
At least 1 of the 3* | Contact's phone number |
tags |
Yes | Array with the tags to remove (by name) |
*At least one identifier must be provided to locate the contact.
Request example
curl --request DELETE \
--url 'https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/contacts/delete_tags' \
--header 'api_access_token: API_TOKEN' \
--header 'content-type: application/json' \
--data '{
"contacts": [
{
"identifier": 123,
"tags": ["tag-de-massa-1","tag-de-massa-2"]
},
{
"email": "[email protected]",
"tags": ["tag-de-massa-2","tag-de-massa-3"]
},
{
"phone_number": 5551000000000,
"tags": ["tag-de-massa-1","tag-de-massa-3"]
}
]
}'
How the contact is located
The system looks up the contact in this order:
-
identifier(first) -
email(second) -
phone_number(third)
Unlike the contact import endpoint (which prioritizes email), here identifier takes priority.
About phone_number
If sent without the + prefix, the system adds it automatically (e.g.: 5511999998888 → +5511999998888).
Notes
-
To delete the contact (not just remove tags): How to create, update and delete contacts via API
-
To create or update contacts (including managing tags with granular
tags_addandtags_remove): How to bulk import contacts via API -
To update custom attributes (not tags) on conversations: How to update custom attributes on conversations via API
-
Overview of all available APIs: Master Guide — How to access and operate Cloud Chat data via API