Contact tags

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.

Add a tag

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" }'

Response

{
  "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
}

API Reference

Workspaces

Agents

Phone Numbers

Contacts

Knowledge

Templates

Campaigns

Calls

Workflows

Conversations

Contact tags