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

# Leads

> Payload reference for lead.created, lead.updated, lead.sundry, lead.activity and lead.deleted webhooks.

# Leads

> New to webhooks? Start with **[Getting started](/getting-started)** (envelope, delivery, retries)
> and **[Verification](/verification)** (confirming a request came from Grow CRM). Those conventions
> apply to every event below and are not repeated here.

Leads expose all five keys plus an import key: `lead.created`, `lead.updated`, `lead.deleted`,
`lead.sundry`, `lead.activity`, `lead.imported`.

## The lead object

Every key except `.deleted` carries this shape, either flat (`.created`) or nested under `lead`
(`.updated`/`.sundry`):

```json theme={null}
{
  "id": 88,
  "title": "Acme Inc - Website Redesign",
  "value": "5000.00",
  "status": { "id": 2, "title": "Contacted", "color": "info" },
  "active_state": "active",
  "category": { "id": 3, "name": "Referral" },
  "source": "Website",
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@acme.example",
    "phone": "+1 555 0100",
    "company_name": "Acme Inc"
  },
  "converted": { "is_converted": false, "client_id": null, "date": null },
  "assigned": [ { "id": 34, "name": "John Smith" } ],
  "tags": ["hot"],
  "dates": { "created": "2026-07-10T09:00:00.000000Z", "updated": "2026-07-16T08:12:00.000000Z" }
}
```

