> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theomnibot.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Contact Tags: Add, Remove, and List Contact Tags

> Manage tags on a ChatbotX contact with three endpoints: add tags to a contact, remove tags from a contact, and list all tags currently applied.

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`.

<Info>
  **POST** `/api/v1/contacts/{identifier}/tags`
</Info>

### Path Parameters

<ParamField path="identifier" type="string" required>
  Contact lookup string (`id:<value>`, `email:<value>`, or `phone:<value>`). Minimum length: 1 character.
</ParamField>

### Request Body

<ParamField body="tagIds" type="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+`.
</ParamField>

### Code Examples

<CodeGroup>
  ```bash curl theme={null}
  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"]
    }'
  ```

  ```python Python theme={null}
  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
  ```

  ```javascript JavaScript theme={null}
  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));
  ```
</CodeGroup>

### 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`.

<Info>
  **DELETE** `/api/v1/contacts/{identifier}/tags`
</Info>

### Path Parameters

<ParamField path="identifier" type="string" required>
  Contact lookup string (`id:<value>`, `email:<value>`, or `phone:<value>`). Minimum length: 1 character.
</ParamField>

### Request Body

<ParamField body="tagIds" type="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+`.
</ParamField>

### Code Examples

<CodeGroup>
  ```bash curl theme={null}
  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"]
    }'
  ```

  ```python Python theme={null}
  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
  ```

  ```javascript JavaScript theme={null}
  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));
  ```
</CodeGroup>

### Response

```
HTTP/1.1 204 No Content
```

***

## List Tags on a Contact

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](/api-reference/contacts/get-contact) endpoint with the contact's identifier.

The `tags` array in the contact object includes the following fields for each tag:

<ResponseField name="id" type="string" required>Unique tag ID.</ResponseField>
<ResponseField name="name" type="string" required>Human-readable tag name.</ResponseField>
<ResponseField name="createdAt" type="string (date-time)" required>When the tag was created.</ResponseField>
<ResponseField name="updatedAt" type="string (date-time)" required>When the tag was last updated.</ResponseField>
<ResponseField name="workspaceId" type="string" required>ID of the Workspace this tag belongs to.</ResponseField>

### Example Tag Object

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

<Tip>
  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.
</Tip>