Triggers
Rules that act when a signal happens: create, preview, edit, archive and read their stats.
Path parameters
The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
triggerId | path | integer (int64) | required | The trigger's id. |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found. |
List triggers
/v1/triggerstriggers.list- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns the workspace's triggers. Filter them by campaignId and by status.
Errors:
400 validation_failed:status,limitorcursoris invalid.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | optional | How many triggers to return, from 1 to 200. Default 50. |
cursor | query | string | optional | The pagination.nextCursor of the previous page. |
campaignId | query | integer (int64) | optional | Only the triggers that add contacts to this campaign. |
status | query | string | optional | Only triggers with this status: active, paused or archived. |
curl -X GET "https://api.ken.so/v1/triggers?limit=50" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of Trigger. Each item has these fields. The response also carries pagination.
Show the 15 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Create a trigger
/v1/triggerstriggers.create- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Creates a trigger that watches one signal type for a campaign. The trigger starts as active.
campaignId and signalType are required. The campaign must be in trigger mode. To use a batch campaign, send switchCampaignToTrigger: true, and Kenso switches the campaign to trigger mode in the same step, so a failed create leaves the campaign as it was. The LinkedIn signal types, linkedin_post_engagement and linkedin_profile_view, take a campaign that is not in trigger mode and need the linkedin_signals feature. A linkedin_post_engagement trigger on pasted posts takes posts no older than 30 days, and a workspace has at most 10 such posts active.
parameters is a JSON string with the keys GET /v1/trigger-schemas lists for the signal type. Omitted fields take these defaults: cooldownMinutes 10080 (7 days), maxAgeMinutes 1440 (1 day), priority 50 and stopSourceSequence true. cooldownMinutes is at least 1, and maxAgeMinutes is from 1 to 10080. tier is deprecated and has no effect: every trigger is processed at the same speed.
A campaign has at most one active lead_uploaded trigger and one active webhook_lead_received trigger. Both types need email enrichment and email verification set up on the campaign, and Kenso creates a staging campaign for them, returned as stagingCampaignId.
Errors:
400 validation_failed: a field is missing or invalid, the parameters or audience filter do not fit the signal type, the campaign has the wrong mode, or alead_uploadedorwebhook_lead_receivedtrigger already exists or lacks email enrichment and verification.404 not_found: the campaign is not in the workspace.409 conflict: an active trigger of this type already exists for this campaign.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
campaignId | integer (int64) | required | Required. The campaign the trigger adds contacts to. |
signalType | string | required | Required. The signal type to watch, such as link_clicked, reply_received or job_change. |
tier | string | optional | Deprecated: no effect, so leave it out. Every trigger is processed at the same speed whatever its tier. Still accepted: minutes, hours or same_day. Default minutes. |
parameters | string | optional | The signal type's parameters as a JSON string, with the keys GET /v1/trigger-schemas lists. Omitted: {}, which a signal type with required parameters refuses. |
audienceFilter | string | optional | The campaigns whose contacts to watch, as a JSON string {"sourceCampaignIds":[1,2]}. The list cannot be empty, and every campaign must be in the workspace. Omitted: every campaign in the workspace. A job_change trigger requires it. |
cooldownMinutes | integer (int32) | optional | Minutes before the trigger can fire again for the same contact, at least 1. Default 10080 (7 days). |
maxAgeMinutes | integer (int32) | optional | Minutes a firing may wait to be processed before Kenso drops it, from 1 to 10080. Default 1440 (1 day). |
priority | integer (int32) | optional | When several triggers fire for the same person at once, the highest priority wins. Default 50. |
stopSourceSequence | boolean | optional | True stops the contact's sequence in its current campaign when the trigger adds it. Default true. |
switchCampaignToTrigger | boolean | optional | True switches a batch campaign to trigger mode as part of the create, so a failed create leaves the campaign as it was. Default false. Ignored for the LinkedIn signal types. |
curl -X POST "https://api.ken.so/v1/triggers" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"campaignId": 812,
"signalType": "link_clicked",
"tier": "minutes",
"parameters": "string",
"audienceFilter": "string",
"cooldownMinutes": 1,
"maxAgeMinutes": 1,
"priority": 1,
"stopSourceSequence": true,
"switchCampaignToTrigger": true
}'Response 201
data is a Trigger.
Show the 15 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a trigger
/v1/triggers/{triggerId}triggers.get- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns one trigger with its signal type, parameters and status.
Errors:
404 not_found: the workspace has no trigger with this id.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/triggers/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Trigger.
Show the 15 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update a trigger
/v1/triggers/{triggerId}triggers.update- Permission
- Campaigns edit
- Rate limit
- 12,000 requests a minute per API key
Changes the fields you send. Omitted fields keep their values.
The body can hold status (active or paused), parameters (a JSON string), audienceFilter (a JSON string, or null to clear the filter), cooldownMinutes, maxAgeMinutes, priority and stopSourceSequence. Their rules are the same as on create. tier (minutes, hours or same_day) is still accepted but deprecated: it has no effect. signalType and campaignId cannot change. To archive a trigger, use DELETE /v1/triggers/{triggerId}.
Errors:
400 validation_failed: a field has the wrong type or value, the body changessignalTypeorcampaignId,statusisarchived, or the trigger is archived.404 not_found: the workspace has no trigger with this id.409 conflict: an active trigger of this type already exists for the campaign.
Requires Campaigns edit.
Request body
application/json, optional: object.
The fields to change.
curl -X PATCH "https://api.ken.so/v1/triggers/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{}'Response 200
data is a Trigger.
Show the 15 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Archive a trigger
/v1/triggers/{triggerId}triggers.delete- Permission
- Campaigns edit
- Rate limit
- 12,000 requests a minute per API key
Archives the trigger, so it stops firing. An archived trigger cannot be changed or made active again, and it stays readable.
Errors:
404 not_found: the workspace has no trigger with this id.409 conflict: another request changed the trigger at the same time. Read it again and retry.
Requires Campaigns edit.
curl -X DELETE "https://api.ken.so/v1/triggers/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 204
HTTP/1.1 204 No ContentPreview a trigger's matching companies
/v1/triggers/previewtriggers.preview- Permission
- Campaigns edit
- Rate limit
- 240 requests a minute per API key
Runs a trigger's parameters against live company data and shows which companies would match, how many pass each step, and an estimated credit cost. Kenso saves nothing, fires nothing and charges nothing, and the preview does not use your export allowance. Use it to tune parameters before you create the trigger.
signalType is fundraising, open_roles or company_headcount_growth. parameters is a JSON object with the same keys a trigger stores. limit is from 1 to 25 companies, default 25. To read the next page, pass pagination.nextCursor as cursor.
Every page has:
companies: sample matching companies.total: the matching companies across all pages, or null foropen_roles.steps: the name, count and description of each filter step on this page, in order. The last step,max_contacts_per_company, is the most people the page can import.estimatedCredits:isEstimate(always true),leads,credits,totalMillicredits,linesandbasis.basissays how Kenso computed it: those people at the leads rate ofPOST /v1/credits/estimates.
Errors:
400 validation_failed:signalTypeorparametersis invalid. For a signal type the preview does not cover,error.details[0].codeispreview_not_supported.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
signalType | string | required | Required. The signal type to preview: fundraising, open_roles or company_headcount_growth. |
parameters | object | required | Required. The trigger's parameters as a JSON object, with the same keys a trigger stores. |
limit | integer (int32) | optional | How many companies to return, from 1 to 25. Default 25. |
cursor | string | optional | The pagination.nextCursor of the previous page. |
curl -X POST "https://api.ken.so/v1/triggers/preview" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"signalType": "fundraising",
"parameters": null,
"limit": 1,
"cursor": "eyJpZCI6ODE1fQ"
}'Response 200
data is a TriggerPreviewPage.
Show the 8 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Test a trigger with a sample signal
/v1/triggers/{triggerId}/test-firetriggers.test-fire- Permission
- Campaigns edit
- Rate limit
- 12,000 requests a minute per API key
Checks one sample signal of the trigger's own type the way Kenso checks a real one, and says whether the trigger would fire and why. Kenso queues no signal, starts no cooldown, records no firing, changes no counter, and sends or charges nothing. It does not replay recent signals: the sample is the only input.
contactId is required. campaignId feeds the audience filter. payload is the signal's JSON object, for example clickedUrl for link_clicked or classification for reply_received. occurredAt defaults to now.
Kenso runs every check in order: status, audience_filter, parameters and cooldown. rejectedBy names the first that failed. status fails for a paused or archived trigger and for one whose campaign was deleted. A real firing can still be suppressed later, for example by do not contact, the blocklist or a frequency cap.
Errors:
400 validation_failed:contactIdis missing, the contact or campaign is not in the workspace, or the body is invalid. For a signal type that only a scheduled scan produces,error.details[0].codeistest_fire_not_supported.404 not_found: the workspace has no trigger with this id.
Requires Campaigns edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
triggerId | path | integer (int64) | required | The trigger to test. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
contactId | integer (int64) | required | Required. The contact the sample signal is about. It must be in the workspace. |
campaignId | integer (int64) | optional | The campaign the sample came from, checked against the trigger's audience filter. It must be in the workspace. |
payload | object | optional | The signal's data, a JSON object of at most 16 KB, such as {"clickedUrl":"https://example.com"}. |
occurredAt | string (date-time) | optional | When the sample happened, in ISO 8601, within the last 365 days and not in the future. Default now. |
curl -X POST "https://api.ken.so/v1/triggers/812/test-fire" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"contactId": 812,
"campaignId": 812,
"payload": null,
"occurredAt": "2026-09-23T15:02:11Z"
}'Response 200
data is a TriggerTestFire.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a trigger's firing stats
/v1/triggers/{triggerId}/statstriggers.get-stats- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns how many times the trigger fired over the last days days, how many of those firings added the contact to the campaign, and how many Kenso suppressed, by reason.
days is from 1 to 90, default 7.
Errors:
400 validation_failed:daysis out of range.404 not_found: the workspace has no trigger with this id.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
days | query | integer (int32) | optional | How many days back to count, from 1 to 90. Default 7. |
curl -X GET "https://api.ken.so/v1/triggers/812/stats" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a TriggerStats.
Show the 5 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
List a trigger's LinkedIn engagements
/v1/triggers/{triggerId}/linkedin-engagementstriggers.list-linkedin-engagements- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
linkedin_signals feature on your workspace. Until it is on, calls answer 404.Returns the reactions, comments, replies and profile views a LinkedIn signal trigger found, newest first.
Each item names the person who engaged (actor), the post and comment when there is one, and for an imported item the person's contact in the campaign. skipReason says why Kenso skipped an item. Items also carry the reaction type, the comment and parent comment ids, the post text, the AI-assigned intent of a comment with its reason, and ownPost. A trigger of another signal type returns an empty list.
Errors:
400 validation_failed:status,limitorcursoris invalid.404 not_found: the workspace has no trigger with this id.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | optional | How many engagements to return, from 1 to 200. Default 50. |
cursor | query | string | optional | The pagination.nextCursor of the previous page. |
status | query | string | optional | Only engagements with this status: new, imported, offered or skipped. |
curl -X GET "https://api.ken.so/v1/triggers/812/linkedin-engagements?limit=50" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of LinkedInEngagement. Each item has these fields. The response also carries pagination.
Show the 19 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Integrations:Webhook endpointsWebhook deliveriesWebhook event typesEventsInbound webhooksCRM connectionsCRM syncCRM field mappingsCRM fieldsCRM importsCRM listsCRM pipelinesCRM recordsCRM sync issuesTrigger firingsTrigger schemasEvent subscriptionsEvent logAll resources