Skip to content
Project BlueDocs
Popular pages
Guides / Getting startedQuickstartGet an API key, send your first message, and confirm delivery.API reference / MessagesPOSTSend a messageSend iMessage or SMS, with media, voice memos, and message effects./send-api-messageGuides / IntegrationsWebhooksReceive message and call events at your own endpoint.Guides / Getting startedAuthenticationCreate an API key and authenticate requests with a bearer token.AI tools / AI toolsMCP server & skillConnect Claude, Codex, Cursor, and other AI tools to Project Blue.
↑ ↓ Navigate↵ Openesc Close
Dashboard
For AI agents
View as Markdown

Enroll a contact

Starts a Workflow run for the given contact. The first step executes immediately. The response includes runId and the pb_line_id pinned to the run.

POST/enroll-flowBearer token

Because the first step runs before the response is written, the returned status is the state after that step. A run that begins with a wait comes back SLEEPING, and one that begins by asking a question comes back WAITING_REPLY — ACTIVE is the exception, not the rule. Statuses are uppercase: ACTIVE, SLEEPING, WAITING_REPLY, COMPLETED, CANCELLED, FAILED.

Request body

flowIdstring (UUID)Required
The Workflow id, as returned by GET /get-flows. An opaque UUID string — do not parse it. Must be 1 to 64 characters.
phoneNumberstringRequired
The contact's phone number. Accepts many formats — normalized to E.164.
pb_line_idstring (UUID)
Optional. Line to send from (lineId from GET /get-lines). When omitted, a line is selected automatically and pinned for the entire run.
variablesobject
Optional string values for this run. first_name, last_name, email, and company override the matching core tokens. Every other key is available as {{custom.<key>}}. first_name and last_name create the Project Blue contact only when no CRM is connected. CRM accounts never get a Project Blue contact from enrollment. Keys are letters, digits, and underscores; case insensitive; max 50 keys; max 500 characters per value. Example: {"first_name":"Jane","order_id":"123"}.
Personalization
Workflow messages can include {{first_name}}, {{last_name}}, {{email}}, {{company}}, {{phone}}, {{reply}} (the contact's last reply during a wait step), and {{custom.<key>}}. An optional fallback is written as {{first_name|there}}. Unknown tokens with no fallback render as an empty string.

At send time each token is filled in this order:

  1. variables sent on the enroll request
  2. the connected CRM contact (HighLevel, HubSpot, or Close), looked up live by the contact's phone number
  3. the Project Blue contact record, only for accounts with no connected CRM

{{custom.<key>}} reads from variables first, then from the CRM using the CRM's own field identifier. HighLevel uses the custom field key without the contact. prefix (the part GHL shows in {{contact.<key>}}). HubSpot uses the contact property internal name. Close uses the custom field name, case insensitive, on the contact or its lead. Accounts with no CRM get custom values from variables only.

Status codes

400
Invalid phone number, invalid pb_line_id, or no available lines
403
Contact has opted out
404
Flow not found or not published, or line not found
409
An active run already exists for this contact in this flow
API reference