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

# Lead Track

> Understand deferred and non-deferred lead tracking with practical payload examples and implementation tips.

## What is a Lead Event?

Lead events help you:

* **Attribute leads** to the correct source and campaign
* **Understand journey quality** across different traffic channels
* **Improve ROI reporting** by linking verified actions to ad spend

Common lead events include:

| Event                | Description                            |
| -------------------- | -------------------------------------- |
| `signup_started`     | User registers for an account          |
| `onboarding_started` | User begins the onboarding flow        |
| `demo_booked`        | User schedules a product demo          |
| `info_requested`     | User submits a contact or inquiry form |

<img src="https://mintcdn.com/cutmeshort/DjXa7XIcYuaTMlzC/images/Attribution/Lead.png?fit=max&auto=format&n=DjXa7XIcYuaTMlzC&q=85&s=63630b3a1b57e5b492a00166f92777bd" alt="Lead event attribution flow" style={{ maxWidth: "720px", width: "100%", borderRadius: "12px", margin: "12px 0" }} width="2858" height="1668" data-path="images/Attribution/Lead.png" />

## Tracking Modes

There are two supported approaches. Choose based on whether your signup flow includes a verification step.

### Non-Deferred Tracking

Use this when you can **immediately trust** the lead action and no verification is needed.

* Send a **single event** right away
* Include `clickId` and `customerExternalId`
* Attribution is established immediately

### Deferred Tracking

Use this when **verification is required** before finalizing the lead (e.g., email or phone confirmation).

* Send **two events** — one before and one after verification
* Use `mode: "deferred"` on the first event
* Both events are linked via a shared `customerExternalId`

<Tip>
  **When in doubt, use deferred tracking.** It's safer to hold a lead open until verified than to count unconfirmed signups as conversions.
</Tip>

<img src="https://mintcdn.com/cutmeshort/WRUKHC6fhoVKHM9y/images/Attribution/deferred_lead_flow.png?fit=max&auto=format&n=WRUKHC6fhoVKHM9y&q=85&s=b67f83dfc945906843434bb7313523cd" alt="Deferred Lead event attribution flow" style={{ maxWidth: "720px", width: "100%", borderRadius: "12px", margin: "12px 0" }} width="2816" height="1536" data-path="images/Attribution/deferred_lead_flow.png" />

### Event 1 - Before Verification

Send this immediately when the user initiates signup.

<Tip>
  `clickId` is a unique identifier stored in cookies when our script detects `cms_rf` in the URL. See [article](/api-reference/endpoint/field) to know more.
</Tip>

**Required fields:**

* `clickId` — establishes attribution
* `mode: "deferred"` — marks this lead as pending
* `customerExternalId` — stable unique ID for the user

**Optional but recommended:**

* `customerName`, `customerEmail`, `customerAvatar` — enriches analytics

### Event 2 - After Verification

Send this once the user completes the verification step.

**Required fields:**

* `customerExternalId` — must match Event 1 exactly
* `eventName` — describes the verification action (e.g. `email_verified`)

<Warning>
  **Do not include `clickId` in Event 2.** Sending it again will cause duplicate attribution errors. The second event only links back to the first via `customerExternalId`.
</Warning>

## Payloads

### Non-Deferred Lead

A single event when no verification step is required.

```json theme={null}
{
  "clickId": "id_123",
  "eventName": "signup_started",
  "customerExternalId": "user_42",
  "timestamp": "2024-01-15T10:30:00Z",
  "customerName": "John Doe",
  "customerEmail": "john@example.com"
}
```

### Deferred Lead — Event 1 (Before Verification)

Initiates deferred lead tracking. Attribution is locked to the `clickId` here.

```json theme={null}
{
  "clickId": "id_123",
  "mode": "deferred",
  "eventName": "signup_started",
  "customerExternalId": "user_42",
  "timestamp": "2024-01-15T10:30:00Z",
  "customerName": "John Doe",
  "customerEmail": "john@example.com"
}
```

<Tip>
  Add user details (`customerName`, `customerEmail`) in this first event. They will be attached to the lead even before verification completes.
</Tip>

### Deferred Lead Event 2 (After Verification)

Confirms the lead. Must use the same `customerExternalId` as Event 1.

```json theme={null}
{
  "eventName": "email_verified",
  "customerExternalId": "user_42"
}
```

<Warning>
  The `customerExternalId` in Event 2 **must exactly match** the value sent in Event 1. Any mismatch will break the attribution chain and result in an unlinked lead.
</Warning>

## Fields

| Field                | Required           | Notes                                                          |
| -------------------- | ------------------ | -------------------------------------------------------------- |
| `clickId`            | Yes (Event 1 only) | Establishes attribution. Never re-send in follow-up events.    |
| `customerExternalId` | Yes (all events)   | Must be stable and consistent across the full user journey.    |
| `eventName`          | Yes (all events)   | Use descriptive names like `signup_started`, `email_verified`. |
| `mode`               | Deferred only      | Set to `"deferred"` on the first event of a deferred flow.     |
| `timestamp`          | Recommended        | ISO 8601 format. Improves sequencing and debugging.            |
| `customerName`       | Optional           | Enriches lead data in your analytics dashboard.                |
| `customerEmail`      | Optional           | Enriches lead data in your analytics dashboard.                |