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

# Set An Account's Tags

> Add, remove, or replace the tags on one account

One endpoint, three verbs, chosen with `mode`. The response is the account's
tags **read back after the write**, not an echo of what you sent: a
single-select group may have swapped out a tag you did not mention.

## Path Parameters

<ParamField path="companyId" type="string" required>
  The account's `company_id` (the company UUID), from
  [List Accounts](/api-reference/list-accounts).
</ParamField>

## Body

<ParamField body="tag_ids" type="string[]" required>
  Tag ids from a group whose `subject_type` is `account`, from
  [List Tag Groups](/api-reference/list-tag-groups).
</ParamField>

<ParamField body="mode" type="string" default="replace">
  * `replace` leaves the account carrying exactly `tag_ids` (within `group_id`
    when you send one). This is the picker's verb.
  * `add` keeps the account's other tags. This is the verb for an automation:
    it knows the one tag it means and must not drop what a person put there.
  * `remove` takes these tags off and leaves the rest.
</ParamField>

<ParamField body="group_id" type="string">
  Narrows a `replace` to one group, so replacing a Segment tag leaves every
  other group alone. Without it, `replace` means the account's whole set.
</ParamField>

<Warning>
  **A bare `replace` is the whole set.** `{"tag_ids": [], "mode": "replace"}`
  clears every tag on the account. Send `group_id` when you mean one group, or
  use `add` and `remove`.
</Warning>

<Note>
  **A single-select group swaps rather than stacks.** Adding a second tag from a
  `single` group replaces the one already there, which is what makes a status
  behave like a status.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://api.clustr-ai.com/api/public/record-tags/account/9c4d5e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"tag_ids": ["7f3e1a22-0c5d-4c1e-9f8a-2b4d6e8f0a12"], "mode": "add"}'
  ```

  ```bash cURL (replace one group) theme={null}
  curl -X PUT "https://api.clustr-ai.com/api/public/record-tags/account/9c4d5e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "tag_ids": ["7f3e1a22-0c5d-4c1e-9f8a-2b4d6e8f0a12"],
      "mode": "replace",
      "group_id": "5a1c3f88-92d4-4b0e-8e7a-1f2b3c4d5e60"
    }'
  ```

  ```python Python theme={null}
  import requests

  requests.put(
      f"https://api.clustr-ai.com/api/public/record-tags/account/{company_id}",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={"tag_ids": [tag_id], "mode": "add"},
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "tags": [
        {
          "id": "7f3e1a22-0c5d-4c1e-9f8a-2b4d6e8f0a12",
          "group_id": "5a1c3f88-92d4-4b0e-8e7a-1f2b3c4d5e60",
          "name": "Enterprise",
          "color": "#3B82F6"
        }
      ]
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": { "message": "unknown tag: 00000000-0000-0000-0000-000000000000", "code": "BAD_REQUEST" }
  }
  ```
</ResponseExample>