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: Entry → Nodes → Routing → Completion. A candidate enters through an entry pathway, 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

Lifecycle

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

Entry pathways

A candidate enters a workflow through an entry pathway — a named source paired with the node the candidate starts on. A workflow can hold several pathways; two are available to integrators — the API pathway and the ATS pathway:

• API pathway — 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, starting at the workflow's entry node.

An ATS pathway is also supported: connect a workflow to an ATS job and applicants enter automatically as they apply. Discover the jobs available to your organisation with GET /v1/ats/jobs, then reference their atsJobIds in an ATS entry pathway — that is all it takes to author an ATS-driven workflow. A workflow's ATS pathway can carry many jobs — up to 250 once the workflow contains an ATS node — so several vacancies can share one workflow. An ATS job can be connected to a workflow, or to a campaign or analysis, not both. The run-start request and response are unchanged by this model. See Entry in the configuration guide for the pathway shape.

Node types

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.

Monitoring runs

Webhooks push run progress to you as it happens. To pull it instead — to build a dashboard, reconcile
your own records, or find a specific candidate's run — list the runs for a workflow with
GET /v1/workflows/{workflowId}/runs.

Each run carries the candidate's name alongside candidateProfileId
(candidateProfileName, candidateProfileFirstName, candidateProfileLastName), so rendering a list
of runs takes one call rather than one call per run.

Filter and page the list with:

candidateName matches an ordered sequence of words, so John Smith matches John Smith but not
Smith John, and John matches every candidate named John. It is case-insensitive and combines with
the other filters.

Two things to know about the name fields:

• They are recorded when the run is created. If a candidate is renamed afterwards, the run keeps
  the name it was enrolled under, and candidateName searches the recorded name. Fetch the candidate
  profile for the current name.
• They can be null — on runs created before the fields existed, or where the candidate profile
  carries no name at all. Treat them as optional and fall back to candidateProfileId.

Fetch one run in full with GET /v1/workflow-runs/{runId}, which adds the
run context and failure detail on top of everything the list returns.

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.

1. API pathway — the firm's ATS posts new RGN applicants to POST /v1/workflows/{id}/runs.
2. 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.
3. 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.
4. 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.
5. Engagement Outreach (compliance pack) — emails the candidate the exact list of documents to send back. Cedar Health's compliance team picks up the reply.
6. 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.

Workflow-managed campaigns

When you publish a workflow, Popp creates a backing campaign with isWorkflowManaged: true. Starting work on that campaign — and managing the campaign itself — must go through the workflow lifecycle, not the campaign or conversation APIs.

The only supported entry point for starting conversations on a workflow-managed campaign is POST /v1/workflows/{workflowId}/runs (or the by-external-id variant, POST /v1/workflows/by-external-id/{externalId}/runs).

The following endpoints reject requests against a workflow-managed campaign with 400 Bad Request:

• POST /v1/conversations (Create conversation)
• POST /v1/conversations/bulk (Bulk create conversations)
• POST /v1/conversations/scheduling (Create scheduling conversation)
• PATCH /v1/campaigns/{id} (Update campaign)
• POST /v1/campaigns/{id}/stop (Stop campaign)

Mid-conversation operations remain available on workflow-driven conversations:

• POST /v1/conversations/{id}/messages — recruiters can still send a message into the conversation alongside the agent.
• POST /v1/conversations/{id}/hand-to-agent — a human takeover can be handed back to the agent.

Read endpoints (GET /v1/campaigns, GET /v1/campaigns/{id}, GET /v1/conversations, GET /v1/conversations/{id}, etc.) continue to return workflow-managed campaigns and their conversations as normal.

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.