Patch Tags

PUT /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.

Request Body

Field	Type	Required	Description
lead_id	string (uuid)	Yes*	Lead ID
email	string	Yes*	Lead email (case-insensitive)
tags	string[]	Yes	Complete 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.

Examples

Sync by lead_id

curl -X PUT https://api.getnexor.ai/api/public/leads/tags \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "lead_id": "123e4567-e89b-12d3-a456-426614174000",
    "tags": ["VIP", "Follow-up"]
  }'

Sync by email

curl -X PUT https://api.getnexor.ai/api/public/leads/tags \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "email": "jane@example.com",
    "tags": ["Hot Lead"]
  }'

Clear all tags

curl -X PUT https://api.getnexor.ai/api/public/leads/tags \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "lead_id": "123e4567-e89b-12d3-a456-426614174000",
    "tags": []
  }'

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

Field	Description
tags	Full current tag set after the sync
added	IDs of tags newly assigned by this request
removed	IDs 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