Carom · Tags · API reference

#The tag object

Returned by every tag endpoint, and embedded in records that carry tags. The per-type counts are filled in by List tags and Retrieve a tag; elsewhere they are null.

Attributes

idstring · uuid

Unique identifier for the tag.
namestring

The label. Unique within the account.
colorstring · nullable

Display color, such as #66b185.
descriptionstring · nullable

What the tag is for.
applicable_to_contactsboolean · nullable

Marks the tag as one for contacts and organizations. It doesn’t restrict where the tag can be applied. False unless set.
applicable_to_interactionsboolean · nullable

When true, Carom can apply the tag to threads automatically, based on their content. False unless set.
contact_count, organization_count, deal_count, thread_count, file_count, calendar_event_countinteger · nullable

Number of records of each type that carry the tag, across the whole account.

The tag object

{
  "id": "0f1e2d3c-4b5a-4968-8776-655443322110",
  "name": "Customer",
  "color": "#66b185",
  "description": "Accounts with a signed contract.",
  "applicable_to_contacts": true,
  "applicable_to_interactions": false,
  "contact_count": 38,
  "organization_count": 12,
  "deal_count": 9,
  "thread_count": 0,
  "file_count": 3,
  "calendar_event_count": 0
}

get/tags Read key

#List tags

Returns every tag in the account, with counts, in one response; the list isn’t paginated. It takes no parameters.

Returns

collectionobject
Show 2 child attributesHide child attributes
- recordsarray of tags
  
  Every tag in the account.
- total_resultsinteger
  
  Number of tags.

get/tags

curl https://api.carom.io/tags \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "collection": {
    "records": [
      {
        "id": "0f1e2d3c-4b5a-4968-8776-655443322110",
        "name": "Customer",
        "color": "#66b185",
        "contact_count": 38,
        …
      },
      {
        "id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
        "name": "Renewal Q4",
        "color": "#e0a43b",
        "contact_count": 14,
        …
      }
    ],
    "total_results": 2
  }
}

post/tags Write key

#Create a tag

Creates a tag in the account without applying it to anything. Tag names are unique within an account. To use a tag by name whether or not it exists, apply it to a record with tag.name.

Request body application/json

tagobjectrequired
Show 5 child attributesHide child attributes
- namestringrequired
- colorstring · nullable
- descriptionstring · nullable
- applicable_to_contactsboolean · nullabledefault false
- applicable_to_interactionsboolean · nullabledefault false

Returns

The new tag object, wrapped in tag, with status 201. Its counts are null.

Errors

400invalid_requesttag.name is missing or empty, or a field has the wrong type.
409tag_name_takenAnother tag in the account has that name. fields.name.code is taken.

post/tags

curl https://api.carom.io/tags \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "Renewal Q4",
      "color": "#e0a43b",
      "description": "Contracts that renew between October and December."
    }
  }'

Response201

{
  "tag": {
    "id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
    "name": "Renewal Q4",
    "color": "#e0a43b",
    "description": "Contracts that renew between October and December.",
    "applicable_to_contacts": false,
    "applicable_to_interactions": false,
    "contact_count": null,
    …
  }
}

get/tags/{id} Read key

#Retrieve a tag

Returns a single tag with its counts.

Path parameters

idstring · uuidrequired

The tag’s id.

Returns

The tag object, wrapped in tag.

Errors

404record_not_foundNo tag with that id in your account.

get/tags/{id}

curl https://api.carom.io/tags/0f1e2d3c-4b5a-4968-8776-655443322110 \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "tag": {
    "id": "0f1e2d3c-4b5a-4968-8776-655443322110",
    "name": "Customer",
    "color": "#66b185",
    "contact_count": 38,
    "organization_count": 12,
    "deal_count": 9,
    …
  }
}

patch/tags/{id} Write key

#Update a tag

Changes a tag. Any user in the account can edit any tag, and the change shows on every record that carries it. Send only the fields you want to change; the rest are left as they are.

Path parameters

idstring · uuidrequired

The tag’s id.

Request body application/json

tagobjectrequired

Any of the attributes accepted by Create a tag, all optional. name can’t be empty.

Returns

The updated tag object, wrapped in tag. Its counts are null.

Errors

400invalid_requesttag.name is empty, or a field has the wrong type.
404record_not_foundNo tag with that id in your account.
409tag_name_takenAnother tag in the account has that name. fields.name.code is taken.

