Sequence Triggers API

Create and manage sequence triggers that fire when a lead completes a specific series of events within a time window. Use sequence triggers to detect multi-step buying signals like "visited pricing page, then downloaded whitepaper, then requested a demo."

GET /sequences

List all sequence triggers for the active Organizational Unit.

Request

No query parameters required.

Response

200 OK

{
  "sequences": [
    {
      "id": "seq-123",
      "name": "Buying Intent Sequence",
      "event_types": ["pricing_page_view", "whitepaper_download", "demo_request"],
      "window_seconds": 604800,
      "window_unit": "7 days",
      "ordered": true,
      "webhook_url": "https://hooks.example.com/leadvibe",
      "emails": ["sales@example.com"],
      "active": true,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}

Example

curl -X GET "https://api.leadvibe.com/sequences" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
401	Unauthorized	Check authentication token
500	Server Error	Contact support if persists

---

POST /sequences

Create a new sequence trigger.

Request

Parameter	Type	Required	Description
name	string	Yes	Sequence trigger name
event_types	array	Yes	Ordered list of event types that must occur
window_seconds	integer	Yes	Time window in seconds within which all events must occur
window_unit	string	No	Human-readable unit label for display (e.g., "7 days", "24 hours")
ordered	boolean	No	Whether events must occur in the specified order (default: false)
webhook_url	string	No	URL to receive the webhook payload when the sequence completes
emails	array	No	Email addresses to notify when the sequence completes
email_subject	string	No	Custom subject line for email notifications
email_preheader	string	No	Preheader text for email notifications
email_message	string	No	Custom message body included before lead metadata in the email

Request Body

{
  "name": "Buying Intent Sequence",
  "event_types": ["pricing_page_view", "whitepaper_download", "demo_request"],
  "window_seconds": 604800,
  "window_unit": "7 days",
  "ordered": true,
  "webhook_url": "https://hooks.example.com/leadvibe",
  "emails": ["sales@example.com"]
}

Response

201 Created

{
  "id": "seq-456",
  "name": "Buying Intent Sequence",
  "event_types": ["pricing_page_view", "whitepaper_download", "demo_request"],
  "window_seconds": 604800,
  "ordered": true,
  "active": true,
  "created_at": "2025-01-15T10:30:00Z"
}

Example

curl -X POST "https://api.leadvibe.com/sequences" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Buying Intent Sequence",
    "event_types": ["pricing_page_view", "whitepaper_download", "demo_request"],
    "window_seconds": 604800,
    "window_unit": "7 days",
    "ordered": true,
    "webhook_url": "https://hooks.example.com/leadvibe"
  }'

Common Errors

Status	Meaning	Solution
400	Bad Request	Missing required fields or invalid values
401	Unauthorized	Check authentication token

---

Webhook Payload

When a sequence trigger fires, the webhook receiver gets a JSON payload with the matching events, the event sequence, and metadata about the trigger that fired.

{
  "trigger": {
    "id": "seq-456",
    "name": "Buying Intent Sequence",
    "type": "sequence"
  },
  "lead_id": "ld_123",
  "sequence": ["pricing_page_view", "whitepaper_download", "demo_request"],
  "events": [
    {
      "id": "evt-001",
      "event_type": "pricing_page_view",
      "created_at": "2025-01-10T09:00:00Z"
    },
    {
      "id": "evt-002",
      "event_type": "whitepaper_download",
      "created_at": "2025-01-12T14:30:00Z"
    },
    {
      "id": "evt-003",
      "event_type": "demo_request",
      "created_at": "2025-01-14T11:00:00Z"
    }
  ]
}

Payload Fields

Field	Type	Description
trigger	object	Metadata about the trigger that fired
trigger.id	string	Unique trigger identifier
trigger.name	string	Trigger name
trigger.type	string	Always "sequence" for sequence triggers
lead_id	string	The lead who completed the sequence
sequence	array	The ordered list of event types being watched
events	array	The engagement events that satisfied the sequence

---

Understanding Sequence Logic

Ordered vs. Unordered

• Ordered (ordered: true): Events must occur in the exact order specified. If a lead downloads a whitepaper before visiting the pricing page, the sequence is not matched.
• Unordered (ordered: false): All events must occur within the time window, but in any order.

Time Windows

The window_seconds field defines how long the system looks back for matching events:

Window	Seconds	Typical Use
1 hour	3600	Real-time session behavior
24 hours	86400	Same-day engagement
7 days	604800	Weekly buying signals
30 days	2592000	Monthly research patterns

---

Notes

• Sequence triggers are OU-scoped like all lead data
• A sequence fires once per lead per completed sequence
• All events in the sequence must occur within the window_seconds time frame
• Provide webhook_url for system-to-system integrations or emails for human notifications (or both)

Related Endpoints

• Sequence Trigger by ID - Update, delete, and simulate sequence triggers
• Milestone Triggers - Single-event score threshold triggers
• Sequence Events - View completed sequence events