Workflow Configuration

A workflow is a directed graph of nodes connected by named routing events. You build the graph by submitting a JSON object as the configuration field on POST /v1/workflows (or PATCH /v1/workflows/{id}), then publish the workflow to make it executable. Once published, you trigger one run per candidate by calling POST /v1/workflows/{id}/runs.

This guide describes the configuration JSON schema, the supported node types, the routing events each node emits, the answer-route condition DSL for screening flows, the condition-node expression grammar, and the validation rules applied at publish time.

Lifecycle

Transitions:

• UNPUBLISHED → PUBLISHED via POST /v1/workflows/{id}/publish (succeeds only when validation passes).
• PUBLISHED ↔ PAUSED via pause / resume.
• Any state → ARCHIVED via archive. Irreversible.

Configuration Graph Shape

The configuration field on a workflow is a JSON-encoded string. Decoded, it has the following structure:

{
  "startNodeId": "screen-availability",
  "triggerSource": "API",
  "nodes": {
    "screen-availability": {
      "id": "screen-availability",
      "type": "screeningOutreach",
      "label": "Registered Nurse — availability and registration screen",
      "routing": {
        "onComplete": "engagement-booking-confirm",
        "onNotInterested": "engagement-nurture",
        "onDeliveryFailed": "engagement-email-fallback"
      },
      "config": {
        "agentName": "Cedar Health Recruiter",
        "agentTone": "PROFESSIONAL",
        "title": "RGN — availability and NMC screen",
        "channel": "SMS",
        "employerName": "Cedar Health Recruitment",
        "roleTitle": "Registered General Nurse (Band 5)",
        "location": "Various UK NHS trusts and care homes",
        "outreachContext": "Cedar Health places Band 5 RGNs into NHS trust bank-shifts and private care-home placements. Confirms NMC registration, region, and shift appetite up front.",
        "customTemplatedMessage": "Hi {{CANDIDATE_FIRST_NAME}}, this is Cedar Health Recruitment — we have new RGN shifts coming up that match your profile. A few quick questions to confirm your fit. Reply STOP to opt out.",
        "questions": [
          {
            "slug": "nmc-pin",
            "content": "Are you currently NMC-registered with an active PIN?",
            "answerRoutes": [
              {
                "when": { "field": "answerState", "op": "eq", "value": "any" },
                "actions": [{ "type": "CLOSE_CONVERSATION", "status": "PASSED_CRITERIA" }]
              }
            ]
          }
        ]
      }
    },
    "engagement-booking-confirm": {
      "id": "engagement-booking-confirm",
      "type": "engagementOutreach",
      "label": "Confirm booking",
      "routing": {},
      "config": {
        "agentName": "Cedar Health Recruiter",
        "agentTone": "PROFESSIONAL",
        "title": "Confirm booking",
        "channel": "SMS",
        "customTemplatedMessage": "Hi {{CANDIDATE_FIRST_NAME}}, your details are confirmed — our bookings team will reach out shortly with shifts that match your region. Reply STOP to opt out."
      }
    },
    "engagement-nurture": {
      "id": "engagement-nurture",
      "type": "engagementOutreach",
      "label": "Nurture for future roles",
      "routing": {},
      "config": {
        "agentName": "Cedar Health Recruiter",
        "agentTone": "PROFESSIONAL",
        "title": "Nurture for future roles",
        "channel": "EMAIL",
        "customTemplatedSubjectLine": "Cedar Health — we'll be in touch when the timing is right",
        "customTemplatedMessage": "Hi {{CANDIDATE_FIRST_NAME}}, thanks for letting us know — we'll keep you on file and reach out when you're ready to pick up RGN shifts."
      }
    },
    "engagement-email-fallback": {
      "id": "engagement-email-fallback",
      "type": "engagementOutreach",
      "label": "Email fallback for SMS-unreachable candidates",
      "routing": {},
      "config": {
        "agentName": "Cedar Health Recruiter",
        "agentTone": "PROFESSIONAL",
        "title": "Email fallback for SMS-unreachable candidates",
        "channel": "EMAIL",
        "customTemplatedSubjectLine": "Cedar Health Recruitment — RGN shifts in your region",
        "customTemplatedMessage": "Hi {{CANDIDATE_FIRST_NAME}}, we tried to reach you over SMS but couldn't get through. Reply to this email if you're interested and we'll send across the next steps."
      }
    }
  }
}

Notice that screen-availability routes three different exit events (onComplete, onNotInterested, onDeliveryFailed) to three different downstream nodes — each conversational outcome lands in its own follow-up journey. onOptedOut is intentionally omitted so opting out terminates the run cleanly. The agent persona is referenced by agentName + agentTone so the agent is created automatically on first publish — see Agent reference.

Top-level fields

Node fields

The routing map controls the graph topology. When a node completes, the engine looks up the emitted routing event in the node's routing map and transitions to the target node. If the emitted event is not present in the map and is required, validation fails at publish time. Routing events that have no target in the map are treated as terminal — the run completes when an unrouted event fires.

Supported Node Types

Three node types are available: screeningOutreach, engagementOutreach, and condition. The two outreach node types share the same channel set, the same routing events, and the same webhook outcome surface; they differ in the data they require on the config and in what context the conversation engine receives at send time. The engine produces PASSED_CRITERIA and FAILED_CRITERIA outcomes only when a question carries preferredAnswerText — see engagementOutreach for the full field-by-field comparison.

