API Reference
Tags
Create and manage contact tags, then assign or remove them from individual contacts.
Overview
Tags are short labels you attach to contacts to group them for filtering, campaigns, and reporting. Each tag belongs to your client account and can be assigned to any number of contacts.
The Tag object
{
"id": 7,
"title": "VIP Customer",
"contacts_count": 34,
"created_at": "2026-02-10T08:00:00.000000Z"
}
| Field | Type | Description |
|---|---|---|
id | integer | Unique tag identifier |
title | string | Tag label |
contacts_count | integer|null | Number of contacts with this tag (included on list/show) |
created_at | string | ISO 8601 creation timestamp |
List tags
GET /api/v1/tags
Returns all tags for your account with contact counts.
Example
curl https://dashboard.skylightchat.com/api/v1/tags \
-H "X-Api-Key: ••••••••••••"
{
"success": true,
"data": [
{ "id": 5, "title": "Hot Lead", "contacts_count": 12 },
{ "id": 7, "title": "VIP Customer", "contacts_count": 34 }
]
}
Create a tag
POST /api/v1/tags
Request body
| Field | Type | Required |
|---|---|---|
title | string | ✓ Max 100 characters |
curl -X POST https://dashboard.skylightchat.com/api/v1/tags \
-H "X-Api-Key: ••••••••••••" \
-H "Content-Type: application/json" \
-d '{ "title": "VIP Customer" }'
Returns 201 Created with the tag object.
Get a tag
GET /api/v1/tags/{id}
Rename a tag
PUT /api/v1/tags/{id}
Request body
| Field | Type | Required |
|---|---|---|
title | string | ✓ |
Renaming a tag updates it everywhere it is used without re-assigning contacts.
Delete a tag
DELETE /api/v1/tags/{id}
Deletes the tag and removes it from all contacts that have it assigned. Returns 204 No Content.
Tag deletion is permanent and immediately affects all associated contacts. Consider renaming instead if you only want to relabel.
Add a tag to a contact
POST /api/v1/contacts/{id}/tags
Assign an existing tag or create a new one by title in a single request.
Request body
| Field | Type | Notes |
|---|---|---|
tag_id | integer | Use an existing tag by ID |
title | string | Creates the tag if it does not exist, then assigns it |
Provide either tag_id or title — not both.
# Assign by ID
curl -X POST https://dashboard.skylightchat.com/api/v1/contacts/42/tags \
-H "X-Api-Key: ••••••••••••" \
-H "Content-Type: application/json" \
-d '{ "tag_id": 7 }'
# Create + assign by title
curl -X POST https://dashboard.skylightchat.com/api/v1/contacts/42/tags \
-H "X-Api-Key: ••••••••••••" \
-H "Content-Type: application/json" \
-d '{ "title": "Newsletter Subscriber" }'
This operation is idempotent — assigning a tag the contact already has does nothing.
Remove a tag from a contact
DELETE /api/v1/contacts/{id}/tags/{tag_id}
Returns 204 No Content.