Sequences with conditions
A sequence with conditions sends each contact down a yes or a no path: whether they opened, clicked, replied, booked a meeting or engaged on LinkedIn within a number of days, or what their data holds. A campaign has at most one, saved as a tree per segment. Saving compiles it to the campaign's workflow as a draft; launching the campaign publishes the workflow and starts its leads, and launch refuses a tree that cannot send (the launch operation names the reason).
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 |
|---|---|---|---|---|
campaignId | path | integer (int64) | required | The campaign'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. |
Get a campaign's sequence with conditions
/v1/campaigns/{campaignId}/branching-sequencebranching-sequences.get- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
sequence_conditions feature on your workspace. Until it is on, calls answer 404.Returns the saved tree (segments), the draft workflow it compiles to (workflowId), modifiedAt, whether each condition kind is available on this campaign (conditions; email_opened is unavailable with reason open_tracking_off when the campaign does not track opens, sends as plain text, or its workspace is past its billing grace), and run counts per node (stats). A campaign with no sequence with conditions returns empty segments and no workflowId.
Errors:
404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/campaigns/812/branching-sequence" \
-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 BranchingSequence.
Show the 6 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Replace a campaign's sequence with conditions
/v1/campaigns/{campaignId}/branching-sequencebranching-sequences.replace- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
sequence_conditions feature on your workspace. Until it is on, calls answer 404.Saves the tree you send and compiles it to the campaign's workflow as a draft. Kenso never publishes that workflow here. Send the modifiedAt from your last read as expectedModifiedAt.
Each segment entry has a segmentId (a segment of the campaign, or null for the default sequence) and steps. Step types: email (waitDays, subject, body), linkedin_connect (waitDays, text up to 300 characters), linkedin_message (waitDays, text), condition (condition, timing, yes, no) and move_to_campaign (campaignId). A condition or a move ends its list. Node ids are 1 to 40 of a-z, 0-9 and _, unique in the tree. waitDays is 0 to 30. At most 100 nodes and 6 levels of conditions.
Conditions on what the contact does (email_opened, link_clicked, replied, meeting_booked, linkedin_invite_accepted, linkedin_message_engaged, unsubscribed) need a step before them and a timing: within 1 to 30 days, or wait_until, which has no no path. Conditions on the contact's data (has_email, has_linkedin_url, has_phone, lead_score with operator gte, lte or eq and a number value, and custom_variable with variable, operator equals or contains and a text value) take no timing.
A tree with no condition removes the sequence with conditions in any campaign status, and the campaign keeps its email and LinkedIn sequences. Only a draft campaign takes a tree with conditions.
Errors:
400 validation_failed: the tree breaks a rule above (each detail names the field and the step),email_openedon a campaign that does not track opens, sends as plain text or whose workspace is past its billing grace (open_tracking_off), a tree with conditions on a campaign that is not a draft (campaign_not_draft), or, with provider tracks on, a tree with conditions on a campaign where a provider track has its own copy of a segment's sequence (provider_track_own_sequence; set every track back to the shared sequence first).404 not_found: the campaign does not exist in this workspace.409 conflictwith astale_writedetail onexpectedModifiedAt: the sequence changed since your read.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
segments | array of BranchingSegment | optional | The tree, one entry per segment: segmentId (null for the campaign's default sequence) and its steps. A tree with no condition removes the sequence with conditions. |
expectedModifiedAt | string (date-time) | optional | The modifiedAt from your last read. Send it so you do not overwrite an edit made since. |
curl -X PUT "https://api.ken.so/v1/campaigns/812/branching-sequence" \
-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 '{
"segments": [
{
"segmentId": 812,
"steps": [
{
"id": "string",
"type": "string",
"waitDays": 1,
"subject": "string",
"body": "string",
"text": "string",
"condition": {
"kind": "string",
"variable": "string",
"operator": "string",
"value": null
},
"timing": {
"mode": "string",
"days": 1
},
"yes": [
{}
],
"no": [
{}
],
"campaignId": 812
}
]
}
],
"expectedModifiedAt": "2026-09-23T15:02:11Z"
}'Response 200
data is a BranchingSequence.
Show the 6 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Campaigns:CampaignsEmail sequencesLinkedIn sequencesSegment email sequencesSegment LinkedIn sequencesSequence variablesSequence importSegmentsLead listsShare linksClient approvalsSending capacityAuto-pausesCampaign languagesLocalized stepsText translationMarket packsCountry complianceCampaign imagesAll resources