screeningOutreach

Sends a screening conversation to the candidate over SMS, WhatsApp, or email and collects answers to a fixed set of questions.

Config fields

Required core:

Agent reference

Every outreach node must reference an agent persona — the assistant that drives generated replies and signs messages. The persona is identified by the (agentName, agentTone) pair; both fields are required on every outreach node.

On publish, the workflow service looks up an organisation-level agent matching the pair. If one already exists it is reused; if not, it is created. The same pair across multiple nodes resolves to a single agent. This means a new integration can publish its first workflow without any prior agent provisioning — the persona is materialised automatically.

Validation rejects any outreach node missing either field with MISSING_AGENT_REFERENCE (one issue per missing field, so a config missing both surfaces both errors on a single attempt).

Channel and templating:

Optional context for the conversation engine (see Context the conversation engine uses to generate replies):

Optional lifecycle messages (copy the conversation engine uses at specific conversation transitions):

Optional pacing and auto-close:

Routing events

Optional events may be omitted from routing — when omitted the run terminates if that event fires.

Questions

Each question controls one prompt-answer step in the screening conversation.

Explicit-routing contract. Every question must declare its forward edge explicitly on every answer route. A route is valid only when its actions take one of these three canonical shapes:

1. [{ type: "CONTINUE", slug: "<sibling-slug>" }] — advance to a named sibling question within the same node.
2. [{ type: "CLOSE_CONVERSATION", status: "<status>" }, { type: "ROUTE_TO", nodeId: "<target>" }] — close the current conversation and hand off to another node.
3. [{ type: "CLOSE_CONVERSATION", status: "<status>" }] — terminate the run cleanly at this question.

Entry question is questions[0]. The first element of the questions array is the question the conversation engine asks first. Every other question is reachable only via an explicit CONTINUE slug from another route — there is no implicit "next by position" fallback. Array position past element [0] is organisational; the runtime walks via explicit slug edges only.

Publishes that omit answerRoutes are rejected with MISSING_ANSWER_ROUTES; any CONTINUE action authored without a slug is rejected with BARE_CONTINUE_ROUTE.

Question shapes

A question's combination of questionType, expectedAnswer, preferred-answer fields, and answerRoutes operators must land in one of four valid shapes. The validator rejects mixed shapes at publish so configurations that would silently no-op or misfire at runtime fail loudly.

Yes/no questions are binary knockouts. When expectedAnswer is set, the conversation engine skips scoring and orients pass/fail around the expected answer — replies the engine cannot classify surface as outcome: INCOMPLETE (see Workflow Events). When expectedAnswer is omitted, the engine still classifies the answer as yes or no but does not orient pass/fail — your answerRoutes must encode the pass/fail direction explicitly (e.g. by attaching CLOSE_CONVERSATION with PASSED_CRITERIA to the answerState=yes route and FAILED_CRITERIA to the answerState=no route, or vice versa). strictness is allowed on yes/no questions.

Open-ended (no scoring) questions capture the candidate's free-form answer without scoring it. Two routing patterns:

• Record-and-continue — a single answerState=any route. The runtime stores the reply on the conversation and runs the route's actions (CONTINUE to the next question, CLOSE_CONVERSATION to end the run, or ROUTE_TO + CLOSE_CONVERSATION to hand off). Use when the answer is for the record only and doesn't need to branch — e.g. "Tell me about your shift preferences" feeding a recruiter review.
• Keyword branching — one or more answerText mentions/does_not_mention routes followed by a trailing answerState=any catch-all. mentions "X" fires when the reply mentions X; does_not_mention "X" fires when it does not. The catch-all handles replies that didn't match any prior route. Use when one or two keyword categories should drive routing — e.g. region branching (mentions "London" → city-specific follow-up), or absence checks (does_not_mention "weekend" → ask about weekend availability before proceeding).

Open-ended scoring questions are scored by the conversation engine against preferredAnswerText. Setting expectedAnswer here is meaningless (the engine skips scoring when it sees expectedAnswer), so the validator rejects the combination with EXPECTED_ANSWER_ON_NON_YES_NO_ROUTES.

Document questions are evaluated by upload state, not by reply text or score. expectedAnswer, preferred-answer fields, and strictness have no runtime effect on a document question and are rejected up front by INCOMPATIBLE_FIELD_FOR_QUESTION_TYPE. Routes must use documentState; an answer-state, score, or text-mention route on a document question fires INCOMPATIBLE_ROUTE_FOR_QUESTION_TYPE.

See Example 3 for valid payloads and common rejections per shape.

engagementOutreach

Sends a re-engagement, nurture, or follow-up conversation. Useful for the steps that come after fit has been established — confirming a booking, requesting a compliance pack, or keeping a candidate warm for future roles.

Engagement nodes share the same channel set, the same routing events, and the same webhook outcome surface as screeningOutreach, but the underlying contract differs because engagement nodes don't carry job-description data.

Differences from screeningOutreach

