Create Tag

POST

/v1/tags/service-account

Creates a new tag that can be used to label and organize contacts or conversations within your workspace. Each tag has a name, an optional icon and description, and can be pinned for quick access.

Notes:

If a tag with the same name already exists in your workspace, the request fails with a clear error message — tag names are unique per workspace.

The description you send is saved, but it is not included in this response or any other tag response (List, Get, Update). There is currently no way to retrieve a tag's description through the API.

Request

Authorization

OAuth 2.0

Client Credentials

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

Authorization: Bearer ********************

Token URL: https://api.voxa.sa/connect/token

Scopes:

VoxaAPI-Access Voxa API as a service account

Body Params application/jsonRequired

Examples

Responses

🟢200OK

application/json

Tag created successfully.

Bodyapplication/json

🟠401Unauthorized

🟠403Forbidden

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.voxa.sa/v1/tags/service-account' \
--header 'Content-Type: application/json' \
--data '{
    "name": "VIP",
    "icon": "⭐",
    "description": "High-value customer",
    "isPinned": true
}'

Response Example

{
    "id": "3a1ebef0-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "VIP",
    "icon": "⭐",
    "isPinned": true,
    "creationTime": "2026-06-22T10:00:00Z"
}

Modified at 2026-06-22 16:07:56

Tag a conversation

Delete Tag