patch/tags/{id}

curl -X PATCH https://api.carom.io/tags/7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "Renewal 2026 Q4",
      "applicable_to_contacts": true
    }
  }'

Response200

{
  "tag": {
    "id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
    "name": "Renewal 2026 Q4",
    "color": "#e0a43b",
    "applicable_to_contacts": true,
    …
  }
}

delete/tags/{id} Write key

#Delete a tag

Permanently deletes a tag and removes it from every record in the account. Requires an account admin; other keys get 403 permission_denied.

To merge one tag into another, pass replacement_tag_id. Every record that carries the deleted tag gets the replacement instead; records that already carry both just lose the deleted one.

Path parameters

idstring · uuidrequired

The tag to delete.

Request body application/json

replacement_tag_idstring · uuid · nullable

A tag to apply to every record that carries the deleted one.

Returns

An empty response with status 204.

Errors

403permission_deniedYour key’s user isn’t an account admin.
404record_not_foundNo tag with that id, or with replacement_tag_id, in your account.

delete/tags/{id}

curl -X DELETE https://api.carom.io/tags/7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "replacement_tag_id": "0f1e2d3c-4b5a-4968-8776-655443322110" }'

Response204

No content

post/{record_type}/{record_id}/taggings Write key

#Apply a tag

Applies a tag to a record. Send exactly one of tag_id, to apply an existing tag, or tag, to apply a tag by name. When no tag has that name, Carom creates it; when one does, Carom uses it as it is and ignores the color you sent.

Applying a tag the record already carries succeeds and returns the existing tagging.

Path parameters

record_typestringrequired

The plural resource name, one of:

contactsorganizationsdealsthreadsfilescalendar_events
record_idstring · uuidrequired

The id of that record. In the OpenAPI spec each route names it after its type, for example contact_id.
Show 6 pathsHide paths
- /contacts/{contact_id}/taggings
- /organizations/{organization_id}/taggings
- /deals/{deal_id}/taggings
- /threads/{thread_id}/taggings
- /files/{file_id}/taggings
- /calendar_events/{calendar_event_id}/taggings

Request body application/json

tag_idstring · uuid

An existing tag. Required unless you send tag.
tagobject

A tag by name. Required unless you send tag_id.
Show 2 child attributesHide child attributes
- namestringrequired
- colorstring
  
  Used only when Carom creates the tag.

Returns

taggingobject

The link between the tag and the record.
Show 7 child attributesHide child attributes
- idstring · uuid
- tag_idstring · uuid
- taggable_typestring
  The record type, singular.
  contactorganizationdealthreadfilecalendar_event
- taggable_idstring · uuid
  The record’s id.
- user_idstring · uuid · nullable
  The user who applied the tag.
- created_atstring · date-time · nullable
- tagtag · nullable
  The tag, without counts.

Errors

400invalid_requestYou sent both tag_id and tag, or neither.
404record_not_foundNo record of that type with that id is visible to your key, or no tag with that tag_id in your account.

post/contacts/{contact_id}/taggings

curl https://api.carom.io/contacts/1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41/taggings \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "Renewal Q4", "color": "#e0a43b" } }'

Response200

{
  "tagging": {
    "id": "3b4c5d6e-7f8a-4b9c-8d0e-1f2a3b4c5d6e",
    "tag_id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
    "taggable_type": "contact",
    "taggable_id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
    "user_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
    "created_at": "2026-09-10T16:31:08.415Z",
    "tag": {
      "id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
      "name": "Renewal Q4",
      "color": "#e0a43b",
      …
    }
  }
}

delete/{record_type}/{record_id}/taggings/{tag_id} Write key

#Remove a tag

Removes a tag from a record, named by the tag’s id rather than the tagging’s. The tag itself stays in the account; to delete it everywhere, use Delete a tag.

Removing a tag the record doesn’t carry succeeds and changes nothing.

Path parameters

record_type, record_idrequired

As on Apply a tag.
tag_idstring · uuidrequired

The id of the tag to remove.

Returns

An empty response with status 204.

Errors

404record_not_foundNo record of that type with that id is visible to your key.

delete/contacts/{contact_id}/taggings/{tag_id}

curl -X DELETE https://api.carom.io/contacts/1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41/taggings/7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response204

No content