# Lead Lifecycle Events


## dnc.created

Triggered when a phone number is added to the Do Not Contact (DNC) list. This can happen when a lead sends a carrier opt-out keyword or an API request is made to DNC a lead. DNCs are company-wide — they apply to all campaigns. The `campaignId` in the metadata refers to the campaign where the DNC originated.

```json
{
  "metadata": {
    "apiVersion": "2026-02-09",
    "eventType": "dnc.created",
    "campaignId": "abc456xyz",
    "eventTime": "2024-01-28T12:00:00.000Z"
  },
  "data": {
    "externalLeadId": "abc123",
    "phone": "+1234567890",
    "dncTimestamp": "2024-01-28T12:00:00.000Z"
  }
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `data.externalLeadId` | string? | Your external lead ID for the lead in the originating campaign |
| `data.phone` | string | E.164 formatted phone number |
| `data.dncTimestamp` | string | ISO 8601 timestamp of when the DNC occurred |

---

## campaign.lead_created

Triggered when a new lead is fully processed and posted to a campaign — after validation, cleaning, line type determination, and agent phone assignment are complete. This ensures the lead is confirmed SMS-capable before the notification fires.

```json
{
  "metadata": {
    "apiVersion": "2026-02-09",
    "eventType": "campaign.lead_created",
    "campaignId": "abc456xyz",
    "eventTime": "2024-01-28T12:00:00.000Z"
  },
  "data": {
    "phone": "+1234567890",
    "externalLeadId": "abc123",
    "firstName": "John",
    "lastName": "Doe",
    "isTestLead": true
  }
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `data.phone` | string | E.164 formatted phone number |
| `data.externalLeadId` | string? | Your external lead ID, if one was provided |
| `data.firstName` | string? | Lead's first name |
| `data.lastName` | string? | Lead's last name |
| `data.isTestLead` | boolean? | Only present when `true`. Omitted for regular leads. |