All other config fields (agentName, agentTone, title, channel, customTemplatedMessage, customTemplatedSubjectLine, templateId, criteriaSatisfiedClosingMessage, criteriaNotSatisfiedClosingMessage, candidateNotInterestedClosingMessage, timeToAutoCloseConversationsInHours, additionalContext) and all four routing events behave identically across both node types.

condition

Branches based on the run's accumulated context.

Config fields

Each branch's when is a Condition-node expression.

Routing events

The condition node's routing map always uses onConditionResolved to route to the next node. The actual routed node is determined by the matched branch's targetNodeId (or else).

Context the conversation engine uses to generate replies

When a candidate replies during an outreach, Popp's conversation engine generates the next message. The config fields you populate on a node are what shape that reply — without that context, replies are generic; with it, the engine can answer candidate questions about the role and phrase nudges, rejections, and closing notes with substance. Understanding which field plays which role is the difference between a reply that sounds informed and one that does not.

Each field maps to a specific role in the conversation engine's input:

Two practical implications:

• The role description belongs in outreachContext, not additionalContext. A common mistake is to put tone or style notes in outreachContext and the role description in additionalContext. The semantics are the inverse: outreachContext is the job description, additionalContext is the steering layer. Swapping them produces replies that sound off-brief.
• On engagementOutreach, lean on additionalContext. Engagement nodes don't pass job-description fields to the conversation engine, so additionalContext is your only steering channel. If you need the engine to know the broader recruiting context for a nurture or compliance step, put it there.

Routing Events

The supported node types emit the following routing events. Wire each event you care about in a node's routing map; events you do not wire terminate the run when they fire.

Answer-route DSL

Answer routes attach to individual questions on screeningOutreach and engagementOutreach nodes. They control how the conversation behaves while the candidate is still answering — skip a follow-up if the candidate said "no", close the conversation early when a score requirement isn't met, or hand off to a different node mid-conversation.

Two layers of routing

Outreach nodes have two routing layers that work together:

• In-conversation routing — answer routes (this section). Fire during a conversation, in response to individual answers, scores, or document uploads. Control which question comes next, whether to close the conversation early, and (via ROUTE_TO) whether to override the node's default downstream target.
• Node-level routing — routing events (see Routing Events). Fire when the conversation terminates. The node's routing map decides which downstream node the run transitions to.

The two layers are connected through the actions an answer route runs:

Some node-level events are emitted automatically by the conversation engine and are not configurable via answer routes:

• onNotInterested — fires when the candidate explicitly declines.
• onOptedOut — fires when the candidate opts out (e.g. SMS STOP).
• onDeliveryFailed — fires when delivery fails across all available channels.

Wire these on the node's routing map if you want to handle them; you don't trigger them from answer routes.

Route shape

Each entry in answerRoutes[] has shape:

{
  "when": { "field": "...", "op": "...", "value": "..." },
  "actions": [
    { "type": "CONTINUE", "slug": "next-question" }
  ],
  "closingMessage": "Optional closing copy used when actions terminate the conversation"
}

Evaluation order. Answer routes are walked in source order. The first route whose when matches the candidate's answer runs its actions and the resolver returns — subsequent routes don't fire, even if they would also match. Order more specific routes before more permissive ones (e.g. mentions "Greater London" before mentions "London"); if the fan-out includes a catch-all (answerState=any), it must sit at the end of the array (the validator enforces this with CATCH_ALL_NOT_LAST). The same first-match-wins rule applies to condition-node branches — see Condition-node DSL.

Condition vocabulary

The when expression on an answer route is a single leaf — and, or, and not are not permitted. Use a condition node for compound logic.

Note on score operators. Answer-route score conditions accept only gte and lt. Two consequences:

• gt and lte on score are rejected at publish as INVALID_NODE_CONFIG (the schema's score-operator enum is closed, so unsupported operators fail the shape parse — they don't reach the business-rule layer that emits INVALID_SCORE_CONDITION). Express thresholds as half-open intervals: score >= 70 instead of score > 69, score < 70 instead of score <= 69.
• The full set (gte, gt, lt, lte) is still available on condition nodes, which use the recursive expression DSL — see Condition-node DSL.

Closed operator vocabulary. The operator sets in the table above are exhaustive on the answer-route surface. Other operators on a family field — for example neq on answerState, in on documentState, or eq on score — are rejected at publish with INVALID_OPERATOR_FOR_FIELD. Presence operators (exists, empty) are not available on answer routes; they remain valid on condition-node expressions (see Condition-node DSL).

Actions

Three action types are supported. A route's actions array runs in order.

CONTINUE

Move on within the same conversation to a named sibling question. slug names the next question to ask within this node. There is no implicit fallback — a CONTINUE without a slug has no defined runtime target and is rejected at publish time (BARE_CONTINUE_ROUTE):

{ "type": "CONTINUE", "slug": "intent-to-register" }

CONTINUE does not fire a node-level routing event — it stays inside the conversation.

Validation at publish time:

• INVALID_CONTINUE_SLUG — the named slug does not exist in this node.
• CONTINUE_SLUG_CYCLE — explicit CONTINUE slug targets within a node form a cycle (e.g. q1 → q2 → q1).
• BARE_CONTINUE_ROUTE — a CONTINUE action was authored without a slug. Every CONTINUE must name its sibling target — there is no implicit fallback. Add a slug, or if the route's intent is to close or hand off, replace the CONTINUE with CLOSE_CONVERSATION (terminate the run) or ROUTE_TO + CLOSE_CONVERSATION (hand off to another node).

