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

# Contact tags

> List, create, rename and delete tags, and add or remove a tag on a contact.

Every plan can use these endpoints. `workspaceId` is required for account API keys and inferred for workspace API keys.

| Method | Path | What it does |
| - | - | - |
| `GET` | `/v1/contacts/tags?workspaceId=&limit=&offset=` | List the workspace's tags, one page at a time |
| `POST` | `/v1/contacts/tags` | Create a tag: `{ "workspaceId", "name" }` |
| `PATCH` | `/v1/contacts/tags/{tagId}` | Rename a tag: `{ "name" }` |
| `DELETE` | `/v1/contacts/tags/{tagId}` | Delete a tag and remove it from every contact |
| `POST` | `/v1/contacts/{contactId}/tags` | Add a tag to a contact: `{ "tagId" }` or `{ "name" }` |
| `DELETE` | `/v1/contacts/{contactId}/tags/{tagId}` | Remove a tag from a contact |

The list is paged: `limit` (1 to 1,000, default 100) and `offset`, oldest first. It returns `{ items, total, limit, offset, hasMore }`; keep adding `limit` to `offset` while `hasMore` is true.

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 tag added** workflow. Removing one starts any **Contact tag removed** workflow, never a tag added one.

```bash Add a tag 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
}
```


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