Skip to main content

Capture & Workflow API

The Capture & Workflow API runs a verification. The Company's backend starts a session with a chosen workflow; the capture front-end then walks through the steps the API hands back, one at a time, until the workflow completes.

API reference​

The complete Capture API is published as an interactive reference — every endpoint, request and response schema, parameter, and status code — rendered directly from the service's OpenAPI specification. Use it to explore the exact contract while you build against the flow described below.

Open the Capture API reference

Authentication​

The API uses OAuth2. The token exchange must run on the Company's backend, not on the client device — putting credentials in the app would expose them. (Self-hosted deployments use the Company's own OAuth2 service.) The short-lived token is then passed to the client for the session.

Session lifecycle​

  1. Start — the backend calls POST /session with the workflow to run and, optionally, a target Customer (for authentication or update flows). The response carries a sessionId and the first nextStep.
  2. Step through — for each nextStep, the front-end launches the named capture component, then calls POST /submit with the captured data.
  3. Advance — after each submission the API returns the next nextStep: the next component, a retake request (with a reason) if capture quality was insufficient, or completed.
  4. Result — on completion the terminal state and (for stored tiers) the resulting Customer / Digital Identity are available; the backend can also be notified by webhook.

The nextStep model​

Each nextStep names the capture component to launch and any parameters (for example a server-issued liveness challenge). The client does not need to know the workflow in advance — it simply follows the steps the API returns. Available components are covered in the Mobile SDK and Web Components pages.

Retries and limits​

Capture steps enforce a per-step retake budget (poor-quality captures are re-prompted) and per-IP anti-hammering limits. Exhausting the retake budget ends the session as Incomplete. These limits are configurable per workflow — see Administration → IDV Configuration.

See also​