Surge Trigger by ID API

Update, delete, preview, and simulate individual surge triggers.

PUT /surge-triggers/{id}

Update an existing surge trigger.

Request

Parameter	Type	Required	Description
`id`	string	Yes	Surge trigger identifier (path parameter)

Request Body

All fields are optional. Only provided fields will be updated.

Field	Type	Description
`name`	string	Trigger name
`active`	boolean	Whether the trigger is active

Response

204 No Content

Example

curl -X PUT "https://api.kenbun.io/surge-triggers/surge-123" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rapid Re-Engagement Alert",
    "active": true
  }'

Common Errors

Status	Meaning	Solution
400	Bad Request	Invalid field values
401	Unauthorized	Check authentication token
404	Not Found	Surge trigger does not exist or is not accessible

DELETE /surge-triggers/{id}

Delete a surge trigger. This action cannot be undone.

Request

Parameter	Type	Required	Description
`id`	string	Yes	Surge trigger identifier (path parameter)

Response

204 No Content

Successfully deleted.

Example

curl -X DELETE "https://api.kenbun.io/surge-triggers/surge-123" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
401	Unauthorized	Check authentication token
404	Not Found	Surge trigger does not exist or is not accessible

POST /surge-triggers/{id}/preview

Backtest a surge trigger against historical event data to see how it would have performed. Use this before activating a trigger to calibrate its sensitivity and estimate alert volume.

The preview scans your event history for the number of days you specify and returns a count of how many times the trigger would have fired, along with a sample of the leads that would have been flagged.

No notifications are sent and the trigger is not activated by calling this endpoint.

Request

Endpoint: POST /surge-triggers/{id}/preview

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Surge trigger identifier

Request Body

Field	Type	Required	Description
`days`	integer	No	Number of days of event history to scan (1–90, default: 30)

Example Request Body:

{
  "days": 30
}

Response

200 OK

Field	Type	Description
`would_fire_count`	integer	Number of times this trigger would have fired during the specified period
`sample_leads`	array of strings	Representative lead IDs that would have triggered it

Example Response:

{
  "would_fire_count": 5,
  "sample_leads": [
    "ld_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "ld_b2c3d4e5-f6a7-8901-bcde-f12345678901"
  ]
}

When to Use This

Before activating a new trigger: Understand the expected alert volume before going live
When tuning thresholds: Check how a change in configuration would affect historical firing rate
Quarterly review: Validate that a trigger is calibrated correctly relative to current lead activity patterns

Examples

Default 30-day backtest:

curl -X POST "https://api.kenbun.io/surge-triggers/surge-123/preview" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"days": 30}'

90-day backtest for a broader view:

curl -X POST "https://api.kenbun.io/surge-triggers/surge-123/preview" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"days": 90}'

Interpreting Results

`would_fire_count`	What to consider
0	Threshold may be too strict, or activity levels have been low. Try a longer `days` window or review the trigger configuration.
1–10 per month	Well-calibrated for high-signal alerting
10–50 per month	Reasonable for active alert channels; consider a cooldown window to reduce notification fatigue
50+ per month	Likely too sensitive — tighten the threshold or add lead filters to narrow the audience

Common Errors

Status	Meaning	Solution
400	Bad Request	`days` is outside the 1–90 range, or the request body is malformed
401	Unauthorized	Check authentication token
404	Not Found	Surge trigger does not exist or is not accessible
500	Server Error	Retry later or contact support if persistent

Notes

Preview results are calculated at the time of the request. Running the same preview a week later may return different results as new events accumulate.
The sample_leads array returns a representative subset, not necessarily all matching leads.
Previewing does not count toward your notification volume or rate limits.

POST /surge-triggers/{id}/simulate

Simulate a surge trigger against a specific lead's event history. Use this to confirm whether a trigger would fire for a particular lead and to see exactly which time windows in their history would have exceeded the threshold.

Unlike the /preview endpoint — which scans across all leads — this endpoint focuses on a single lead and returns the precise matched windows, making it ideal for per-lead debugging and calibration.

No notifications are sent and the trigger is not modified.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Surge trigger identifier

Request Body

Field	Type	Required	Description
`lead_id`	string	Yes	The Lead ID to simulate against
`days`	integer	No	Number of days of event history to scan (1–90, default: 30)

