Workflow Builder

The Workflow Builder is Popp's automation engine for multi-step recruitment journeys. You design a candidate journey once — outreach, screening, branching logic, follow-up — and the platform runs it for every candidate that enters the workflow. No bespoke engineering, no manual coordination between campaigns and rules.

You can author workflows in two ways:

Visually, in the Popp UI's drag-and-drop builder.
Programmatically, via the public API. See the Workflow Configuration guide for the JSON schema and the API reference for the endpoints.

Workflows replace the need to manually coordinate separate campaigns, automation rules, and integrations — everything lives in one place.

How Workflows Work

Every workflow follows the same lifecycle: Trigger → Nodes → Routing → Completion. An event starts a run, the candidate flows through a sequence of nodes, each node's outcome determines the next step via routing, and the run eventually reaches a terminal state.

Key concepts

Concept	Description
Workflow	The blueprint — your complete candidate journey
Version	An immutable published snapshot of a workflow (safe iteration)
Run	A single candidate's execution through a published workflow version
Node	One step in the workflow (e.g. send a screening conversation, branch)
Routing	Outcome-based branching that determines which node executes next

Lifecycle

Status	Meaning
`UNPUBLISHED`	Working draft. Editable. Cannot accept runs.
`PUBLISHED`	Live. Editable (the working draft) and accepts new runs against the published version.
`PAUSED`	Live but not accepting new runs. In-flight runs continue to completion.
`ARCHIVED`	Read-only.

You publish via the API or the Popp UI. Validation runs on every publish and surfaces a list of errors against the configuration if the workflow isn't ready to ship.

Capabilities

Triggers

Workflow runs are started via the API:

API trigger — call POST /v1/workflows/{id}/runs with one or more candidates (by ID, external ID, or inline contact details). Each candidate is enrolled into a separate run.

Node types

Node type	`configuration.nodes[].type`	What it does
Screening Outreach	`screeningOutreach`	Starts a screening conversation with the candidate over SMS, WhatsApp, or email and collects answers to a fixed set of questions. Used when you need to test fit (pass/fail, scoring, structured answers).
Engagement Outreach	`engagementOutreach`	Starts a re-engagement, nurture, or follow-up conversation. Same channel + content surface as Screening Outreach but does not require job-description data, so the message-level job-description variables (`{{JOB_TITLE}}`, `{{EMPLOYER_NAME}}`, `{{LOCATION}}`) are not available. Used after fit is established.
Condition	`condition`	Branches the run based on the accumulated context — answers, scores, or candidate attributes.

Each node type emits routing events when it completes. You wire those events to subsequent nodes in the configuration to build the journey. See the Workflow Configuration guide for the full DSL, including the answer-route condition vocabulary and the condition-node expression grammar.

Webhooks

Workflow runs publish lifecycle events to subscribed webhooks. Subscribe via the Webhooks API to receive run-start, per-node, run-terminal, contact-resolution, and workflow-publish events. See Workflow Events.

Example: Healthcare nurse onboarding

Cedar Health Recruitment is a UK-based health-tech recruitment firm placing Registered General Nurses (RGNs) into NHS trusts and care homes. Compliance is non-negotiable — every candidate needs an active NMC PIN, an in-date DBS, mandatory training certificates, and right-to-work documentation before they can pick up a single shift. They configure a workflow once and run it against every RGN applicant their ATS feeds in via the API.

A single workflow handles every conversational outcome — interested, not interested, mid-registration, unreachable over SMS — and routes each one to the right follow-up. No manual coordination between teams.

API trigger — the firm's ATS posts new RGN applicants to POST /v1/workflows/{id}/runs.
Screening Outreach (availability + NMC) — Popp opens an SMS conversation asking about NMC registration, region preference, and shift availability. Candidates who don't yet have a PIN are asked a follow-up about whether they're in the process of registering — those who say no end the conversation early and land on a nurture list, those who are mid-registration continue through the screen.
Per-outcome fan-out — the screening node wires each conversational outcome to a different downstream node:
- Interested + screened → continue to a region-aware compliance step.
- Not interested / mid-registration → land on a long-term nurture list.
- SMS delivery failed → retry the same screening intent over email.
- Opted out → end the run cleanly, no further messages.
Condition (route by region) — candidates whose region answer mentions London get routed to a London-trust-specific compliance pack (some Greater London trusts require additional clinical references); everyone else gets the standard pack.
Engagement Outreach (compliance pack) — emails the candidate the exact list of documents to send back. Cedar Health's compliance team picks up the reply.
Engagement Outreach (booking confirmation) — once compliance is in, a final SMS confirms the candidate is shift-ready and the bookings team takes it from there.

The whole journey runs automatically. Cedar Health's compliance and bookings teams only step in when there's a real human decision to make.

Two complete, copy-paste-runnable versions of this workflow live in the Workflow Configuration guide — a simple linear version for first-time integrators, and a richer branching version that demonstrates per-outcome fan-out and in-conversation answer routing.

Get started

Workflow Configuration — full reference for the configuration DSL, node types, answer-route DSL, condition-node expression grammar, validation errors, and worked examples.
Workflow Events — webhook payloads emitted as runs progress.
Webhooks — how to subscribe an HTTPS endpoint and verify the x-signature header.
Authentication — how to authenticate API requests with your Popp API key.