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

# Add a tag to a contact

> Add a tag to a contact, by tag id or by name.

Every plan can use this endpoint.

Give exactly one of `tagId` or `name`. Adding a tag by `name` creates it in the contact's workspace if it doesn't exist yet. Adding a tag the contact already has does nothing and returns `"added": false`.

A tag added to a contact starts any [Contact tagged](https://docs.nedzo.ai/workflows/triggers/contact-tagged.md) workflow set to fire when a tag is added. A tag the contact already had starts nothing.

## Path Parameters

**contactId** `string` *required*

Contact UUID

## Body

**tagId** `string`

An existing tag's UUID. It must be a tag in the contact's workspace.

**name** `string`

A tag name, 1 to 100 characters after trimming. Names are not case-sensitive and are stored lowercase, so `"VIP"` finds or creates the tag `"vip"`.

```bash cURL theme={null}
curl -X POST "https://api.nedzo.ai/v1/contacts/123e4567-e89b-12d3-a456-426614174000/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "vip" }'
```

```json Response theme={null}
{
  "contactId": "123e4567-e89b-12d3-a456-426614174000",
  "tag": { "id": "9b2f6c1e-1d2a-4f3b-8c4d-5e6f7a8b9c0d", "workspaceId": "789e4567-e89b-12d3-a456-426614174000", "name": "vip", "createdAt": "2026-10-11T12:00:00Z", "updatedAt": "2026-10-11T12:00:00Z" },
  "added": true
}
```

## Errors

| Status | When |
| - | - |
| `400` | `contactId` or `tagId` is not a UUID, you sent both `tagId` and `name` or neither (`Give exactly one of tagId or name`), or `name` is empty or longer than 100 characters. |
| `404` | No contact has this id, the contact was deleted, it is not in this key's scope, or `tagId` is not a tag in the contact's workspace. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.