Example Request Body:

{
  "lead_id": "ld_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "days": 30
}

Response

200 OK

Field	Type	Description
`would_fire`	boolean	Whether the trigger would have fired for this lead at least once during the period
`total_matches`	integer	Number of time windows in which the threshold was exceeded
`message`	string	Plain-language summary of the result
`matched_windows`	array	List of specific windows where the threshold was exceeded (only present when `would_fire` is `true`)

matched_windows Entry:

Field	Type	Description
`window_start`	timestamp	Start of the matching time window (ISO 8601)
`window_end`	timestamp	End of the matching time window (ISO 8601)
`event_count`	integer	Number of events that occurred in this window

Example Response — Would Fire:

{
  "would_fire": true,
  "total_matches": 3,
  "message": "Trigger would have fired 3 time(s) for this lead in the last 30 days",
  "matched_windows": [
    {
      "window_start": "2025-01-10T14:00:00Z",
      "window_end": "2025-01-10T16:00:00Z",
      "event_count": 7
    },
    {
      "window_start": "2025-01-15T09:00:00Z",
      "window_end": "2025-01-15T11:00:00Z",
      "event_count": 6
    },
    {
      "window_start": "2025-01-22T18:00:00Z",
      "window_end": "2025-01-22T20:00:00Z",
      "event_count": 9
    }
  ]
}

Example Response — Would Not Fire:

{
  "would_fire": false,
  "total_matches": 0,
  "message": "Trigger would NOT have fired for this lead in the last 30 days. No windows exceeded the threshold of 5 events."
}

Example

curl -X POST "https://api.kenbun.io/surge-triggers/surge-123/simulate" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "ld_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "days": 30
  }'

When to Use This

Debugging: A surge trigger is firing for a lead unexpectedly — use simulate to see exactly which windows crossed the threshold
Calibration: Before activating a new trigger, test it against your most engaged lead to confirm the threshold is set appropriately
Verification: After tightening or loosening a trigger's configuration, confirm the change produces the expected behavior for a known lead

Difference from `/preview`

Endpoint	Scope	Returns
`POST /surge-triggers/{id}/preview`	All leads in your organization	Aggregate fire count and a sample of matching lead IDs
`POST /surge-triggers/{id}/simulate`	One specific lead	Whether it fires, how many times, and the exact matched time windows

Common Errors

Status	Meaning	Solution
400	Missing or invalid `lead_id`, or `days` out of range	Provide a valid `lead_id` and ensure `days` is between 1 and 90
401	Unauthorized	Check authentication token
404	Surge trigger or lead not found	Verify both the trigger ID and lead ID are correct and accessible
500	Server Error	Retry later or contact support if persistent

Notes

Preview and simulate results are calculated at the time of the request. Running the same request a week later may return different results as new events accumulate.
The sample_leads array on the /preview endpoint returns a representative subset, not necessarily all matching leads.
Neither previewing nor simulating sends notifications or counts toward your notification volume or rate limits.

Surge Triggers (list and create) — Manage surge triggers
Milestone Trigger by ID — Simulate and manage milestone triggers
Sequence Trigger by ID — Simulate and manage sequence triggers

PUT /surge-triggers/{id}​

Request​

Request Body​

Response​

Example​

Common Errors​

DELETE /surge-triggers/{id}​

Request​

Response​

Example​

Common Errors​

POST /surge-triggers/{id}/preview​

Request​

Path Parameters​

Request Body​

Response​

When to Use This​

Examples​

Interpreting Results​

Common Errors​

Notes​

POST /surge-triggers/{id}/simulate​

Path Parameters​

Request Body​

Response​

Example​

When to Use This​

Difference from /preview​

Common Errors​

Notes​

Related Endpoints​

PUT /surge-triggers/{id}

Request

Request Body

Response

Example

Common Errors

DELETE /surge-triggers/{id}

Request

Response

Example

Common Errors

POST /surge-triggers/{id}/preview

Request

Path Parameters

Request Body

Response

When to Use This

Examples

Interpreting Results

Common Errors

Notes

POST /surge-triggers/{id}/simulate

Path Parameters

Request Body

Response

Example

When to Use This

Difference from `/preview`

Common Errors

Notes

Related Endpoints