Skip to main content
POST
Enroll Lead (instruction bots)
Instruction bots are being retired. They are the older stage-based engine: a lead is enrolled into one and walks a sequence of stages. The engine that replaced them — goal bots — has no stages and no enrolment: you tag a lead and the bot handles their replies.Build new work on goal bots. These endpoints stay up for integrations already using them.
Puts a lead into an instruction bot at its first stage. Also answers on POST /api/goal-bots/{id}/enroll — that path stayed pointed at the instruction engine when the rest of /api/goal-bots moved, because published integrations depend on it.
Goal bots do not use this endpoint. To put a lead in front of a goal bot, add its trigger tag with PATCH /api/leads/{id}.

Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

Path parameter

string
required
The instruction id from GET /api/instructions. Not a goal bot id — the two live in different collections. A malformed id returns 400 Invalid instruction ID.

Request body

string
required
The lead to enrol. Missing or malformed returns 400 Valid leadId is required.

Example

Success (200 OK)

The lead is set to the instruction’s first stage, its turn counter is reset, and the instruction’s stats.totalEnrolled and stats.inProgress both increment.

Rules

A draft or paused instruction returns 400 Instruction is not active.
Enrolling a lead that is already enrolled anywhere returns 400 Lead is already enrolled in an instruction. Unenrol first with DELETE.
An instruction with no stages returns 400 Instruction has no steps.

Errors