Tags

Tags are simple named, optionally colored labels scoped to the company, used to mark contacts and conversations for later filtering, audience segmentation, and automation triggers. This section is CRUD for the tag catalogue itself.

Name uniqueness

A tag's name is unique within the company.

Attaching to contacts and conversations

Attaching/detaching a tag to a specific contact or conversation is done via the resource-specific endpoints (POST /contacts/{contact}/tags, POST /conversations/{conversation}/tags); this section is CRUD for the tag catalogue itself.

Create and update request fields

In create and update requests:

name — a required string of up to 255 characters.
color — an optional 6-digit hex code like #RRGGBB (or null).

Endpoints

Method	Path	Summary
GET	`/v1/tags` List the company's tags (with name search).	List the company's tags (with name search).
POST	`/v1/tags` Create a tag.	Create a tag.
PATCH	`/v1/tags/{tag}` Update a tag's name or color.	Update a tag's name or color.
DELETE	`/v1/tags/{tag}` Delete a tag.	Delete a tag.

Examples

Create a tag

Request

bash

curl -X POST "https://api.aisar.app/v1/tags" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vip",
    "color": "#22c55e"
  }'

Response

json

{
  "data": {
    "message": "Tag created.",
    "tag": {
      "id": 7,
      "company_id": 1,
      "name": "vip",
      "color": "#22c55e",
      "created_at": "2026-02-09T18:00:00Z",
      "updated_at": "2026-02-09T18:00:00Z"
    }
  }
}

List tags

Request

bash

curl -X GET "https://api.aisar.app/v1/tags?search=vip" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "data": [
    {
      "id": 7,
      "company_id": 1,
      "name": "vip",
      "color": "#22c55e",
      "created_at": "2026-02-09T18:00:00Z",
      "updated_at": "2026-02-09T18:00:00Z"
    }
  ]
}

Update a tag

Request

bash

curl -X PATCH "https://api.aisar.app/v1/tags/7" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "priority",
    "color": "#e11d48"
  }'

Response

json

{
  "data": {
    "message": "Tag updated.",
    "tag": {
      "id": 7,
      "company_id": 1,
      "name": "priority",
      "color": "#e11d48",
      "created_at": "2026-02-09T18:00:00Z",
      "updated_at": "2026-02-10T09:30:00Z"
    }
  }
}