| Field          | Type             | Notes                                                                                                                                                                                      |
| -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`           | integer          | `lead_id`.                                                                                                                                                                                 |
| `title`        | string           |                                                                                                                                                                                            |
| `value`        | string           | Decimal as string.                                                                                                                                                                         |
| `status`       | object           | `{ id, title, color }`.                                                                                                                                                                    |
| `active_state` | string           | `active` or `archived`.                                                                                                                                                                    |
| `category`     | object           | `{ id, name }`.                                                                                                                                                                            |
| `source`       | string\|null     |                                                                                                                                                                                            |
| `contact`      | object           | `first_name`, `last_name`, `email`, `phone`, `company_name`. There is no separate top-level `name`/`phone`/`email` — those sundry fields (below) still deliver the full object shown here. |
| `converted`    | object           | `is_converted` (bool), `client_id`, `date` — populated once the lead converts to a client.                                                                                                 |
| `assigned`     | array            | `[{ id, name }]`, one per assigned user.                                                                                                                                                   |
| `tags`         | array of strings |                                                                                                                                                                                            |
| `dates`        | object           | `created`, `updated` — both ISO 8601 with microseconds (`Lead` recasts these via `CREATED_AT`/`UPDATED_AT`).                                                                               |

## `lead.created`

Fires when a lead is created, **including via clone**. `data` is the full lead object above.

```json theme={null}
{
  "event": "lead.created",
  "id": 88,
  "created": "2026-07-16T08:00:00+00:00",
  "data": {
    "id": 88,
    "title": "Acme Inc - Website Redesign",
    "value": "0.00",
    "status": { "id": 1, "title": "New", "color": "default" },
    "active_state": "active",
    "category": { "id": 1, "name": "Default" },
    "source": null,
    "contact": { "first_name": "Jane", "last_name": "Doe", "email": null, "phone": null, "company_name": "Acme Inc" },
    "converted": { "is_converted": false, "client_id": null, "date": null },
    "assigned": [],
    "tags": [],
    "dates": { "created": "2026-07-16T08:00:00.000000Z", "updated": "2026-07-16T08:00:00.000000Z" }
  }
}
```

## `lead.updated`

Fires on a significant change. `data.change` tells you which; `data.lead` is the full object.

| `change`       | Fires when                                                         |
| -------------- | ------------------------------------------------------------------ |
| `edited`       | The main lead edit form is saved.                                  |
| `status`       | The lead's pipeline status changes (single or bulk status change). |
| `converted`    | The lead is converted to a client.                                 |
| `value`        | The lead's value is updated.                                       |
| `assigned`     | The lead's assigned user(s) change.                                |
| `active_state` | The lead is archived or restored.                                  |

```json theme={null}
{
  "event": "lead.updated",
  "id": 88,
  "created": "2026-07-16T08:05:00+00:00",
  "data": {
    "change": "converted",
    "lead": { "id": 88, "converted": { "is_converted": true, "client_id": 45, "date": "2026-07-16" }, "...": "..." }
  }
}
```

## `lead.sundry`

Fires on a minor, cosmetic field edit. `data.field` names it; `data.lead` is the full object (same
shape as `.updated`, just a lower-significance discriminator) — it is **not** a partial diff, so
`data.lead` reflects the whole record even though only one field changed.

| `field`         | Fires when                                      |
| --------------- | ----------------------------------------------- |
| `description`   | The lead's description is edited on its own.    |
| `title`         | The lead's title is edited on its own.          |
| `name`          | The lead's contact name is edited on its own.   |
| `tags`          | The lead's tags are changed.                    |
| `category`      | The lead's category is changed.                 |
| `phone`         | The lead's contact phone is edited on its own.  |
| `email`         | The lead's contact email is edited on its own.  |
| `source`        | The lead's source is edited.                    |
| `contacted`     | The lead's "last contacted" date is updated.    |
| `date_added`    | The lead's date-added value is edited.          |
| `organisation`  | The lead's organisation/company name is edited. |
| `custom_fields` | One or more custom field values are updated.    |

```json theme={null}
{
  "event": "lead.sundry",
  "id": 88,
  "created": "2026-07-16T08:07:00+00:00",
  "data": {
    "field": "description",
    "lead": { "id": 88, "title": "Acme Inc - Website Redesign", "...": "..." }
  }
}
```

## `lead.activity`

Fires when a child record on the lead changes.

| `type`              | `action`                                        | Item shape                                                                                                                                            |
| ------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `comment`           | `added`, `deleted`                              | `{ id, text, author, created }` — `author` is the commenter's first name only.                                                                        |
| `attachment`        | `added`                                         | `{ id, uniqueid, filename, created }`                                                                                                                 |
| `attachment`        | `deleted`                                       | `{ id }` only — the attachment record is already gone by the time this fires.                                                                         |
| `log`               | `added`, `updated`                              | `{ id, text, created }`                                                                                                                               |
| `log`               | `deleted`                                       | `{ id }` only — the log record is already gone by the time this fires.                                                                                |
| `checklist`         | `added`, `updated`, `deleted`, `status_changed` | `{ id, text, status, created }` — `status_changed` fires when an item is ticked or un-ticked; `status` is `pending` or `completed`.                   |
| `checklist_comment` | `added`, `deleted`                              | `{ id, checklist_id, text, author, created }` — kept separate from `comment` so a note on a checklist item is not mistaken for a comment on the lead. |

Leads have **two** separate attachment systems. The `attachment` rows above cover files added from
the lead's own attachment control. Files uploaded through the Files section against a lead also fire
`attachment`, but carry `{ id, uniqueid, filename }` and provide the full shape on delete as well
(that record is read before removal).

```json theme={null}
{
  "event": "lead.activity",
  "id": 88,
  "created": "2026-07-16T08:10:00+00:00",
  "data": {
    "type": "attachment",
    "action": "added",
    "item": { "id": 210, "uniqueid": "gr84y6837rh", "filename": "proposal.pdf", "created": "2026-07-16T08:10:00.000000Z" }
  }
}
```

```json theme={null}
{
  "event": "lead.activity",
  "id": 88,
  "created": "2026-07-16T08:11:00+00:00",
  "data": {
    "type": "attachment",
    "action": "deleted",
    "item": { "id": 210 }
  }
}
```

## `lead.deleted`

Fires after the lead is deleted. `data` is just the id — the record no longer exists to describe.

```json theme={null}
{
  "event": "lead.deleted",
  "id": 88,
  "created": "2026-07-16T08:15:00+00:00",
  "data": { "id": 88 }
}
```

## `lead.imported`

Fires when a bulk lead import finishes. Imported leads do **not** fire `lead.created` — see
**[Imports](/events#imports)** for the batch shape, batching rules and the fields common to every
import event.

Each lead record in the batch carries:

| Field        | Type         |
| ------------ | ------------ |
| `id`         | integer      |
| `title`      | string\|null |
| `first_name` | string\|null |
| `last_name`  | string\|null |
| `email`      | string\|null |
| `created`    | string       |

```json theme={null}
{
  "event": "lead.imported",
  "id": "8f3ka92m",
  "created": "2026-07-31T10:00:00+00:00",
  "data": {
    "import_ref": "8f3ka92m",
    "imported_by": 3,
    "batch": 1,
    "batch_count": 1,
    "totals": { "imported": 300, "skipped": 4, "errors": 0 },
    "records": [
      { "id": 88, "title": "Website redesign", "first_name": "Sam", "last_name": "Reyes", "email": "sam@example.com", "created": "2026-07-31T10:00:00.000000Z" }
    ]
  }
}
```