Skip to main content

Remove tags from a lead

DELETE 
/v1/leads/:leadID/tags

Detaches the named tags from one lead of your company. The request body is JSON and required: {"tags": ["a", "b"]} with 1 to 50 tag names, matched exactly (case-sensitive) against your company's tags (see GET /v1/tags). Names are trimmed and de-duplicated; an empty name is rejected.

Idempotent. A tag that is not on the lead, or that does not exist in your company at all, is reported in not_attached and is not an error, so a retry returns 200 with everything in not_attached. tags is the lead's full tag list after the removal.

Lead identifier. {leadID} is either the numeric lead id or the external_id, which is the data.id returned by POST /v1/webhooks/leads. Without id_type, a value that is not a positive integer is looked up as an external_id; a positive integer is looked up as both, and if it names two different leads the request fails with 409 lead_ambiguous: repeat it with ?id_type=lead_id or ?id_type=external_id. An external_id shared by more than one lead is also 409 lead_ambiguous; use the numeric id for those leads.

Right after intake. POST /v1/webhooks/leads is asynchronous: it answers 202 before the lead is stored. A follow-up call made immediately can get 404 for a few seconds; retry with exponential backoff (for example 1s, 2s, 4s, 8s) before treating the lead as missing.

Webhooks. When at least one tag is removed, a lead-updated event is sent to your webhook subscriptions. A subscriber that reacts to lead updates by calling this endpoint again can create a loop; make such automations idempotent.

Rate limited per company (default 600 requests per 10 minutes, shared with PUT /v1/leads/{leadID}/ai-handling).

Request​

Responses​

OK