Skip to Content
Campaigns

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).

Campaigns2 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
campaignIdpathinteger (int64)requiredThe campaign'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.

Get a campaign's sequence with conditions

GET/v1/campaigns/{campaignId}/branching-sequencebranching-sequences.get
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key
Needs the sequence_conditions feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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

PUT/v1/campaigns/{campaignId}/branching-sequencebranching-sequences.replace
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key
Needs the sequence_conditions feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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_opened on 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 conflict with a stale_write detail on expectedModifiedAt: the sequence changed since your read.

Requires Campaigns edit.

Request body

application/json, optional.

FieldTypeRequiredDescription
segmentsarray of BranchingSegmentoptionalThe 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.
expectedModifiedAtstring (date-time)optionalThe modifiedAt from your last read. Send it so you do not overwrite an edit made since.
Request
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.


On this page