Recognize documents and selfies from images

Purpose

The web widget uploads for your user. Use this call when you capture images yourself and want to send them from your backend. The platform detects the kind of each image, takes it to the first step that accepts it, and answers with the session.

Request

POST <API_BASE_URL>/kyc/process. All calls are POST under your API address. Replace <API_BASE_URL> with the API address provided with your access.

Send a permanent API token in the token field of the body, or a user token in the token header. See authentication.

Content type: multipart/form-data. Send the fields as a multipart form.

Field	Type	Required	Description
`token`	string (uuid)	if no header	Your permanent API token. Required unless you send a user token in the `token` header.
`images`	array of file	yes	The image files. With `stepIndex`, send exactly one.
`sessionId`	string (uuid)	no	An existing session. A new session is created when it is empty or unknown.
`schemaId`	string (uuid)	no	The scenario identifier, for a new session.
`mode`	string	no	`sync`, the default, waits for the complete session result. `async` answers at once with a session in `processing` and no results.
`clientKey`	string	no	Your own identifier for the person.
`clientUser`	string	no	Your own identifier for the operator. It need not be unique.
`stepIndex`	string	no	The zero-based position of the scenario step the image is for, as in `results` of the session. When given, the image is matched against that step only.
`ocr`	boolean	no	Whether to recognize the text of a document. On by default.

Each step takes a limited number of tries. When the upload that reaches the limit fails, the step gets the error [general] too many tries and the session is blocked. See the session object.

Response

HTTP 200. The upload was accepted. The body is the session.

Field	Type	Description
`status`	string	The session status: `success`, `failed` or `processing`. It is not the `ok` or `error` of an envelope. In `async` mode it is always `processing` with an empty `results`; poll session status.
`results`	array of object	One entry per step. See the session object.

Errors

400: The request was refused and nothing in the session changed: no image is processed and no try is charged. Typical messages name an invalid schema with details, a missing image, or an invalid stepIndex with a reason: out of range, step kind mismatch, single image required or step closed.
401: The token is missing, expired or unknown.
409: The session was busy with another request for the whole wait. Nothing of this request was applied. Repeat it once the other request has been answered.

A refusal can also come before the operation runs: an address outside your IP allowlist, a token bound to another address, or a body that is not valid JSON. See response format and errors.

Example

Request:

curl -X POST "<API_BASE_URL>/kyc/process" \
  -F "token=<your permanent API token>" \
  -F "schemaId=<your scenario id>" \
  -F "mode=async" \
  -F "images=@document.jpg" \
  -F "images=@selfie.jpg"

Response:

{
  "sessionId": "00000000-0000-0000-0000-000000000000",
  "status": "processing",
  "schemaId": "<your scenario id>",
  "clientKey": "<your identifier for the person>",
  "secondsToLive": 3600,
  "createdAt": "2026-01-01T10:00:00.000Z",
  "errors": [],
  "results": []
}