CLOSE_CONVERSATION

Terminate the conversation cleanly. The status field uses the same vocabulary as the workflow-domain webhook outcome — whatever you set here is what onComplete fires with on the WORKFLOW_NODE_COMPLETED webhook.

{ "type": "CLOSE_CONVERSATION", "status": "FAILED_CRITERIA" }

After the conversation closes, the run transitions per the node's routing.onComplete target — unless a ROUTE_TO action is paired in the same route (see below).

ROUTE_TO

Hand off to a different node when the conversation closes, overriding the node's default routing.onComplete target. Use this when a specific in-conversation outcome should branch into its own downstream journey rather than reusing the node's configured onComplete route.

{ "type": "ROUTE_TO", "nodeId": "engagement-london-compliance" }

ROUTE_TO must always be paired with a CLOSE_CONVERSATION action in the same route — ROUTE_TO transfers run ownership to another node, and CLOSE_CONVERSATION declares the terminal status for the current conversation. Both are required; without CLOSE_CONVERSATION, the publish is rejected with ROUTE_TO_WITHOUT_CLOSE:

{
  "when": { "field": "answerText", "op": "mentions", "value": "London" },
  "actions": [
    { "type": "CLOSE_CONVERSATION", "status": "PASSED_CRITERIA" },
    { "type": "ROUTE_TO", "nodeId": "engagement-london-compliance" }
  ]
}

Validation at publish time:

• ROUTE_TO_WITHOUT_CLOSE — a ROUTE_TO action is missing its required sibling CLOSE_CONVERSATION action.
• INVALID_ROUTE_TO_TARGET — the nodeId does not exist in the workflow graph.

Examples

Close the conversation as rejected if the candidate isn't NMC-registered:

{
  "when": { "field": "answerState", "op": "eq", "value": "no" },
  "actions": [{ "type": "CLOSE_CONVERSATION", "status": "FAILED_CRITERIA" }]
}

Skip directly to a shift-pattern deep-dive if the candidate scored highly on availability:

{
  "when": { "field": "score", "op": "gte", "value": 70 },
  "actions": [{ "type": "CONTINUE", "slug": "shift-pattern" }]
}

Branch into a London-specific question if the candidate's region response mentions London:

{
  "when": { "field": "answerText", "op": "mentions", "value": "London" },
  "actions": [{ "type": "CONTINUE", "slug": "london-trust-preference" }]
}

Close the conversation and hand off to a London-specific compliance node when the answer mentions London:

{
  "when": { "field": "answerText", "op": "mentions", "value": "London" },
  "actions": [
    { "type": "CLOSE_CONVERSATION", "status": "PASSED_CRITERIA" },
    { "type": "ROUTE_TO", "nodeId": "engagement-london-compliance" }
  ],
  "closingMessage": "Thanks — I'll hand you over to our London compliance team."
}

Condition-node DSL

The when expression on each condition node branch is the full recursive expression DSL.

Operators

and and or reject empty conditions[] arrays at publish time — vacuous always-match catch-alls fail the schema parse and surface as INVALID_NODE_CONFIG on the path to the empty array.

Field paths

Field paths are dot-delimited and the leading segment must match a WorkflowRunContext namespace:

The validator rejects field paths whose leading segment does not match one of these namespaces with INVALID_CONDITION_FIELD. Leaf paths beyond the namespace are not graph-aware in v1 — the validator does not check that a slug, an analysis output, or a meeting field exists on an upstream node.

Within the answers.<slug>.* namespace, the routable leaves are:

INCOMPLETE is set when the conversation engine can't classify a yes/no answer (the candidate's reply is too vague to orient pass/fail). Route on it via { "op": "eq", "field": "answers.<slug>.outcome", "value": "INCOMPLETE" } to send those candidates down a clarification branch rather than to the default pass/fail downstream.

Depth limit

Expressions deeper than 10 nesting levels evaluate to false at runtime. Keep your branch logic flat — if you find yourself nesting more than a few layers, split into multiple condition nodes.

Examples

Fast-track candidates who scored at least 70 on the shift-availability question:

{ "op": "gte", "field": "answers.shift-availability.score", "value": 70 }

Route candidates who hold an active NMC PIN AND signalled availability for full-time work:

{
  "op": "and",
  "conditions": [
    { "op": "eq", "field": "answers.nmc-pin.answerState", "value": "yes" },
    { "op": "gte", "field": "answers.shift-availability.score", "value": 60 }
  ]
}

Validation at Publish

POST /v1/workflows/{id}/publish runs the full validator suite against the working draft. On failure the response carries validation.valid: false and validation.errors[] listing every problem found (no fail-fast). Common error codes:

Graph-level

Outreach config

Question-shape coherence

These rules cross-check each question's fields and routes against the four valid question shapes. They fire at publish time and are distinct from OPERATOR_SOURCE_MISMATCH (which catches field/namespace mismatches across the answer-route and condition-node surfaces); the codes below catch in-shape misuse on a single question.

Answer-route specific

Answer-logic coherence and reachability

