# Lead Events

Quantiv delivers instant notifications to your registered webhook(s) when specific events occur related to leads. These events include:

- `lead.created`
- `lead.updated`


## Lead Created

The `lead.created` event occurs when Lead is created via Widget flow. The event data has the following structure:


```json
{
  "id": "8b8638f9-755a-4311-ba88-6f760abb23c5",
  "event": "lead.created",
  "data": {
    "object": {
      "referenceId": "1354521a-e2d4-4a61-b610-db31016ead69",
      "widgetType": "roof-estimate",
      "leadId": "295d0482-5b03-48f2-8e1e-e52fa511a1b2",
      "flowId": "ac2e648c-ce9c-4d47-a554-2059491e7086",
      "leadStatus": "address_info_provided",
      "addressInfo": {
        "streetNumber": "123",
        "streetAddress": "William Street",
        "city": "New York",
        "state": "NY",
        "zip": "10038",
        "formattedAddress": "123 William Street, New York, NY",
        "lat": 40.7091708,
        "lng": -74.0069522
      }
    }
  },
  "timestamp": "2025-06-25T15:46:49.921Z",
  "mode": "prod",
  "version": "1.0",
  "metadata": {}
}
```

## Lead Updated

The `lead.updated` event occurs when Lead is updated while the Client's end user goes through Widget flow. The event data has the following structure:


```json
{
  "id": "75e2bb36-c5aa-42f9-8d67-12f00f2630a3",
  "event": "lead.updated",
  "data": {
    "object": {
      "referenceId": "1354521a-e2d4-4a61-b610-db31016ead69",
      "widgetType": "roof-estimate",
      "leadId": "295d0482-5b03-48f2-8e1e-e52fa511a1b2",
      "flowId": "ac2e648c-ce9c-4d47-a554-2059491e7086",
      "leadStatus": "project_details_provided",
      "addressInfo": {
        "streetNumber": "123",
        "streetAddress": "William Street",
        "city": "New York",
        "state": "NY",
        "zip": "10038",
        "formattedAddress": "123 William Street, New York, NY",
        "lat": 40.7091708,
        "lng": -74.0069522
      },
      "roofProjectDetails": {
        "reason": "Damaged by a storm",
        "startTime": "In a few weeks",
        "details": "123"
      }
    },
    "previousObject": {
      "referenceId": "1354521a-e2d4-4a61-b610-db31016ead69",
      "widgetType": "roof-estimate",
      "leadId": "295d0482-5b03-48f2-8e1e-e52fa511a1b2",
      "flowId": "ac2e648c-ce9c-4d47-a554-2059491e7086",
      "leadStatus": "address_info_provided",
      "addressInfo": {
        "streetNumber": "123",
        "streetAddress": "William Street",
        "city": "New York",
        "state": "NY",
        "zip": "10038",
        "formattedAddress": "123 William Street, New York, NY",
        "lat": 40.7091708,
        "lng": -74.0069522
      }
    }
  },
  "timestamp": "2025-06-25T15:47:47.376Z",
  "mode": "prod",
  "version": "1.0",
  "metadata": {}
}
```

## Sample Lead Status Transitions

As a lead progresses through the flow, `lead.updated` events will include a `status` field:

| Status | Description |
|  --- | --- |
| `address_info_provided` | Address submitted |
| `project_details_provided` | Project scope selected |
| `personal_info_and_estimate_provided` | Personal info + estimate collected |
| `contact_info_provided` | Callback preferences provided |


Each lead has a unique `leadId`, and every session is tracked via `leadFlowId`.
A new session (`leadFlowId`) is created every time the lead re-submits their address, while `leadId` remains consistent.