Skip to Content
Integrations

Triggers

Rules that act when a signal happens: create, preview, edit, archive and read their stats.

Integrations9 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

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.

NameInTypeRequiredDescription
triggerIdpathinteger (int64)requiredThe trigger's id.

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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-Idheaderinteger (int64)optionalThe 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

GET/v1/triggerstriggers.list
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Returns the workspace's triggers. Filter them by campaignId and by status.

Errors:

  • 400 validation_failed: status, limit or cursor is invalid.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
limitqueryinteger (int32)optionalHow many triggers to return, from 1 to 200. Default 50.
cursorquerystringoptionalThe pagination.nextCursor of the previous page.
campaignIdqueryinteger (int64)optionalOnly the triggers that add contacts to this campaign.
statusquerystringoptionalOnly triggers with this status: active, paused or archived.
Request
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

POST/v1/triggerstriggers.create
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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 a lead_uploaded or webhook_lead_received trigger 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.

FieldTypeRequiredDescription
campaignIdinteger (int64)requiredRequired. The campaign the trigger adds contacts to.
signalTypestringrequiredRequired. The signal type to watch, such as link_clicked, reply_received or job_change.
tierstringoptionalDeprecated: 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.
parametersstringoptionalThe 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.
audienceFilterstringoptionalThe 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.
cooldownMinutesinteger (int32)optionalMinutes before the trigger can fire again for the same contact, at least 1. Default 10080 (7 days).
maxAgeMinutesinteger (int32)optionalMinutes a firing may wait to be processed before Kenso drops it, from 1 to 10080. Default 1440 (1 day).
priorityinteger (int32)optionalWhen several triggers fire for the same person at once, the highest priority wins. Default 50.
stopSourceSequencebooleanoptionalTrue stops the contact's sequence in its current campaign when the trigger adds it. Default true.
switchCampaignToTriggerbooleanoptionalTrue 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.
Request
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

GET/v1/triggers/{triggerId}triggers.get
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

PATCH/v1/triggers/{triggerId}triggers.update
Permission
Campaigns edit
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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 changes signalType or campaignId, status is archived, 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.

Request
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

DELETE/v1/triggers/{triggerId}triggers.delete
Permission
Campaigns edit
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

Response 204
HTTP/1.1 204 No Content

Preview a trigger's matching companies

POST/v1/triggers/previewtriggers.preview
Permission
Campaigns edit
Rate limit
240 requests a minute per API key

Try it on developer.ken.so

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 for open_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, lines and basis. basis says how Kenso computed it: those people at the leads rate of POST /v1/credits/estimates.

Errors:

  • 400 validation_failed: signalType or parameters is invalid. For a signal type the preview does not cover, error.details[0].code is preview_not_supported.

Requires Campaigns edit.

Request body

application/json, optional.

FieldTypeRequiredDescription
signalTypestringrequiredRequired. The signal type to preview: fundraising, open_roles or company_headcount_growth.
parametersobjectrequiredRequired. The trigger's parameters as a JSON object, with the same keys a trigger stores.
limitinteger (int32)optionalHow many companies to return, from 1 to 25. Default 25.
cursorstringoptionalThe pagination.nextCursor of the previous page.
Request
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

POST/v1/triggers/{triggerId}/test-firetriggers.test-fire
Permission
Campaigns edit
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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: contactId is 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].code is test_fire_not_supported.
  • 404 not_found: the workspace has no trigger with this id.

Requires Campaigns edit.

Parameters

NameInTypeRequiredDescription
triggerIdpathinteger (int64)requiredThe trigger to test.

Request body

application/json, optional.

FieldTypeRequiredDescription
contactIdinteger (int64)requiredRequired. The contact the sample signal is about. It must be in the workspace.
campaignIdinteger (int64)optionalThe campaign the sample came from, checked against the trigger's audience filter. It must be in the workspace.
payloadobjectoptionalThe signal's data, a JSON object of at most 16 KB, such as {"clickedUrl":"https://example.com"}.
occurredAtstring (date-time)optionalWhen the sample happened, in ISO 8601, within the last 365 days and not in the future. Default now.
Request
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

GET/v1/triggers/{triggerId}/statstriggers.get-stats
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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: days is out of range.
  • 404 not_found: the workspace has no trigger with this id.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
daysqueryinteger (int32)optionalHow many days back to count, from 1 to 90. Default 7.
Request
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

GET/v1/triggers/{triggerId}/linkedin-engagementstriggers.list-linkedin-engagements
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key
Needs the linkedin_signals feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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, limit or cursor is invalid.
  • 404 not_found: the workspace has no trigger with this id.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
limitqueryinteger (int32)optionalHow many engagements to return, from 1 to 200. Default 50.
cursorquerystringoptionalThe pagination.nextCursor of the previous page.
statusquerystringoptionalOnly engagements with this status: new, imported, offered or skipped.
Request
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.


On this page