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, externalId and workflowRuns, which are always present.

workflowRuns lists every workflow run that is currently open (active or paused) against the lead, oldest first. It is an empty array when the lead is not in any workflow run.

Payload Structure

event · string · required

The event type: lead.updated

data · object · required

The updated lead data (sparse — only changed fields included)

Show data

leadId · string · required

Unique identifier for the lead

externalId · string | null

External identifier for the lead (if set)

workflowRuns · array · required

Workflow runs currently open against this lead, oldest first

Show workflowRuns

id · string · required

ID of the workflow run

externalId · string | null

Your own identifier for the run, if you set one when creating it

workflowId · string · required

ID of the workflow the run belongs to

status · string · required

ACTIVE or PAUSED

firstName · string

Lead’s first name (only included if changed)

middleName · string

Lead’s middle name (only included if changed)

lastName · string

Lead’s last name (only included if changed)

phoneNumber · string

Lead’s phone number (only included if changed)

email · string

Lead’s email address (only included if changed)

businessName · string

Lead’s business name (only included if changed)

website · string

Lead’s website URL (only included if changed)

tags · string[]

List of tags attached to the lead

checklistItems · array

Array of updated checklist items (only included if checklist items changed)

Show checklistItems

checklistItemId · string

ID of the checklist item definition

checklistGroupCode · string

Code identifier for the checklist item’s group

checklistItemCode · string

Code identifier for the checklist item

value · 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": "..." }.

alternateValues · array | null

Alternative extracted values

Show alternateValues

value · string

The alternate extracted value

parentActionId · string | null

ID of the action that produced this value

status · string

Status of the checklist item: TODO, COMPLETED, INVALID, SKIPPED, NEEDS_REVIEW

updatedAt · string

ISO 8601 timestamp of the last update

documents · array

Array of documents associated with the checklist item (only for file-type fields)

Show documents

documentId · string

Unique identifier for the document

externalId · string | null

External identifier for the document

filename · string

Original filename

mimeType · string

MIME type of the document

size · number

File size in bytes

s3Bucket · string

S3 bucket name (only included if external S3 integration is configured)

s3Key · string

S3 object key (only included if external S3 integration is configured)

validationResult · object | null

Document validation results (if validation rules are configured)

Show validationResult

documentId · string

ID of the validated document

overallValid · boolean

Whether the document passed all validation rules

otherNotes · string | null

Additional notes from validation

validationResults · array

Individual rule results

Show validationResults

isValid · boolean

Whether this rule passed

ruleName · string

Name of the validation rule

ruleIndex · number

Index of the rule

isValidReason · string

Explanation of why the rule passed or failed

leadChecklistItemId · string

ID of the associated checklist item

overallValid · boolean | null

Whether the document passed all validation rules

actor · object | null

Workspace user who made this change. Returns null for actions not initiated by a workspace user.

Show actor

type · enum

Type of actor

id · string

Unique identifier for the user

name · string | null

Name of the user

email · string

Email address of the user

{
  "event": "lead.updated",
  "actor": {
    "type": "USER",
    "id": "8a1f6c2e-4b7d-4e2a-9c3f-1d5e6f7a8b9c",
    "name": "Jane Doe",
    "email": "[e-mail]"
  },
  "data": {
    "leadId": "50713355-df73-4077-9d84-dcda6da5729c",
    "externalId": "ext-lead-001",
    "workflowRuns": [
      {
        "id": "5d8c1f3a-7b2e-4c9d-8e1f-2a3b4c5d6e7f",
        "externalId": "crm-run-8813",
        "workflowId": "0f1e2d3c-4b5a-4968-8776-655443322110",
        "status": "ACTIVE"
      }
    ],
    "email": "[e-mail]",
    "tags": ["VIP", "priority-1"],
    "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
          }
        ]
      }
    ]
  }
}