Lemlist Developer Docs

curl --request POST \
  --url https://api.lemlist.com/api/sequences/{sequenceId}/steps/{stepId}/branches \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Marketing",
  "customField": "jobTitle",
  "customOperator": "contains",
  "customValue": "CMO"
}
'

{
  "sequenceId": "seq_Nb4vKq7Xm2Rd9Tz1L",
  "index": 2,
  "key": "customLeadInfo",
  "name": "Marketing",
  "customField": "variables.jobTitle",
  "customOperator": "contains",
  "customValues": [
    "CMO"
  ]
}

{
  "error": "emailStatusFilter is required to add a branch on condition \"hasEmailAddress\"",
  "code": "SEQUENCE_BRANCH_VALUE_REQUIRED"
}

"The authentication you supplied is incorrect"

"route is available starting emailPro plan"

{
  "error": "Condition branches are not enabled for this team",
  "code": "SEQUENCE_BRANCH_BETA_REQUIRED"
}

{
  "error": "Step not found",
  "code": "SEQUENCE_STEP_NOT_FOUND"
}

{
  "error": "You cannot add, remove or reorder branches once leads have entered the campaign",
  "code": "SEQUENCE_BRANCH_CAMPAIGN_RUNNING"
}

POST

sequences

{sequenceId}

steps

{stepId}

branches

curl --request POST \
  --url https://api.lemlist.com/api/sequences/{sequenceId}/steps/{stepId}/branches \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Marketing",
  "customField": "jobTitle",
  "customOperator": "contains",
  "customValue": "CMO"
}
'

{
  "sequenceId": "seq_Nb4vKq7Xm2Rd9Tz1L",
  "index": 2,
  "key": "customLeadInfo",
  "name": "Marketing",
  "customField": "variables.jobTitle",
  "customOperator": "contains",
  "customValues": [
    "CMO"
  ]
}

{
  "error": "emailStatusFilter is required to add a branch on condition \"hasEmailAddress\"",
  "code": "SEQUENCE_BRANCH_VALUE_REQUIRED"
}

"The authentication you supplied is incorrect"

"route is available starting emailPro plan"

{
  "error": "Condition branches are not enabled for this team",
  "code": "SEQUENCE_BRANCH_BETA_REQUIRED"
}

{
  "error": "Step not found",
  "code": "SEQUENCE_STEP_NOT_FOUND"
}

{
  "error": "You cannot add, remove or reorder branches once leads have entered the campaign",
  "code": "SEQUENCE_BRANCH_CAMPAIGN_RUNNING"
}

New to condition branches? Start with List Condition Branches, which explains how a step branches and how a branch is addressed.

The new branch is inserted just before the Else branch, so it becomes the lowest-priority branch of the step. Reorder afterwards with PATCH …/branches if it should be tested earlier. lemlist mints the empty sub-sequence the branch routes to and returns its id as sequenceId. Pass that id to POST /sequences/{sequenceId}/steps to fill the branch with steps.

A branch carries the value it tests

There are no blank branches: the body must say what this one matches, and a step’s condition is never sent here. conditionKey in the body is refused with SEQUENCE_BRANCH_CONDITION_KEY_NOT_ALLOWED — every branch of a step shares the step’s condition. Only four conditions host more than one branch:

Condition	Required in the body
`customLeadInfo`	`customValue` — unless `customOperator` is `empty` or `notEmpty`, which refuse one. The tested field is inherited from the step, so `customField` is optional
`hasScore`	nothing — the branch inherits a complete `>= 80` band. Send `scoreComparator` and `scoreThreshold` to give it its own
`hasEmailAddress`	`emailStatusFilter`
`aircallDone`	`callStatusFilter`

Any other condition answers 400: not-multi-capable when the condition supports a single branch plus Else, SEQUENCE_BRANCH_CONDITION_NOT_CONFIGURABLE when it has no branch parameters on the API.

On a customLeadInfo step every branch tests the same field — only the operator and the value differ. Sending a customField that differs from the step’s changes it on every branch at once.

When the campaign is running

Adding a branch changes the shape of the tree leads walk, so it is refused with 409 once leads have entered the campaign — see Editing a running campaign.

Authorizations

Authorization

string

header

required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Path Parameters

sequenceId

string

required

