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

# Patch Tags

<span class="badge--patch">PATCH</span> <code class="endpoint-url">/leads/tags</code>

Sync the full set of tags assigned to a lead. The request body is treated as the source of truth:

* Tags present in `tags` that the lead does not have are **created** (find-or-create by slug) and **assigned**.
* Tags currently assigned to the lead that are **absent** from `tags` are **unassigned**.
* Send `"tags": []` to **clear all tags** from the lead.

The lead can be identified by `lead_id` **or** `email`. The three fields (`lead_id`, `email`, `tags`) may also be nested anywhere inside the request body. The server will find them automatically.

Authenticate every request with the `X-API-Key` header. See [Authentication](/docs/en/api/authentication).

## Request Body

| Field     | Type          | Required  | Description                                                                                                                                   |
| --------- | ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `lead_id` | string (uuid) | **Yes\*** | Lead ID                                                                                                                                       |
| `email`   | string        | **Yes\*** | Lead email (case-insensitive)                                                                                                                 |
| `tags`    | string\[]     | **Yes**   | Complete list of tag names that should be active on the lead. Missing tags are unassigned; new names are created. Use `[]` to clear all tags. |

\* Provide either `lead_id` or `email`. If both are present, `lead_id` takes precedence.

## Responses

### `200` Tags synced successfully

```json theme={null}
{
  "success": true,
  "lead_id": "123e4567-e89b-12d3-a456-426614174000",
  "tags": [
    {
      "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "name": "VIP",
      "slug": "vip"
    },
    {
      "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "name": "Follow-up",
      "slug": "follow-up"
    }
  ],
  "added": ["aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"],
  "removed": ["cccccccc-cccc-cccc-cccc-cccccccccccc"]
}
```

| Field     | Description                                |
| --------- | ------------------------------------------ |
| `tags`    | Full current tag set after the sync        |
| `added`   | IDs of tags newly assigned by this request |
| `removed` | IDs of tags unassigned by this request     |

### `400` Validation error

Returned when `tags` is not an array, or when neither `lead_id` nor `email` is provided.

### `401` Authentication error

See [Authentication](/docs/en/api/authentication).

### `404` Lead not found

Returned when the lead does not exist or does not belong to your account.

### `500` Internal server error