Tags

Tags are reusable colored labels applied to external contacts. This section covers the endpoints to manage the organization’s tag catalog and to apply and remove tags on a contact. For the in-product concept (inbox chips, contact panel, filter), see Contact Tags.

All endpoints require the Authorization: Bearer pk_... header. When there’s a JSON body, also include Content-Type: application/json.

Base URL: https://api.squados.io/v1

See Authentication to get your key, and Errors for the code reference.

The ContactTag model

Every tag is represented as:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "hot lead",
  "color": "orange"
}

Field	Type	Description
id	uuid	Tag identifier.
name	string	Tag name (unique within the organization).
color	string	One of: purple, blue, green, orange, red, pink, teal, gray.

Note

The catalog endpoints (/tags) are usable directly. The per-contact endpoints (/contacts/{contactId}/tags) need the contactId — the external contact’s UUID (external_contacts.id), the same identifier the admin panel and the agent tool use to reference the person.

---

GET /tags

Lists the organization’s tag catalog, ordered by name.

curl -X GET "https://api.squados.io/v1/tags" \
  -H "Authorization: Bearer pk_your_key_here"

Response — 200 OK

{
  "tags": [
    { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "awaiting payment", "color": "blue" },
    { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "customer", "color": "red" },
    { "id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789", "name": "hot lead", "color": "orange" }
  ]
}

---

PATCH /tags/{tagId}

Renames and/or recolors a catalog tag. The change applies to every contact that has the tag.

Path parameters

Name	Type	Description
tagId	uuid	Tag ID.

Request body (send at least one field)

Field	Type	Description
name	string	New tag name. Cannot be empty or collide with another tag.
color	string	New color: purple, blue, green, orange, red, pink, teal, or gray.

curl -X PATCH "https://api.squados.io/v1/tags/TAG_ID" \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "qualified lead", "color": "green"}'

Response — 200 OK

{
  "success": true,
  "id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789"
}

Relevant errors: 400 if the name is empty or the color invalid; 404 if the tag doesn’t exist in your organization; 409 if another tag already uses the given name.

---

DELETE /tags/{tagId}

Deletes the tag from the catalog and removes it from all contacts that had it. Cannot be undone.

Path parameters

Name	Type	Description
tagId	uuid	Tag ID.

curl -X DELETE "https://api.squados.io/v1/tags/TAG_ID" \
  -H "Authorization: Bearer pk_your_key_here"

Response — 200 OK

{ "success": true }

Relevant errors: 404 if the tag doesn’t exist in your organization.

---

GET /contacts/{contactId}/tags

Lists the tags applied to an external contact.

Path parameters

Name	Type	Description
contactId	uuid	External contact ID.

curl -X GET "https://api.squados.io/v1/contacts/CONTACT_ID/tags" \
  -H "Authorization: Bearer pk_your_key_here"

Response — 200 OK

{
  "tags": [
    { "id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789", "name": "hot lead", "color": "orange" },
    { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "customer", "color": "red" }
  ]
}

Relevant errors: 400 if the contactId is invalid; 404 if the contact doesn’t exist or doesn’t belong to your organization.

---

POST /contacts/{contactId}/tags

Applies a tag to the contact by name. If the tag doesn’t exist in the organization’s catalog yet, it is created automatically (with a color assigned deterministically from the name).

Path parameters

Name	Type	Description
contactId	uuid	External contact ID.

Request body

Field	Type	Required	Description
name	string	Yes	Name of the tag to apply (created if it doesn’t exist).

curl -X POST "https://api.squados.io/v1/contacts/CONTACT_ID/tags" \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "hot lead"}'

Response — 200 OK

{
  "tag": { "id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789", "name": "hot lead", "color": "orange" }
}

Relevant errors: 400 if name is empty or the contactId invalid; 404 if the contact doesn’t exist or doesn’t belong to your organization.

---

DELETE /contacts/{contactId}/tags/{tagId}

Removes the tag from the contact. The tag stays in the organization’s catalog and on other contacts.

Path parameters

Name	Type	Description
contactId	uuid	External contact ID.
tagId	uuid	ID of the tag to remove.

curl -X DELETE "https://api.squados.io/v1/contacts/CONTACT_ID/tags/TAG_ID" \
  -H "Authorization: Bearer pk_your_key_here"

Response — 200 OK

{ "success": true }

Relevant errors: 400 if any ID is invalid; 404 if the contact doesn’t exist or doesn’t belong to your organization.

Tip

Prefer testing in the browser? The same endpoints are in the interactive Swagger, under the Tags section — paste your token and fire the calls from there.