> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/branching-sequences/openapi.json](/docs/api/branching-sequences/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Sequences with conditions

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

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

Campaigns. 2 endpoints under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/branching-sequences/openapi.json](/docs/api/branching-sequences/openapi.json).

- `GET /v1/campaigns/{campaignId}/branching-sequence` - Get a campaign's sequence with conditions (`branching-sequences.get`): [/docs/api/branching-sequences/get.md](/docs/api/branching-sequences/get.md)
- `PUT /v1/campaigns/{campaignId}/branching-sequence` - Replace a campaign's sequence with conditions (`branching-sequences.replace`): [/docs/api/branching-sequences/replace.md](/docs/api/branching-sequences/replace.md)

## Get a campaign's sequence with conditions

`GET /v1/campaigns/{campaignId}/branching-sequence` - operationId `branching-sequences.get`

| Permission | Rate limit |
| --- | --- |
| Campaigns view | 12,000 requests a minute per API key |

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.

Needs the `sequence_conditions` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/branching-sequences/GET/v1/campaigns/%7BcampaignId%7D/branching-sequence)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | The campaign's id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Response 200

`data` is a `BranchingSequence`.

| Field | Type | Description |
| --- | --- | --- |
| `campaignId` | integer (int64) |  |
| `segments` | array of BranchingSegment | The tree, one entry per segment. Empty when the campaign has no sequence with conditions. |
| `workflowId` | integer (int64) | The campaign workflow the tree compiles to, saved as a draft. Absent when nothing is saved. |
| `modifiedAt` | string (date-time) | When the tree was last saved. Send it back as expectedModifiedAt. Absent when nothing is saved. |
| `conditions` | array of BranchingConditionAvailability | Every condition kind and whether this campaign can use it. |
| `stats` | array of BranchingNodeStats | Run counts per node id of the tree. |

### Request

```bash
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"
```

### Example response

```json
{
  "success": true,
  "data": {
    "campaignId": 812,
    "segments": [
      {
        "segmentId": 812,
        "steps": [
          {
            "id": "string",
            "type": "string",
            "waitDays": 1,
            "subject": "string",
            "body": "string",
            "text": "string",
            "condition": {},
            "timing": {},
            "yes": [],
            "no": [],
            "campaignId": 812
          }
        ]
      }
    ],
    "workflowId": 812,
    "modifiedAt": "2026-09-23T15:02:11Z",
    "conditions": [
      {
        "kind": "string",
        "available": true,
        "reason": "string"
      }
    ],
    "stats": [
      {
        "nodeId": "string",
        "reached": 1,
        "completed": 1
      }
    ]
  }
}
```

## Replace a campaign's sequence with conditions

`PUT /v1/campaigns/{campaignId}/branching-sequence` - operationId `branching-sequences.replace`

| Permission | Rate limit |
| --- | --- |
| Campaigns edit | 4,800 requests a minute per API key |

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.

Needs the `sequence_conditions` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/branching-sequences/PUT/v1/campaigns/%7BcampaignId%7D/branching-sequence)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | The campaign's id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `segments` | array of BranchingSegment | no | 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) | no | The `modifiedAt` from your last read. Send it so you do not overwrite an edit made since. |

### Response 200

`data` is a `BranchingSequence`.

| Field | Type | Description |
| --- | --- | --- |
| `campaignId` | integer (int64) |  |
| `segments` | array of BranchingSegment | The tree, one entry per segment. Empty when the campaign has no sequence with conditions. |
| `workflowId` | integer (int64) | The campaign workflow the tree compiles to, saved as a draft. Absent when nothing is saved. |
| `modifiedAt` | string (date-time) | When the tree was last saved. Send it back as expectedModifiedAt. Absent when nothing is saved. |
| `conditions` | array of BranchingConditionAvailability | Every condition kind and whether this campaign can use it. |
| `stats` | array of BranchingNodeStats | Run counts per node id of the tree. |

### Request

```bash
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"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "campaignId": 812,
    "segments": [
      {
        "segmentId": 812,
        "steps": [
          {
            "id": "string",
            "type": "string",
            "waitDays": 1,
            "subject": "string",
            "body": "string",
            "text": "string",
            "condition": {},
            "timing": {},
            "yes": [],
            "no": [],
            "campaignId": 812
          }
        ]
      }
    ],
    "workflowId": 812,
    "modifiedAt": "2026-09-23T15:02:11Z",
    "conditions": [
      {
        "kind": "string",
        "available": true,
        "reason": "string"
      }
    ],
    "stats": [
      {
        "nodeId": "string",
        "reached": 1,
        "completed": 1
      }
    ]
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### BranchingSegment

One segment's sequence. A null segmentId is the campaign's default sequence.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `segmentId` | integer (int64) | no | The segment these steps are for: a segment of the campaign. Null is the campaign's default sequence, for leads in no listed segment. |
| `steps` | array of BranchingNode | no | The steps in order. A condition or a move to another campaign ends the list. |

### BranchingConditionAvailability

Whether a condition kind can be used on this campaign.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | no |  |
| `available` | boolean | no |  |
| `reason` | string | no | Why it is unavailable: open_tracking_off when the campaign does not track opens, sends as plain text, or its workspace is past its billing grace. |

### BranchingNodeStats

Run counts of one node of the tree in the campaign workflow.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `nodeId` | string | no |  |
| `reached` | integer (int32) | no | Leads that reached this node. |
| `completed` | integer (int32) | no | Leads that finished this node. |

### BranchingNode

One node of the tree. type picks which fields apply: `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).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | The node's id: 1 to 40 of a-z, 0-9 and _, unique in the tree. Stats use it. |
| `type` | string | no | email, linkedin_connect, linkedin_message, condition or move_to_campaign. |
| `waitDays` | integer (int32) | no | Steps only: days to wait before the step, 0 to 30. Default 0. |
| `subject` | string | no | email only: the subject. |
| `body` | string | no | email only: the body. |
| `text` | string | no | linkedin_connect (the note, up to 300 characters, optional) and linkedin_message (the message). |
| `condition` | BranchingCondition | no | What a condition checks. |
| `timing` | BranchingTiming | no | How long a condition on what the lead does waits. |
| `yes` | array of BranchingNode | no | condition only: the steps when the condition is true. |
| `no` | array of BranchingNode | no | condition only: the steps when it is false. Must be empty with wait_until. |
| `campaignId` | integer (int64) | no | move_to_campaign only: the campaign the lead moves to, another live campaign of the workspace. |

### BranchingCondition

What a condition checks.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | no | email_opened, link_clicked, replied, meeting_booked, linkedin_invite_accepted, linkedin_message_engaged or unsubscribed (what the lead does); has_email, has_linkedin_url, has_phone, lead_score or custom_variable (the lead's data). |
| `variable` | string | no | custom_variable only: the variable's key. |
| `operator` | string | no | lead_score: gte, lte or eq. custom_variable: equals or contains. |
| `value` | object | no | lead_score: a number. custom_variable: the text to compare, case-insensitive. |

### BranchingTiming

How long a condition on what the lead does waits.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | string | no | within: the yes path when it happens within days, else the no path. wait_until: wait until it happens; there is no no path. |
| `days` | integer (int32) | no | within only: 1 to 30 days. |

All resources: [/docs.md](/docs.md).