These rules apply across the answer routes on a single question (and across the branches on a condition node). They prevent configurations that publish cleanly but misbehave at runtime — silent closes, never-fires routes, and ambiguous fan-outs.

Worked example — a fan-out that fails today

{
  "slug": "region",
  "content": "Which UK region or trusts are you available to cover?",
  "answerRoutes": [
    { "when": { "field": "answerText", "op": "mentions", "value": "London" },
      "actions": [{ "type": "CONTINUE", "slug": "london-shifts" }] },
    { "when": { "field": "answerText", "op": "mentions", "value": "Manchester" },
      "actions": [{ "type": "CONTINUE", "slug": "manchester-shifts" }] }
  ]
}

This passes the schema but is rejected at publish with MISSING_FALLBACK_ROUTE — an answer-text fan-out needs an explicit catch-all so candidates whose answer mentions neither term still have a defined route. Fix:

"answerRoutes": [
  { "when": { "field": "answerText", "op": "mentions", "value": "London" },
    "actions": [{ "type": "CONTINUE", "slug": "london-shifts" }] },
  { "when": { "field": "answerText", "op": "mentions", "value": "Manchester" },
    "actions": [{ "type": "CONTINUE", "slug": "manchester-shifts" }] },
  { "when": { "field": "answerState", "op": "eq", "value": "any" },
    "actions": [{ "type": "CONTINUE", "slug": "shift-availability" }] }
]

Condition-node specific

The strict expression schema rejects unknown operators, missing fields, and value-type mismatches. Field paths whose leading segment does not match a known WorkflowRunContext namespace are rejected with INVALID_CONDITION_FIELD.

Template variables

Both outreach types parse {{...}} template variables in customTemplatedMessage (and the other interpolated message fields: customTemplatedSubjectLine, criteriaSatisfiedClosingMessage, criteriaNotSatisfiedClosingMessage, candidateNotInterestedClosingMessage, and any per-route closingMessage) and reject unknown variables with INVALID_TEMPLATE_VARIABLE. Variable names are SCREAMING_SNAKE_CASE and must come from the supported set:

Using {{JOB_TITLE}}, {{EMPLOYER_NAME}}, or {{LOCATION}} inside an engagementOutreach node will fail publish with INVALID_TEMPLATE_VARIABLE. Unknown placeholders (e.g. {{firstName}}, {{candidate.firstName}}) are rejected on either node type.

Worked Examples

Example 1 — Linear nurse onboarding journey

Cedar Health Recruitment runs a three-step linear journey for every Registered General Nurse their ATS feeds in: screen for availability and registration, collect compliance documents, then confirm bookings. Three outreach nodes chained — each builds on the last.

{
  "startNodeId": "screen-availability",
  "triggerSource": "API",
  "nodes": {
    "screen-availability": {
      "id": "screen-availability",
      "type": "screeningOutreach",
      "label": "RGN — availability and NMC screen",
      "routing": { "onComplete": "engagement-compliance-docs" },
      "config": {
        "agentName": "Cedar Health Recruiter",
        "agentTone": "PROFESSIONAL",
        "title": "RGN — availability and NMC screen",
        "channel": "SMS",
        "employerName": "Cedar Health Recruitment",
        "roleTitle": "Registered General Nurse (Band 5)",
        "location": "Various UK NHS trusts and care homes",
        "outreachContext": "Cedar Health places Band 5 RGNs into NHS trust bank-shifts and private care-home placements. Initial screen confirms NMC registration, region, and shift appetite before we ask for compliance documents.",
        "customTemplatedMessage": "Hi {{CANDIDATE_FIRST_NAME}}, this is Cedar Health Recruitment — we have new RGN shifts coming up that match your profile. A few quick questions to confirm your fit. Reply STOP to opt out.",
        "questions": [
          {
            "slug": "nmc-pin",
            "content": "Are you currently NMC-registered with an active PIN?",
            "answerRoutes": [
              {
                "when": { "field": "answerState", "op": "eq", "value": "any" },
                "actions": [{ "type": "CONTINUE", "slug": "region" }]
              }
            ]
          },
          {
            "slug": "region",
            "content": "Which UK region or trusts are you available to cover?",
            "answerRoutes": [
              {
                "when": { "field": "answerState", "op": "eq", "value": "any" },
                "actions": [{ "type": "CONTINUE", "slug": "shift-availability" }]
              }
            ]
          },
          {
            "slug": "shift-availability",
            "content": "How many shifts per week are you looking to pick up over the next month?",
            "answerRoutes": [
              {
                "when": { "field": "answerState", "op": "eq", "value": "any" },
                "actions": [{ "type": "CLOSE_CONVERSATION", "status": "PASSED_CRITERIA" }]
              }
            ]
          }
        ]
      }
    },
    "engagement-compliance-docs": {
      "id": "engagement-compliance-docs",
      "type": "engagementOutreach",
      "label": "Request compliance pack",
      "routing": { "onComplete": "engagement-booking-confirm" },
      "config": {
        "agentName": "Cedar Health Recruiter",
        "agentTone": "PROFESSIONAL",
        "title": "Request compliance pack",
        "channel": "EMAIL",
        "customTemplatedSubjectLine": "Cedar Health — your compliance pack for upcoming RGN shifts",
        "customTemplatedMessage": "Hi {{CANDIDATE_FIRST_NAME}}, thanks for confirming your details over SMS. To get you booked onto shifts we need your compliance pack: an in-date Enhanced DBS on the update service, your right-to-work documentation, your mandatory training certificate (CSTF or equivalent), and two professional references. Reply to this email with the documents attached and our compliance team will take it from there."
      }
    },
    "engagement-booking-confirm": {
      "id": "engagement-booking-confirm",
      "type": "engagementOutreach",
      "label": "Confirm booking",
      "routing": {},
      "config": {
        "agentName": "Cedar Health Recruiter",
        "agentTone": "PROFESSIONAL",
        "title": "Confirm booking",
        "channel": "SMS",
        "customTemplatedMessage": "Hi {{CANDIDATE_FIRST_NAME}}, your compliance pack is in and you're now shift-ready with Cedar Health. Our bookings team will be in touch this week with the first set of shifts in your region. Reply STOP to opt out at any time."
      }
    }
  }
}

