Skip to main content
API docs by Redocly

Capture API (0.1.0)

Download OpenAPI specification:Download

Frontend Capture API — endpoints used by mobile Apps and the IDV redirect web to collect data.

Authentication

  • POST /api/v1/session: Authorization: Bearer with a Keycloak access token

Health

Service health check

Health check

Returns { status: "ok" } when the service is up.

Responses

Response samples

Content type
{
  • "status": "ok"
}

Session

Create an ID verification workflow session

Create a new session

Creates a frontend session for the onboarding flow.

Gateway must inject x-org-id header before forwarding the request.

Returns a sessionToken (JWT) that must be passed as X-Session-Token on GET /info and POST /submit. Also returns the ordered steps[] list and nextStep (first step to render).

Call GET /info to retrieve locale and branding URLs before starting submissions.

Error codes:

  • NO_ACTIVE_FLOW (400) — customer has no active flow configured
  • SANDBOX_LIMIT_REACHED (403) — sandbox time or verification limit exceeded
header Parameters
x-org-id
required
string

Organization ID injected by gateway

Request Body schema:
required
object
workflowId
string

Requested workflow ID. Defaults to the customer's default workflow if omitted.

enrolmentCustomerId
string

ID of the customer that is targeted with this workflow.

Responses

Request samples

Content type
{
  • "configuration": {
    },
  • "workflowId": "string",
  • "enrolmentCustomerId": "string"
}

Response samples

Content type
{
  • "nextStep": {
    },
  • "sessionToken": "string",
  • "steps": [
    ],
  • "workflowId": "string"
}

Info

Session information and steps

Get session and workflow steps

Returns locale, branding URLs and the ordered workflow step list for this session.

Call this once after POST /session before starting step submissions.

Error codes:

  • SESSION_NOT_FOUND (404) — session token is missing or expired
  • INVALID_TOKEN (401) — token signature is invalid
header Parameters
x-session-token
required
string

JWT session token obtained from POST /session

Responses

Response samples

Content type
{
  • "locale": "string",
  • "logoUrl": "string",
  • "rejectedUrl": "string",
  • "steps": [
    ],
  • "unverifiedUrl": "string",
  • "verifiedUrl": "string"
}

Submit

Upload step data to advance to the next step in the workflow

Submit current step data

Advances the session through the current workflow step.

The server reads the current step from the session — the client never sends a step name.

Set cancel: true to abort from any step. The captured data is deleted and the session ends.

Business-logic errors are returned as HTTP 200 with an error object in the body. The nextStep always indicates where the flow is now (step id only — resolve metadata from session steps[]).

On a tenant that stores records, the outcome may still be settling when the captures are complete: nextStep.step is then enrolment_pending rather than complete, so the client can show a pending state, and the final result arrives on the configured callback. On a tenant that stores nothing, the result is delivered on the callback and is not included in this response.

Error codes (4xx/5xx):

  • SESSION_NOT_FOUND (404) — session token is missing or expired
  • INVALID_TOKEN (401) — token signature is invalid
header Parameters
x-session-token
required
string

JWT session token obtained from POST /session

Request Body schema:
required
boolean or "true" (string) or "false" (string)

Abort the verification. When true, the server deletes the session.

boolean or "true" (string) or "false" (string)

Abort the workflow if the step performed on a phone after redirect aborts.

string or string or any

Image or NFC data capture in the proprietary format from the capture components — required when the current step's requiresFile is true.

redirectToken
string

If the process continues after redirection on the phone, provide the redirection token here to continue the session.

number or string

Number of steps to skip from the current position. Only steps whose skippable flag is true can be skipped.

Responses

Request samples

Content type
{
  • "cancel": true,
  • "clearRedirectToken": true,
  • "file": "File",
  • "redirectToken": "string",
  • "skipSteps": 1
}

Response samples

Content type
{
  • "error": {
    },
  • "nextStep": {
    }
}

Result

Read the verification result of the current session

Read the verification result of this session

Returns the full Digital Identity data of the run this session performed: the extracted fields plus an images object whose property names are the slot names accepted by GET /api/v1/result/images/{slot}.

Session-scoped by design: the identity is resolved from the session token alone, so a client can never address another run, and no tenant-wide Customer API credentials are needed. That is what lets a native mobile app without a backend receiver render its own result screen.

Works for successful and rejected runs, and also mid-flow — the identity belongs to the session either way.

The session token lives on the user device, so treat anything read here as a display value and confirm the verification server-side from the callback before granting access.

Error codes:

  • SESSION_EXPIRED (401) — the session token is invalid or expired
  • NOT_FOUND (404) — the session no longer exists
  • RESULT_NOT_FOUND (404) — the identity of this session does not exist in the customer store yet
  • RESULT_SOURCE_NOT_CONFIGURED (503) — the result source is not configured on this deployment
  • RESULT_SOURCE_ERROR (502) — the result source returned an unexpected error
header Parameters
x-session-token
required
string

JWT session token obtained from POST /session

Responses

Response samples

Content type
application/json
{
  • "identity_id": "string",
  • "customer_id": "string",
  • "decision": "string",
  • "state": "string",
  • "status": "string",
  • "workflow_name": "string",
  • "name": "string",
  • "given_name": "string",
  • "surname": "string",
  • "date_of_birth": "2019-08-24",
  • "date_of_birth_raw": "string",
  • "date_of_expiry": "2019-08-24",
  • "document_number": "string",
  • "issuing_country": "string",
  • "personal_number": "string",
  • "place_of_birth": "string",
  • "chip_data": null,
  • "images": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Stream one captured image of this session result

Streams one captured image of the Digital Identity of this session, addressed by slot name. The identity id comes from the session itself, so a client can never read the images of another run.

Supports If-None-Match: pass back the ETag from a previous response to receive 304 Not Modified instead of the bytes.

Error codes:

  • SESSION_EXPIRED (401) — the session token is invalid or expired
  • RESULT_NOT_FOUND (404) — no image is stored in that slot for this run
  • RESULT_SOURCE_ERROR (502) — the result source returned an unexpected error
path Parameters
slot
required
string
Enum: "document_front" "document_back" "document_portrait" "document_chip_portrait" "selfie" "selfie_crop" "selfie_raw"

Image slot name — one of the property names of the images object returned by GET /api/v1/result.

header Parameters
x-session-token
required
string

JWT session token obtained from POST /session

If-None-Match
string

ETag of a previously fetched copy of this image.

Responses

Response samples

Content type
{
  • "error": {
    }
}