Skip to main content

Contact tags

Manage your account's list of contact tags: the tags your team picks from in the app and that segments filter on. To put a tag on a contact or take it off, use the tag endpoints in the Contacts API; they also create any tag that doesn't exist yet.

Conventions

Send your key in the x-api-key header and bodies as JSON with Content-Type: application/json. Requests without a valid key get 401 { "message": "Unauthorized" }; other errors look like { "error": "message" }. Tags belong to the account. Lists are plain arrays, paged with page (default 1) and limit (default 10, max 100; higher values are reduced to 100): keep increasing page until you get fewer results than your limit. See REST API for your API host and key.

Endpoints

The tag object​

Attributes
idstring
The tag id
namestring
The tag name, as it appears on contacts. Contacts store tag names, not ids.
canonicalstring
The name in lower case, used for search
createdAt, updatedAtstring
Timestamps

Other values saved on a tag in the app may also be returned.

The tag object
{
  "id": "Tg5pQ1wZr8",
  "name": "vip",
  "canonical": "vip",
  "createdAt": "2026-10-12T14:05:11.000Z",
  "updatedAt": "2026-10-12T14:05:11.000Z"
}

List tags​

GET/v1/contactTags
Query parameters
searchTextstring
Matches part of the tag name. Not case sensitive.
pageintegerdefault 1
limitintegerdefault 10
Max 100. Higher values are reduced to 100.

200 OK: a JSON array of tags. When it has fewer than limit items, it's the last page.

Errors
StatusBodyWhen
500{ "error": "Could not retrieve Contact Tags" }The request could not be completed. Retry.
Request
curl "https://api.whauto.chat/v1/contactTags?searchText=vip&page=1&limit=100" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"
Response 200
[
  {
    "id": "Tg5pQ1wZr8",
    "name": "vip",
    "canonical": "vip",
    "createdAt": "2026-10-12T14:05:11.000Z",
    "updatedAt": "2026-10-12T14:05:11.000Z"
  }
]

Create a tag​

POST/v1/contactTags
Body parameters
namestringrequired
The tag name. Saved exactly as sent, so case and spaces matter.

201 Created: the new tag.

This endpoint doesn't check for an existing tag with the same name, so calling it twice creates two tags. Search with GET /v1/contactTags?searchText= first if you're not sure the tag exists.

Errors
StatusBodyWhen
400{ "error": "name cannot be empty" }name is missing
500{ "error": "Could not create Contact Tag" }The request could not be completed. Retry.
Request
curl -X POST https://api.whauto.chat/v1/contactTags \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "black-friday-2026" }'
Response 201
{
  "id": "Tg9hR4kLm2",
  "name": "black-friday-2026",
  "canonical": "black-friday-2026",
  "createdAt": "2026-10-14T09:30:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}

Get a tag​

GET/v1/contactTags/{id}
Path parameters
idstringrequired
Tag id

200 OK: the tag.

Errors
StatusBodyWhen
404{ "error": "Contact Tag not found" }The tag isn't in your account
500{ "error": "Could not retrieve Contact Tag" }The request could not be completed. Retry.
Request
curl "https://api.whauto.chat/v1/contactTags/Tg5pQ1wZr8" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"
Response 200
{
  "id": "Tg5pQ1wZr8",
  "name": "vip",
  "canonical": "vip",
  "createdAt": "2026-10-12T14:05:11.000Z",
  "updatedAt": "2026-10-12T14:05:11.000Z"
}

Delete a tag​

DEL/v1/contactTags/{id}
Path parameters
idstringrequired
Tag id

Permanently deletes the tag from your account's tag list. It doesn't remove the tag name from contacts that already have it; use remove tags for that.

Errors
StatusBodyWhen
404{ "error": "Contact Tag not found" }The tag isn't in your account
500{ "error": "Could not delete Contact Tag" }The request could not be completed. Retry.
Request
curl -X DELETE https://api.whauto.chat/v1/contactTags/Tg9hR4kLm2 \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"
Response 200
{ "success": true }