screen-availability only routes onComplete here — opting out, signalling not interested, or delivery failure terminates the run cleanly. Example 2 shows what to do if you want each of those exit events to land in its own follow-up.

Example 2 — Branching journey with per-outcome fan-out

Cedar Health Recruitment wants every conversational outcome to land somewhere useful: candidates who say they're not interested go onto a nurture list, candidates who don't reply over SMS get retried over email, region-specific candidates land on a region-specific compliance pack, and everyone else goes through the standard one. This example shows three things at once:

1. Multiple routing events on a single screening node, each connected to a different downstream node. The screening's onComplete, onNotInterested, and onDeliveryFailed events fan out to three different engagement journeys.
2. In-conversation pathways via answer routes. The nmc-pin question branches mid-conversation: candidates without an active PIN are asked a follow-up about whether they're in the process of registering, and that follow-up can end the conversation early via ROUTE_TO paired with CLOSE_CONVERSATION.
3. Content-based branching post-screening. A condition node routes London candidates to a London-specific compliance pack, and everyone else to the standard one.

{
  "startNodeId": "screen-availability",
  "triggerSource": "API",
  "nodes": {
    "screen-availability": {
      "id": "screen-availability",
      "type": "screeningOutreach",
      "label": "RGN — availability and NMC screen",
      "routing": {
        "onComplete": "branch-on-region",
        "onNotInterested": "engagement-nurture",
        "onDeliveryFailed": "engagement-email-fallback"
      },
      "config": {
        "agentName": "Cedar Health Recruiter",
        "agentTone": "PROFESSIONAL",
        "title": "RGN — availability and NMC screen",
        "channel": "SMS",
        "employerName": "Cedar Health Recruitment",
        "roleTitle": "Registered General Nurse (Band 5)",
        "location": "Various UK NHS trusts and care homes",
        "outreachContext": "Cedar Health places Band 5 RGNs into NHS trust bank-shifts and private care-home placements. We confirm NMC registration first; candidates who are mid-registration are still worth a follow-up nurture email, but candidates who don't intend to register at all are not a fit right now.",
        "customTemplatedMessage": "Hi {{CANDIDATE_FIRST_NAME}}, this is Cedar Health Recruitment — we have new RGN shifts coming up that match your profile. A few quick questions to confirm your fit. Reply STOP to opt out.",
        "questions": [
          {
            "slug": "nmc-pin",
            "content": "Are you currently NMC-registered with an active PIN?",
            "answerRoutes": [
              {
                "when": { "field": "answerState", "op": "eq", "value": "yes" },
                "actions": [{ "type": "CONTINUE", "slug": "region" }]
              },
              {
                "when": { "field": "answerState", "op": "eq", "value": "no" },
                "actions": [{ "type": "CONTINUE", "slug": "intent-to-register" }]
              }
            ]
          },
          {
            "slug": "intent-to-register",
            "content": "Are you in the process of registering with the NMC?",
            "answerRoutes": [
              {
                "when": { "field": "answerState", "op": "eq", "value": "yes" },
                "actions": [{ "type": "CONTINUE", "slug": "region" }]
              },
              {
                "when": { "field": "answerState", "op": "eq", "value": "no" },
                "actions": [
                  { "type": "CLOSE_CONVERSATION", "status": "FAILED_CRITERIA" },
                  { "type": "ROUTE_TO", "nodeId": "engagement-nurture" }
                ],
                "closingMessage": "Thanks for letting us know — we'll keep you on file and reach out when you're ready to pick up RGN shifts."
              }
            ]
          },
          {
            "slug": "region",
            "content": "Which UK region or trusts are you available to cover?",
            "answerRoutes": [
              {
                "when": { "field": "answerState", "op": "eq", "value": "any" },
                "actions": [{ "type": "CONTINUE", "slug": "shift-availability" }]
              }
            ]
          },
          {
            "slug": "shift-availability",
            "content": "How many shifts per week are you looking to pick up over the next month?",
            "answerRoutes": [
              {
                "when": { "field": "answerState", "op": "eq", "value": "any" },
                "actions": [{ "type": "CLOSE_CONVERSATION", "status": "PASSED_CRITERIA" }]
              }
            ]
          }
        ]
      }
    },
    "branch-on-region": {
      "id": "branch-on-region",
      "type": "condition",
      "label": "Route by region",
      "routing": { "onConditionResolved": "engagement-compliance-docs" },
      "config": {
        "branches": [
          {
            "id": "london-region",
            "label": "Region mentions London",
            "when": { "op": "mentions", "field": "answers.region.answerText", "value": "London" },
            "targetNodeId": "engagement-london-compliance"
          }
        ],
        "else": "engagement-compliance-docs",
        "elseLabel": "Standard compliance pack"
      }
    },
    "engagement-london-compliance": {
      "id": "engagement-london-compliance",
      "type": "engagementOutreach",
      "label": "London compliance pack",
      "routing": {},
      "config": {
        "agentName": "Cedar Health Recruiter",
        "agentTone": "PROFESSIONAL",
        "title": "London compliance pack",
        "channel": "EMAIL",
        "customTemplatedSubjectLine": "Cedar Health — your London compliance pack for upcoming RGN shifts",
        "customTemplatedMessage": "Hi {{CANDIDATE_FIRST_NAME}}, thanks for confirming your details. For our Greater London trusts we need the standard pack plus two London-trust-specific clinical references: in-date Enhanced DBS on the update service, right-to-work documentation, mandatory training certificate, and references from two clinical leads at trusts you've worked at in the last two years. Reply with the documents attached and our compliance team will take it from there."
      }
    },
    "engagement-compliance-docs": {
      "id": "engagement-compliance-docs",
      "type": "engagementOutreach",
      "label": "Standard compliance pack",
      "routing": {},
      "config": {
        "agentName": "Cedar Health Recruiter",
        "agentTone": "PROFESSIONAL",
        "title": "Standard compliance pack",
        "channel": "EMAIL",
        "customTemplatedSubjectLine": "Cedar Health — your compliance pack for upcoming RGN shifts",
        "customTemplatedMessage": "Hi {{CANDIDATE_FIRST_NAME}}, thanks for confirming your details. To get you booked onto shifts we need your compliance pack: an in-date Enhanced DBS on the update service, right-to-work documentation, your mandatory training certificate (CSTF or equivalent), and two professional references. Reply to this email with the documents attached and our compliance team will take it from there."
      }
    },
    "engagement-nurture": {
      "id": "engagement-nurture",
      "type": "engagementOutreach",
      "label": "Nurture for future roles",
      "routing": {},
      "config": {
        "agentName": "Cedar Health Recruiter",
        "agentTone": "PROFESSIONAL",
        "title": "Nurture for future roles",
        "channel": "EMAIL",
        "customTemplatedSubjectLine": "Cedar Health — we'll be in touch when the timing is right",
        "customTemplatedMessage": "Hi {{CANDIDATE_FIRST_NAME}}, thanks for letting us know — we'll keep you on file and reach out when you're ready to pick up RGN shifts. If anything changes in the meantime, just reply to this email and we'll get you set up."
      }
    },
    "engagement-email-fallback": {
      "id": "engagement-email-fallback",
      "type": "engagementOutreach",
      "label": "Email fallback for SMS-unreachable candidates",
      "routing": {},
      "config": {
        "agentName": "Cedar Health Recruiter",
        "agentTone": "PROFESSIONAL",
        "title": "Email fallback for SMS-unreachable candidates",
        "channel": "EMAIL",
        "customTemplatedSubjectLine": "Cedar Health Recruitment — RGN shifts in your region",
        "customTemplatedMessage": "Hi {{CANDIDATE_FIRST_NAME}}, we tried to reach you over SMS but couldn't get through. Cedar Health Recruitment has new RGN shifts coming up that match your profile — reply to this email if you're interested and we'll send across the next steps."
      }
    }
  }
}

