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

# lead.updated

Triggered when a lead is updated.

## Event Type

`lead.updated`

## Description

This event is fired when lead fields or checklist items are updated. The payload is sparse — it only includes fields that changed, along with `leadId` and `externalId` which are always present.

## Payload Structure

<ResponseField name="event" type="string" required>
  The event type: `lead.updated`
</ResponseField>

<ResponseField name="data" type="object" required>
  The updated lead data (sparse — only changed fields included)

  <Expandable title="data">
    <ResponseField name="leadId" type="string" required>
      Unique identifier for the lead
    </ResponseField>

    <ResponseField name="externalId" type="string | null">
      External identifier for the lead (if set)
    </ResponseField>

    <ResponseField name="firstName" type="string">
      Lead's first name (only included if changed)
    </ResponseField>

    <ResponseField name="middleName" type="string">
      Lead's middle name (only included if changed)
    </ResponseField>

    <ResponseField name="lastName" type="string">
      Lead's last name (only included if changed)
    </ResponseField>

    <ResponseField name="phoneNumber" type="string">
      Lead's phone number (only included if changed)
    </ResponseField>

    <ResponseField name="email" type="string">
      Lead's email address (only included if changed)
    </ResponseField>

    <ResponseField name="businessName" type="string">
      Lead's business name (only included if changed)
    </ResponseField>

    <ResponseField name="website" type="string">
      Lead's website URL (only included if changed)
    </ResponseField>

    <ResponseField name="checklistItems" type="array">
      Array of updated checklist items (only included if checklist items changed)

      <Expandable title="checklistItems">
        <ResponseField name="checklistItemId" type="string">
          ID of the checklist item definition
        </ResponseField>

        <ResponseField name="checklistItemCode" type="string">
          Code identifier for the checklist item
        </ResponseField>

        <ResponseField name="value" type="string | number | object | null">
          Current value of the checklist item. Type depends on the field type: `string` for text fields, `number` for numeric fields, or an address object with the following structure: `{ "street": "...", "city": "...", "state": "...", "postalCode": "...", "country": "..." }`.
        </ResponseField>

        <ResponseField name="alternateValues" type="array | null">
          Alternative extracted values

          <Expandable title="alternateValues">
            <ResponseField name="value" type="string">
              The alternate extracted value
            </ResponseField>

            <ResponseField name="parentActionId" type="string | null">
              ID of the action that produced this value
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="status" type="string">
          Status of the checklist item: `TODO`, `COMPLETED`, `INVALID`, `SKIPPED`, `NEEDS_REVIEW`
        </ResponseField>

        <ResponseField name="updatedAt" type="string">
          ISO 8601 timestamp of the last update
        </ResponseField>

        <ResponseField name="documents" type="array">
          Array of documents associated with the checklist item (only for file-type fields)

          <Expandable title="documents">
            <ResponseField name="documentId" type="string">
              Unique identifier for the document
            </ResponseField>

            <ResponseField name="externalId" type="string | null">
              External identifier for the document
            </ResponseField>

            <ResponseField name="filename" type="string">
              Original filename
            </ResponseField>

            <ResponseField name="mimeType" type="string">
              MIME type of the document
            </ResponseField>

            <ResponseField name="size" type="number">
              File size in bytes
            </ResponseField>

            <ResponseField name="s3Bucket" type="string">
              S3 bucket name (only included if external S3 integration is configured)
            </ResponseField>

            <ResponseField name="s3Key" type="string">
              S3 object key (only included if external S3 integration is configured)
            </ResponseField>

            <ResponseField name="validationResult" type="object | null">
              Document validation results (if validation rules are configured)

              <Expandable title="validationResult">
                <ResponseField name="documentId" type="string">
                  ID of the validated document
                </ResponseField>

                <ResponseField name="overallValid" type="boolean">
                  Whether the document passed all validation rules
                </ResponseField>

                <ResponseField name="otherNotes" type="string | null">
                  Additional notes from validation
                </ResponseField>

                <ResponseField name="validationResults" type="array">
                  Individual rule results

                  <Expandable title="validationResults">
                    <ResponseField name="isValid" type="boolean">
                      Whether this rule passed
                    </ResponseField>

                    <ResponseField name="ruleName" type="string">
                      Name of the validation rule
                    </ResponseField>

                    <ResponseField name="ruleIndex" type="number">
                      Index of the rule
                    </ResponseField>

                    <ResponseField name="isValidReason" type="string">
                      Explanation of why the rule passed or failed
                    </ResponseField>
                  </Expandable>
                </ResponseField>

                <ResponseField name="leadChecklistItemId" type="string">
                  ID of the associated checklist item
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="overallValid" type="boolean | null">
              Whether the document passed all validation rules
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "event": "lead.updated",
    "data": {
      "leadId": "50713355-df73-4077-9d84-dcda6da5729c",
      "externalId": "ext-lead-001",
      "email": "newemail@example.com",
      "checklistItems": [
        {
          "checklistItemId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "checklistItemCode": "bank_statement",
          "value": "bank-statement-june.pdf",
          "alternateValues": [],
          "status": "NEEDS_REVIEW",
          "updatedAt": "2025-10-31T19:00:01.675Z",
          "documents": [
            {
              "documentId": "8349efe7-3c68-49c3-9411-f9affda0d03a",
              "externalId": null,
              "filename": "bank-statement-june.pdf",
              "mimeType": "application/pdf",
              "size": 153143,
              "validationResult": {
                "documentId": "8349efe7-3c68-49c3-9411-f9affda0d03a",
                "overallValid": false,
                "otherNotes": "Document shows account holder name as 'JOHN DOE'.",
                "validationResults": [
                  {
                    "isValid": true,
                    "ruleName": "First name should match",
                    "ruleIndex": 0,
                    "isValidReason": "Lead first name 'John' matches document name 'JOHN'."
                  },
                  {
                    "isValid": false,
                    "ruleName": "Statement must be dated within the last 3 months",
                    "ruleIndex": 1,
                    "isValidReason": "June 2025 is outside the required period. Valid months are October 2025, September 2025, August 2025."
                  }
                ],
                "leadChecklistItemId": "f830cc29-16ad-4c64-9fa8-f90f318f8dce"
              },
              "overallValid": false
            }
          ]
        }
      ]
    }
  }
  ```
</ResponseExample>