Going live

The rest of these guides say how each call works. This one is the setup around them: what your account consists of, and what to have handled before a real subject goes through it.

​

What we configure with you

None of this is self-serve. Ask us for any of it, or to change it. Your API keys. One for uat and one for production, each authenticating every request it makes and reaching only its own environment’s workflows. Your workflows. Each has a workflow_key, which you name when creating a verification, a mode that decides how the documents reach us, an environment, the steps it declares, and which of those are required. GET /workflows lists them and GET /workflows/{workflow_key} reads one, so your integration can read all of it rather than hold a copy of it. A key, its mode and its environment belong together: a journey that has to change any of the three is published under a new key. Any other change is published as the workflow’s next version, which the verifications created from then on run; each one created earlier keeps its own. See Versions. Your credits. How many verifications each workflow is sold, the date they expire on, and how many of its verifications may be going at once. Credits are per workflow, so each of your journeys is sold separately and a uat workflow’s credits are its own. A workflow with none left refuses 402 until we top it up. See Credits and limits. How long each workflow holds data. Anywhere from 1 to 120 days of inactivity, and 30 on a workflow that asks for nothing in particular. See Expiry and retention. How each workflow’s outputs reach you. Optional, and per workflow. Left alone, a workflow publishes the names and shapes these guides use. Set up, it publishes the names your own schema keeps those values by, and converts a value into the shape your systems read, in collected.outputs and nowhere else. A change to either is a new version of the workflow, so it reaches the verifications created after it. See Custom output transformations. Each workflow’s callback endpoint. The https URL we post to when a verification on that workflow is submitted, and how a delivery identifies itself so your handler can tell the request is ours: a secret you choose and we send back, or a token we fetch from your own auth service. Registered per workflow, so a uat journey reports to wherever you are testing and a production one to where your real work goes. Registering an endpoint is optional: without one you poll. See Callbacks. Each workflow’s return URL allowlist. Hosted workflows only, and per workflow like the callback. The URLs a journey on it may return a user to when it is done; a return_url outside its allowlist is refused with 400. See Hosted.

​

Before your first real subject

​

Keys and environments

• Hold the two keys apart. A uat key reaches only uat workflows and a production key only production ones, so the environment your integration is pointed at is whichever key it loaded. A uat key’s token begins uat_ and a uat workflow’s key ends -uat, which is how a config you are reading tells you where it points.
• Expect 403 on a mismatch, not an empty result. Naming the other environment’s workflow is refused, and so is reading a record created on one. See Environments.
• Do not treat uat as a sandbox. The same steps, sources and verdicts, on documents that are really read and really confirmed.

​

Credits

• Watch credits.remaining and credits.expiring on each workflow you run, and alert yourself before either runs out. Reading a workflow is free.
• Surface 402 rather than retrying it. It means the workflow has no credits left and the same call will be refused until we top it up. Verifications already open on that workflow are frozen meanwhile, and a hosted journey stops under the person walking it.
• Ask for headroom on runs.limit if runs.live sits near it in normal operation. At the ceiling, creating a verification is refused with 409 until one of yours ends.
• Reckon a reset as another credit. Running the same subject through again is a run of its own, and credits_consumed on the record counts every run of it. See Credits and limits.
• Reckon a reset of an open or submitted verification against resets.remaining. Nobody was charged for the run you clear, so it draws one of the workflow’s resets; at zero those resets are refused with 402 until the workflow is topped up. Resetting a completed, cancelled or failed record draws nothing. Resets are sold with credits and expire with them, so stock them like runs if your process clears records mid-run.

​

The workflow

• Drive off the steps array the API returns, never a hardcoded list. Which steps a workflow declares and what each one checks are ours to tune as a journey is refined; the step keys, the mode and the intake are what you address them by and do not change under you. A refinement is a new version, and a verification keeps the one it was created on, so read its steps off the record rather than off the workflow. See Staged.
• Handle all eight step states, not passed and failed alone. See Step states.

​

Identifiers

• Make reference_user_id something you can reconcile against your own records. With workflow_key it is the only handle on a record whose data has been deleted. See Identifiers.
• Reuse it on a retry. Creating is idempotent on it, so a call you never saw the answer to resolves to the same verification rather than a second one. See Retrying safely.

​

Being told it is done

• Answer a callback 2xx within 10 seconds, and read the record afterwards rather than before.
• Check the proof the delivery carries, whether that is the secret you chose, compared with a constant-time function, or a token from your own auth service, checked as your other endpoints check one. Serve the endpoint over https only.
• Make the handler idempotent on verification_id and occurred_at together. A delivery can repeat, and a verification you reset and that is submitted again earns a callback of its own.
• Know how to catch up. After an outage, callback.status on each record tells you which submissions you were never told about. See Catching up on callbacks you missed.

​

Acting on the result

• Route a step that passed with a gap to a person. Every document is genuine and confirmed at source, and something is not an exact match.
• Do not read error as a failure. A failed step was checked and did not stand up; a step in error was never checked, because a source could not be reached.
• Know which values a source stood up and which are a reading of a document. Documents are read automatically, by a language model, and a model is not exact. See Accuracy and limits.
• Read not-supplied on a required step as unverified, which is the absence of a check rather than the result of one.
• Know whether your workflows transform their outputs, and treat these guides as the system’s names and shapes either way. Nothing you read here is written in your names or your shapes. If a workflow transforms anything, every field in these guides and in the API reference is one to translate from, and GET /workflows/{workflow_key} reports the output_transformations to translate with. Transformations reach collected.outputs alone, so the same value can arrive under your name and in your shape there and under the system’s name in answer. Changing a transformation later changes what your integration receives without changing anything these guides describe, so change one only alongside the code that parses it. See Custom output transformations.

​

Before the data goes

• Take out what you need to keep. Download the documents and copy the values you need before a verification’s retention window closes. Nothing is recoverable afterwards, completed records included.
• Purge when your own process is done, if you want what you supplied gone sooner than the window. The record stays readable and holds nothing else. See Ending or restarting.