The unique identifier of the sequence holding the condition step

stepId

string

required

The unique identifier of the condition step, from GET /campaigns/{campaignId}/sequences

Body

application/json

name

string

The branch's display name. An empty string clears it, and lemlist falls back to labelling the branch "Branch 1", "Branch 2", … by rank. The Else branch cannot be named.

delayType

enum<string>

How a lead-action condition waits: within branches once the delay window is over, waitUntil parks the lead until the action happens, with no time bound. Ignored by the conditions that store no time window (customLeadInfo, hasEmailAddress).

Available options:

within,

waitUntil

delay

integer

Length of that time window, in days.

scoreComparator

enum<string>

hasScore only - how the lead's score is compared to scoreThreshold.

Available options:

$gte,

$lt

scoreThreshold

integer

hasScore only - the score this branch tests against.

Required range: 0 <= x <= 100

emailStatusFilter

enum<string>[]

hasEmailAddress only - the email statuses this branch matches. Required to add a branch on that condition.

Minimum array length: 1

Available options:

deliverable,

risky,

undeliverable,

unverified

callStatusFilter

string[]

aircallDone only - the call-status keys this branch matches. The keys are the team's own (defaults plus custom dispositions), so any non-empty string is accepted. Required to add a branch on that condition.

Minimum array length: 1

customField

string

customLeadInfo only - the field to test. A bare name reads as a lead variable (jobTitle becomes variables.jobTitle); prefix with fields. to test a contact field. Every branch of a step tests the same field, so changing it here changes it on all of them.

customOperator

enum<string>

customLeadInfo only - how the field is compared. equal and contains need a customValue; empty and notEmpty refuse one.

Available options:

equal,

contains,

empty,

notEmpty

customValue

string

customLeadInfo only - the value the field is compared to. Required for equal and contains, and refused for empty and notEmpty.

Response

The branch was added.

One branch of a condition step. Addressed by sequenceId - the sub-sequence its leads walk - never by position. The fields describing what the branch tests depend on the step's condition; the ones that do not apply are absent.

sequenceId

string

The branch's sub-sequence id, and its address on every branch endpoint. Pass it to POST /sequences/{sequenceId}/steps to add steps inside the branch.

index

integer

Execution rank among the non-fallback branches, starting at 0. The first branch whose test matches takes the lead. Absent on the Else branch, which always runs last.

fallback

boolean

true on the Else branch - the one that catches every lead no other branch matched. Absent on the others.

key

string

The condition the step tests. Every branch of a step shares it: a branch never carries a condition of its own.

name

string

The branch's display name, present only when someone has set one. lemlist labels the unnamed ones "Branch 1", "Branch 2", … and "Else"; those defaults are not stored and are not returned here.

delay

integer

Length of the time window the condition waits on the lead's action, in days. Only on the lead-action conditions that store one.

delayType

enum<string>

How the condition waits: within branches once the window is over, waitUntil parks the lead until the action happens, with no time bound.

Available options:

within,

waitUntil

scoreComparator

enum<string>

hasScore only - how the lead's score is compared to scoreThreshold.

Available options:

$gte,

$lt

scoreThreshold

integer

hasScore only - the score this branch tests against.

emailStatusFilter

enum<string>[]

hasEmailAddress only - the email statuses this branch matches.

Available options:

deliverable,

risky,

undeliverable,

unverified

callStatusFilter

string[]

aircallDone only - the call-status keys this branch matches.

customField

string

customLeadInfo only - the tested field, normalized: a lead variable reads back as variables.<name>, a contact field as fields.<name>. Every branch of the step tests the same field.

customOperator

enum<string>

customLeadInfo only - how the field is compared to the tested values.

Available options:

equal,

contains,

empty,

notEmpty

customValues

string[]

customLeadInfo only - every value this branch tests; the branch matches when any of them does. Empty for the empty and notEmpty operators.

selector

string

The raw stored condition selector, as JSON. Returned only when none of the fields above could describe the branch.

Getting started

Popular Resources

Endpoints

Objects & Definitions

Add Condition Branch

A branch carries the value it tests

When the campaign is running

Authorizations

Path Parameters

Body

Response

​A branch carries the value it tests

​When the campaign is running

Authorizations

Path Parameters

Body

Response

A branch carries the value it tests

When the campaign is running