Skip to main content

​
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:
EventDescription
signup_startedUser registers for an account
onboarding_startedUser begins the onboarding flow
demo_bookedUser schedules a product demo
info_requestedUser submits a contact or inquiry form
Lead event attribution flow

​
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
When in doubt, use deferred tracking. It’s safer to hold a lead open until verified than to count unconfirmed signups as conversions.
Deferred Lead event attribution flow

​
Event 1 - Before Verification

Send this immediately when the user initiates signup. 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)
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.

​
Payloads

​
Non-Deferred Lead

A single event when no verification step is required. 
{
  "clickId": "id_123",
  "eventName": "signup_started",
  "customerExternalId": "user_42",
  "timestamp": "2024-01-15T10:30:00Z",
  "customerName": "John Doe",
  "customerEmail": "john@example.com",
  "customerAvatar": "https://example.com/avatar.jpg"
}

​
Deferred Lead — Event 1 (Before Verification)

Initiates deferred lead tracking. Attribution is locked to the clickId here. 
{
  "clickId": "id_123",
  "mode": "deferred",
  "eventName": "signup_started",
  "customerExternalId": "user_42",
  "timestamp": "2024-01-15T10:30:00Z",
  "customerName": "John Doe",
  "customerEmail": "john@example.com",
  "customerAvatar": "https://example.com/avatar.jpg"
}
Add user details (customerName, customerEmail) in this first event. They will be attached to the lead even before verification completes.

​
Deferred Lead Event 2 (After Verification)

Confirms the lead. Must use the same customerExternalId as Event 1. 
{
  "eventName": "email_verified",
  "customerExternalId": "user_42"
}
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.

​
Fields

FieldRequiredNotes
clickIdYes (Event 1 only)Establishes attribution. Never re-send in follow-up events.
customerExternalIdYes (all events)Must be stable and consistent across the full user journey.
eventNameYes (all events)Use descriptive names like signup_started, email_verified.
modeDeferred onlySet to "deferred" on the first event of a deferred flow.
timestampRecommendedISO 8601 format. Improves sequencing and debugging.
customerNameOptionalEnriches lead data in your analytics dashboard.
customerEmailOptionalEnriches lead data in your analytics dashboard.
customerAvatarOptionalURL to a user profile image.