Contact Tags: Add, Remove, and List Contact Tags

ChatbotX uses tags to label and segment contacts for automation, filtering, and reporting. This page documents all three tag management endpoints for a contact: adding tags, removing tags, and listing currently applied tags. All three endpoints use the same flexible contact identifier format (ID, email, or phone).

Add Tags to a Contact

Applies one or more tags to a contact. You must supply a non-empty array of tag IDs. You can add up to 100 tags in a single request. A successful request returns HTTP 204 No Content.

POST /api/v1/contacts/{identifier}/tags

Path Parameters

string

required

Contact lookup string (id:<value>, email:<value>, or phone:<value>). Minimum length: 1 character.

Request Body

array of strings

required

Array of tag IDs to add to the contact. Must contain between 1 and 100 elements. Each ID must be a numeric string matching \d+.

Code Examples

curl --request POST \
  --url "https://app.chatbotx.io/api/v1/contacts/email:user@example.com/tags" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "tagIds": ["15", "28", "41"]
  }'

import requests

identifier = "email:user@example.com"
url = f"https://app.chatbotx.io/api/v1/contacts/{identifier}/tags"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
payload = {"tagIds": ["15", "28", "41"]}

response = requests.post(url, json=payload, headers=headers)
print(response.status_code)  # 204 on success

const identifier = 'email:user@example.com';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ tagIds: ['15', '28', '41'] })
};

fetch(`https://app.chatbotx.io/api/v1/contacts/${identifier}/tags`, options)
  .then(res => {
    if (res.status === 204) console.log('Tags added successfully');
  })
  .catch(err => console.error(err));

Response

HTTP/1.1 204 No Content

Remove Tags from a Contact

Removes one or more tags from a contact. Supply the array of tag IDs you want to detach. A successful request returns HTTP 204 No Content.

DELETE /api/v1/contacts/{identifier}/tags

Path Parameters

string

required

Contact lookup string (id:<value>, email:<value>, or phone:<value>). Minimum length: 1 character.

Request Body

array of strings

required

Array of tag IDs to remove from the contact. Must contain between 1 and 100 elements. Each ID must be a numeric string matching \d+.

Code Examples

curl --request DELETE \
  --url "https://app.chatbotx.io/api/v1/contacts/email:user@example.com/tags" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "tagIds": ["15"]
  }'

import requests

identifier = "email:user@example.com"
url = f"https://app.chatbotx.io/api/v1/contacts/{identifier}/tags"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
payload = {"tagIds": ["15"]}

response = requests.delete(url, json=payload, headers=headers)
print(response.status_code)  # 204 on success

const identifier = 'email:user@example.com';
const options = {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ tagIds: ['15'] })
};

fetch(`https://app.chatbotx.io/api/v1/contacts/${identifier}/tags`, options)
  .then(res => {
    if (res.status === 204) console.log('Tags removed successfully');
  })
  .catch(err => console.error(err));

Response

HTTP/1.1 204 No Content

You can retrieve all tags currently applied to a contact by fetching the full contact object and reading its tags array. Use the Get Contact endpoint with the contact’s identifier. The tags array in the contact object includes the following fields for each tag:

string

required

Unique tag ID.

string

required

Human-readable tag name.

string (date-time)

required

When the tag was created.

string (date-time)

required

When the tag was last updated.

string

required

ID of the Workspace this tag belongs to.

Example Tag Object

{
  "id": "15",
  "name": "VIP",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "deletedAt": null,
  "folderId": null,
  "workspaceId": "ws123"
}

Before adding tags, call GET /api/v1/tags to confirm the tag IDs you want to use. Tag IDs are numeric strings and must exist in your Workspace before you can apply them to contacts.

Overview

Contacts

Custom Fields

Tags

Flows & Sequences

Broadcasts & Channels

Workspace

AI Agents

Contact Tags: Add, Remove, and List Contact Tags

Add Tags to a Contact

Path Parameters

Request Body

Code Examples

Response

Remove Tags from a Contact

Path Parameters

Request Body

Code Examples

Response

Example Tag Object

​Add Tags to a Contact

​Path Parameters

​Request Body

​Code Examples

​Response

​Remove Tags from a Contact

​Path Parameters

​Request Body

​Code Examples

​Response

​List Tags on a Contact

​Example Tag Object

Add Tags to a Contact

Path Parameters

Request Body

Code Examples

Response

Remove Tags from a Contact

Path Parameters

Request Body

Code Examples

Response

List Tags on a Contact

Example Tag Object