Walking through the journey:

• A candidate enters at screen-availability.
• If they say they don't have an NMC PIN, the answer route on nmc-pin skips them straight to intent-to-register. If they then say they're not even registering, the answer route closes the conversation with status: "FAILED_CRITERIA" and uses ROUTE_TO to send the run directly to engagement-nurture — overriding the node's default onComplete target. The conversation engine still emits onNotInterested automatically for candidates whose tone signals disinterest more generically (e.g. "not for me thanks"), and that path also lands in engagement-nurture via the node's routing map.
• If they say they have a PIN (or that they're mid-registration), they continue through region and shift-availability and the conversation completes normally — onComplete fires and the run lands in branch-on-region.
• branch-on-region checks whether the candidate's region answer mentions London and routes to either engagement-london-compliance or engagement-compliance-docs.
• If the SMS never delivered (e.g. invalid mobile number), onDeliveryFailed routes the run to engagement-email-fallback instead, retrying via email.
• Opting out (onOptedOut) is intentionally unrouted, so the run terminates cleanly with no further messages.

Example 3 — Question shapes by example

Four valid question fragments — one per shape from the Question shapes table — followed by common rejection examples and the error code each produces. Fragments are shown in isolation; drop them into a node's config.questions[] array.

Yes/no question with expectedAnswer: IS_YES (knockout)

{
  "slug": "nmc-pin",
  "content": "Are you currently NMC-registered with an active PIN?",
  "questionType": "TEXT",
  "expectedAnswer": "IS_YES",
  "strictness": "STRICT",
  "answerRoutes": [
    { "when": { "field": "answerState", "op": "eq", "value": "yes" },
      "actions": [{ "type": "CONTINUE", "slug": "region" }] },
    { "when": { "field": "answerState", "op": "eq", "value": "no" },
      "actions": [{ "type": "CLOSE_CONVERSATION", "status": "FAILED_CRITERIA" }] }
  ]
}

Open-ended (no scoring) question — record-and-continue

{
  "slug": "current-shifts",
  "content": "What does your current week look like — which shifts are you working now?",
  "questionType": "TEXT",
  "answerRoutes": [
    { "when": { "field": "answerState", "op": "eq", "value": "any" },
      "actions": [{ "type": "CONTINUE", "slug": "shift-availability" }] }
  ]
}

For keyword-based branching, swap the sole catch-all for one or more answerText mentions/does_not_mention routes followed by a trailing answerState=any catch-all (see Question shapes).

Open-ended scoring question with preferredAnswerText and score routes

{
  "slug": "shift-availability",
  "content": "How many shifts per week are you looking to pick up over the next month, and which days work best for you?",
  "questionType": "TEXT",
  "preferredAnswerText": "Four or more shifts per week, including at least one weekend day, with availability for early or late starts.",
  "answerRoutes": [
    { "when": { "field": "score", "op": "gte", "value": 70 },
      "actions": [{ "type": "CLOSE_CONVERSATION", "status": "PASSED_CRITERIA" }] },
    { "when": { "field": "score", "op": "lt", "value": 70 },
      "actions": [{ "type": "CLOSE_CONVERSATION", "status": "FAILED_CRITERIA" }] }
  ]
}

Document question with documentTypes and document-state routes

{
  "slug": "right-to-work",
  "content": "Please attach a clear photo of your right-to-work documentation (passport, BRP, or share code letter).",
  "questionType": "DOCUMENT",
  "documentTypes": ["passport", "biometric-residence-permit", "share-code-letter"],
  "answerRoutes": [
    { "when": { "field": "documentState", "op": "eq", "value": "uploaded" },
      "actions": [{ "type": "CLOSE_CONVERSATION", "status": "PASSED_CRITERIA" }] },
    { "when": { "field": "documentState", "op": "eq", "value": "not_uploaded" },
      "actions": [{ "type": "CLOSE_CONVERSATION", "status": "FAILED_CRITERIA" }] }
  ]
}

Common rejections

These fragments publish-fail with the indicated error code.

expectedAnswer combined with a scoring rubric — fires PREFERRED_ANSWER_ON_YES_NO_QUESTION on path: ...questions[0].preferredAnswerText (and MISSING_FALLBACK_ROUTE on the routes, since expectedAnswer declares binary intent and a sole answerState=any catch-all is not a complete yes/no pair). Yes/no shape (expectedAnswer set) is mutually exclusive with scoring (preferredAnswerText set):

{
  "slug": "nmc-pin",
  "content": "Are you currently NMC-registered?",
  "expectedAnswer": "IS_YES",
  "preferredAnswerText": "Active PIN holder for at least 12 months",
  "answerRoutes": [
    { "when": { "field": "answerState", "op": "eq", "value": "any" },
      "actions": [{ "type": "CLOSE_CONVERSATION", "status": "FAILED_CRITERIA" }] }
  ]
}

Document question with an answerState route — fires INCOMPATIBLE_ROUTE_FOR_QUESTION_TYPE on the route (and MISSING_FALLBACK_ROUTE, since questionType: DOCUMENT declares binary intent and the fan-out is not a complete documentState=uploaded + =not_uploaded pair):

{
  "slug": "right-to-work",
  "content": "Attach your right-to-work documentation.",
  "questionType": "DOCUMENT",
  "documentTypes": ["passport"],
  "answerRoutes": [
    { "when": { "field": "answerState", "op": "eq", "value": "yes" },
      "actions": [{ "type": "CLOSE_CONVERSATION", "status": "PASSED_CRITERIA" }] }
  ]
}

Non-canonical operator on an answer-route family field — fires INVALID_OPERATOR_FOR_FIELD on the route's when:

{
  "when": { "field": "answerState", "op": "neq", "value": "yes" },
  "actions": [{ "type": "CLOSE_CONVERSATION", "status": "FAILED_CRITERIA" }]
}

The fix is to express the inverse with the canonical operator — answerState eq no — or, if you need richer logic across multiple leaves, lift the comparison into a condition node where the full DSL is available.

Conversation Outcomes in Workflow Webhooks

When a workflow node's conversation completes, the webhook payload carries a workflow-domain outcome on the NodeOutcome (outcome.kind: "conversation" → outcome.status). This enum is intentionally separate from the Conversations API's conversationStatus field — the workflow domain owns its own outcome contract so screening-themed labels do not leak into webhook consumers.

If you need to read the underlying conversation directly, fetch it via the Conversations API using the conversationId carried on the NodeOutcome. The Conversations API uses its own public status enum (COMPLETED_SCREENING_PASSED, CLOSED, COMPLETED_SCREENING_FAILED, OPTED_OUT, etc.) which is documented separately on the Conversation schema.

Next Steps

• Workflow Events — webhook payloads emitted as runs progress.
• Webhook Authentication — verify the x-signature header on incoming events.