Create a new KYC session

The method creates a new KYC session for the selected scenario. Then upload images against the sessionId from the response with kyc/process, and read the result with kyc/session/status.

  • Method: POST
  • Path: kyc/session/create
  • Content-Type: application/json

Authorization

Pass the token in one of two ways:

  • the token: <jwt-token> header — a temporary JWT token obtained with user/login;
  • the token field in the request body — a permanent API token (UUID) from your account.

Without a token the request returns 401 access denied.


Request parameters

ParameterTypeRequiredDescription
schemaIdstring (UUID)yesVerification scenario ID. The scenario must be active and belong to your company
tokenstring (UUID)—Permanent API token, if the token header is not sent

Response

Successful response (200)

The response is the created session itself. The status field is the session status: idle for a new session.

{
  "sessionId": "00000000-0000-0000-0000-000000000000",
  "errors": [],
  "schemaId": "11111111-1111-1111-1111-111111111111",
  "status": "idle",
  "clientId": "",
  "spent": 0,
  "createdAt": "2026-03-19T10:00:00.000Z",
  "isClientNew": true,
  "clientKey": "",
  "secondsToLive": 3600,
  "responseTime": "2026-03-19T10:00:00.000Z",
  "results": [
    {
      "status": "idle",
      "type": "document",
      "spent": 0,
      "errors": [],
      "history": [],
      "isBackSide": false
    }
  ]
}
FieldTypeDescription
sessionIdstring (UUID)Session ID. Keep it: you need it to upload images and get the status
errorsarrayGeneral session errors; empty for a new session
schemaIdstring (UUID)Scenario the session was created with
selectedSchemaIdnullOnly in a session of linked scenarios: null until the first document selects the scenario
statusstringSession status, idle for a new session
clientIdstringClient ID; an empty string until the client is identified
spentnumberProcessing time in seconds
createdAtstring (ISO 8601)Session creation date and time
isClientNewbooleantrue — the client’s first visit
clientKeystringYour client identifier. It is set by the clientKey parameter when the session is created by kyc/process; an empty string for a session created with this method
secondsToLivenumberRemaining session lifetime in seconds
responseTimestring (ISO 8601)Response time
resultsarrayScenario steps; all are idle in a new session

Session of linked scenarios

If the scenario is linked with other scenarios, the session starts with one step — the first document. The recognized document determines which scenario the session continues with, and its steps are added. Until then selectedSchemaId is null and results holds one step.


Errors

ResponseCause
400 invalid schemaThe request body does not match the parameter description, e.g. schemaId is not a UUID
400 bad schemaIdschemaId is missing, or no active scenario of your company has this ID. No session is created
400 questionnaire is widget-onlyThe scenario has a questionnaire step: such a scenario is completed only in the widget
401 access deniedNo token, or the token is invalid. A JWT token goes only in the token header: in the request body it returns 400 invalid schema

Example of an error response:

{
  "status": "error",
  "message": "bad schemaId"
}

Request example

curl -X POST https://api.neuro-vision.ru/v1/kyc/session/create -H 'Content-Type: application/json' -H 'token: <jwt-token>' -d '{"schemaId": "11111111-1111-1111-1111-111111111111"}'

With a permanent API token in the request body:

curl -X POST https://api.neuro-vision.ru/v1/kyc/session/create -H 'Content-Type: application/json' -d '{"token": "<api-token>", "schemaId": "11111111-1111-1111-1111-111111111111"}'