Skip to main content
PATCH /leads/tags Sync the full set of tags assigned to a lead. The request body is treated as the source of truth:
  • Tags present in tags that the lead does not have are created (find-or-create by slug) and assigned.
  • Tags currently assigned to the lead that are absent from tags are unassigned.
  • Send "tags": [] to clear all tags from the lead.
The lead can be identified by lead_id or email. The three fields (lead_id, email, tags) may also be nested anywhere inside the request body. The server will find them automatically. Authenticate every request with the X-API-Key header. See Authentication.

​
Request Body

FieldTypeRequiredDescription
lead_idstring (uuid)Yes*Lead ID
emailstringYes*Lead email (case-insensitive)
tagsstring[]YesComplete list of tag names that should be active on the lead. Missing tags are unassigned; new names are created. Use [] to clear all tags.
* Provide either lead_id or email. If both are present, lead_id takes precedence.

​
Responses

​
200 Tags synced successfully

{
  "success": true,
  "lead_id": "123e4567-e89b-12d3-a456-426614174000",
  "tags": [
    {
      "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "name": "VIP",
      "slug": "vip"
    },
    {
      "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "name": "Follow-up",
      "slug": "follow-up"
    }
  ],
  "added": ["aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"],
  "removed": ["cccccccc-cccc-cccc-cccc-cccccccccccc"]
}
FieldDescription
tagsFull current tag set after the sync
addedIDs of tags newly assigned by this request
removedIDs of tags unassigned by this request

​
400 Validation error

Returned when tags is not an array, or when neither lead_id nor email is provided.

​
401 Authentication error

See Authentication.

​
404 Lead not found

Returned when the lead does not exist or does not belong to your account.

​
500 Internal server error

Last modified on July 10, 2026