Label contacts

Put one label on up to 5,000 contacts. Name an existing label by label_id, or give a name: an existing label with that name is reused, and a new one is created in the colour given. Contacts already carrying it are left alone.

POSThttps://app.trygtm.com/api/v1/contacts/labels

Scope: write
MCP tool: add_contact_labels

Headers

Idempotency-Keystringoptional: A key unique to this write, up to 255 characters. A retry carrying the same key returns the first response instead of running again. Kept for 24 hours.

Body

contact_idsstring[]required: Contact ids, up to 5,000 a call. Read them from list_contacts.
label_idstring | nulloptional: An existing label's id from list_labels. Use null when naming the label instead.
namestring | nulloptional: The label's name, reused if it exists and created if it does not.
colorstringoptionaldefault: zinc: The colour for a label this call creates. Ignored for an existing label.zincgraph-agentgraph-audiencegraph-companygraph-meetinggraph-notegraph-signalgraph-messagegraph-task

Request

curl -X POST https://app.trygtm.com/api/v1/contacts/labels \
  -H "Authorization: Bearer $TRYGTM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [
      "8f2a91c4-6d1e-4c0a-9a57-2f3b1c7e9d10"
    ]
  }'

Response

{
  "data": {
    "label": {
      "id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "name": "Warm",
      "color": "graph-meeting"
    },
    "created": false,
    "applied": 2,
    "already_labelled": 0,
    "ignored": 0
  }
}