> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendora.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Lead Tags

> Add, remove, and list tags on leads for segmentation, GHL sync, and workflow routing.

## Overview

Tags are free-form labels you attach to leads. They're stored on the lead record and can be used for:

* **GHL sync**, push Sendora tags to GHL contact tags in real time
* **Segmentation**, filter leads in reports and lists
* **Workflow routing**, branch GHL workflows based on tags Sendora sets

Tags are case-sensitive strings, max 200 characters. A lead can have any number of tags.

## List tags on a lead

```bash theme={"dark"}
curl "https://api.sendora.ai/api/v1/public/leads/LEAD_ID/tags" \
  -H "X-API-Key: sk_live_..."
```

```json theme={"dark"}
{ "tags": ["ghl-prospect", "qualified", "demo-requested"] }
```

## Add tags

Adds one or more tags. Duplicates are ignored, safe to call repeatedly with the same tags.

```bash theme={"dark"}
curl -X POST "https://api.sendora.ai/api/v1/public/leads/LEAD_ID/tags" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["qualified", "high-intent"] }'
```

```json theme={"dark"}
{ "tags": ["ghl-prospect", "qualified", "high-intent"] }
```

## Remove a tag

```bash theme={"dark"}
curl -X DELETE "https://api.sendora.ai/api/v1/public/leads/LEAD_ID/tags/ghl-prospect" \
  -H "X-API-Key: sk_live_..."
```

```json theme={"dark"}
{ "tags": ["qualified", "high-intent"] }
```

## Replace all tags

To replace the full tag list, call `PATCH /leads/{id}` with a `custom_fields.tags` override:

```bash theme={"dark"}
curl -X PATCH "https://api.sendora.ai/api/v1/public/leads/LEAD_ID" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "custom_fields": { "tags": ["new-tag-a", "new-tag-b"] } }'
```

## GHL workflow integration

The GHL marketplace action **"Add Tags to Lead"** calls `POST /leads/{id}/tags` automatically. To trigger it from a GHL workflow:

1. Add the **Sendora** app action to your GHL workflow
2. Select **"Add Tags to Lead"**
3. Map the GHL contact's Sendora Lead ID and set the tags to apply

Tags flow from Sendora → GHL via the CRM sync queue (typically synced within 30 seconds).

## Webhook event

Subscribe to `lead.status_changed` to be notified when a lead's tags change:

```json theme={"dark"}
{
  "event": "lead.status_changed",
  "data": {
    "lead_id": "...",
    "field": "custom_fields.tags",
    "new_value": ["qualified", "high-intent"]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.