Skip to main content
GET
Read a workflow

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
workflow_key
string
required

Response

The workflow: who completes it, and every step it can present.

A workflow as it is configured for you: who completes it, and the journey its key runs, step by step.

Everything the journey declares is the latest version's, which is the one a verification created now runs. A verification created earlier runs the version it names in version, and reads under that version for as long as it lasts.

The mode, the step keys and each step's intake are stable. The rest is configuration we maintain and tune without notice, so read it to understand a journey rather than to build behaviour against; the stable thing to integrate with is the verification record.

​
key
string
required

The key you name when creating a verification on this workflow.

​
name
string
required

The workflow's name, for showing in your own tools.

​
mode
enum<string>
required

How verifications on this workflow are conducted. hosted: the person being verified walks the journey on our screens and submits it. staged: you create a verification, upload each document against the step it answers, and then ask for the checks to run. instant: you send the whole submission in one request, which runs the checks and answers with the finished record.

A workflow is one of the three, and every endpoint belonging to another is refused on it.

Available options:
hosted,
staged,
instant
​
version
integer
required

The workflow's latest version, which is the one a verification created now runs. Versions are numbered from 1, and every change to the journey is published as the next one, so a number names one journey for good.

A verification keeps the version it was created on until it is reset, so a change reaches the verifications created after it and never one already under way. The mode is the workflow's, and the same on every version.

Required range: x >= 1
​
expires_after_days
integer
required

How long a verification on the version reported here holds a user's data, counted from their last action. Once that window runs out the verification expires and everything the user provided is deleted. A verification is held for as long as the version it runs says.

​
groups
StepGroup · object[]
required

The named parts the version reported here presents its steps in, in the order a user meets them. A step that belongs to one names it in group, and the steps of a group are consecutive, so each group heads one unbroken run of steps. A version that presents its steps under no headings at all has none of these.

​
steps
WorkflowStepRecord · object[]
required

Every step the version reported here can present, in the order a user meets them. A step that carries a condition is only presented when that condition holds, so any one verification walks some of these rather than all of them.

​
environment
enum<string>
required

Which environment this workflow is in: uat for the ones you integrate and test against, production for your real work. An API key belongs to one environment and reaches only that environment's workflows, so a key of the other one is refused with 403. A uat workflow's key ends in -uat and a production workflow's never does, so the key in your own configuration says which you are pointed at.

A run is identical in both: the same steps, the same checks, the same verdicts and the same credits.

Available options:
uat,
production
​
credits
WorkflowCredits · object
required

This workflow's prepaid credits as they stand.

​
runs
WorkflowRuns · object
required

How many verifications this workflow has going, against how many it may. An instant workflow reports these too: its verifications are open while their checks run, so they count towards the ceiling for as long as they take to answer.

​
resets
WorkflowResets · object
required

The resets this workflow was sold, where they went, and what is left. They are sold with credits on the same terms and expire with them, so this reads exactly as credits does.

Clearing a verification that had not ended draws one, because the run being cleared was never charged for. It is held by the workflow rather than by any one verification, so where the allowance goes is a question about the workflow and not about the record a reset happened to fall on. A verification's own resets counts every reset of it, drawn or not.

An instant workflow reports these unmoved: its verifications are answered in the request that made them, so they are asked again rather than reset and nothing on one ever draws.

​
output_transformations
Output Transformations · object
required

How the outputs of the version reported here reach you, by step type. Each entry names a field of what that step type publishes by the path it sits at, and states the name it arrives under in collected.outputs, the transform that converts its value, or both; [] in a path descends into every record of a list. A step type with no entry here reaches you as this reference describes it, as does every step type when this is empty.

A transform is a JSONata expression over the one value at its path, in the shape this reference documents it, and what it yields arrives in that value's place. It reads nothing else, so it never reaches another field or another step, and it always yields a value. Where a version's transformation cannot be applied to a verification's value, reading that verification answers workflow-misconfigured.

Only collected.outputs is transformed. The paths on the left are the names used everywhere else a field is named, this reference and collected.answer included, so read this to translate between the two.

The map belongs to the version, so a verification's outputs reach you as the version it runs states, and a change to it reaches the verifications created after it.

​
output_names
Output Names · object
required

The names alone from output_transformations, by step type: each published path mapped to the name it arrives under in collected.outputs, for every entry that states one. A path whose entry states only a transform keeps its own name and is not listed.

A name is not the whole of how a field reaches you where its entry also converts the value, so read output_transformations for that.