Add a tag to a contact

PUT /v1/contacts/{id}/tags/{tag}

Adds the tag to the contact. A tag your workspace hasn’t used before joins its tag list in grey.

Needs contacts:write.

Add the tag Wholesale

curl -X PUT https://app.soosh.io/v1/contacts/4ea0d485-435d-407f-837a-c7d67095f23a/tags/Wholesale \
  -H "Authorization: Bearer $SOOSH_API_KEY"

const res = await fetch('https://app.soosh.io/v1/contacts/4ea0d485-435d-407f-837a-c7d67095f23a/tags/Wholesale', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.SOOSH_API_KEY}`,
  },
});
console.log(await res.json());

import os
import requests

res = requests.put(
    "https://app.soosh.io/v1/contacts/4ea0d485-435d-407f-837a-c7d67095f23a/tags/Wholesale",
    headers={"Authorization": f"Bearer {os.environ['SOOSH_API_KEY']}"},
)
print(res.json())

Response200

{
  "id": "4ea0d485-435d-407f-837a-c7d67095f23a",
  "phone": "+919876543210",
  "whatsapp_user_id": null,
  "name": "Priya Sharma",
  "whatsapp_name": "Priya S",
  "attributes": {
    "customer_id": "8812",
    "city": "Pune",
    "orders": 3
  },
  "tags": [
    "VIP",
    "Wholesale"
  ],
  "marketing_opt_out": false,
  "number_id": "0f6d3c1e-5b7a-4c52-9a55-3f6a2d5c8b10",
  "chat": {
    "status": "open",
    "assigned_agent_id": "5b1d7d0e-3c2a-4f61-9a0e-6f8f3b2c1d40",
    "last_message_at": "2026-10-14T09:30:12.481Z",
    "last_inbound_at": "2026-10-14T09:12:40.117Z"
  },
  "created_at": "2026-10-14T09:05:11.420Z",
  "updated_at": "2026-10-14T10:12:03.518Z"
}

Every field of the contact object

Path parameters

id string · uuid

The contact’s ID.

tag string

The tag. Percent-encode characters such as / (Sales%2FEMEA).

1 to 50 characters.

Adding a tag twice

Adding a tag the contact already has changes nothing and still returns 200. contact.updated is sent only if the tag was added.

Returns

200 The contact object. The contact as it is now.

Errors

Besides the ones every request can get:

422invalid_fieldThe tag is too short or too long, or the contact already has 50 tags.

404not_foundThere is no contact with this ID in your workspace.