Tags

Contact tags are reusable colored labels that describe a person across all their conversations. This section covers the endpoints to manage the organization’s tag catalog and to apply and remove tags on an external contact. For their use in the product, under Contact tags and Manage tags, see Contact Tags.

Do not confuse this resource with tags that describe a specific conversation or with campaign tags. The manage_tags native tool uses contact tags; manage_conversation_tags applies the same catalog vocabulary to the current conversation but stores a different association. This public API exposes only the catalog and external-contact associations.

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 case-insensitively 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 external contact’s UUID (external_contacts.id). The agent’s native tool receives that contact from the conversation context; it does not ask the model for the UUID.

---

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

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.

Send either name or color per call. The current runtime also accepts both fields and performs the rename before the color change, but the two changes are not atomic. If the second one fails, the first may already have been applied. An empty object or an object containing only unknown fields also receives 200 without changing the tag; do not use that behavior as validation.

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"}'

Response — 200 OK

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

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

Caution

In the current runtime, internal rename failures are returned as 409 and internal color-change failures as 400. After an unexpected error, query GET /tags before deciding whether to retry the call.

---

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: 400 invalid_request if tagId is not a valid UUID; 404 not_found if the tag doesn’t exist in your organization; 500 internal_error if deletion fails.

---

GET /contacts/{contactId}/tags

Lists the tags applied to an external contact. The response does not guarantee ordering; sort by name on the client when presentation requires a stable order.

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 invalid_request if contactId is invalid; 404 not_found if the contact doesn’t exist or doesn’t belong to your organization; 500 internal_error if reading the associations fails.

---

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 deterministic color derived from the name. Lookup is case-insensitive: reapplying the same name, even with different capitalization, reuses the stored tag and color. The association is also idempotent and does not create a duplicate.

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 invalid_request for malformed JSON, a missing/non-string/empty name, or an invalid contactId; 404 not_found if the contact doesn’t exist or doesn’t belong to your organization; 500 internal_error if applying the tag fails.

---

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

Removes the tag from the contact. The tag stays in the organization’s catalog and on other contacts. The operation is idempotent: valid IDs receive 200 even when the association no longer exists or tagId does not identify a tag applied to that contact.

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 invalid_request if either ID is invalid; 404 not_found if the contact doesn’t exist or doesn’t belong to your organization; 500 internal_error if removal fails.

Caution

The current runtime’s contact and tag existence checks ignore query errors. As a result, a 404 can represent a transient lookup failure. Confirm the resource with a fresh read before dropping it from local state.

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.

The current Swagger does not list the 500 responses implemented by five of these operations. Treat 5xx as transient, use backoff with jitter, and reconcile the result through GET /tags or GET /contacts/{contactId}/tags before repeating a mutation.