Session status - NeuroVision

Get the status and results of a KYC session by sessionId or clientKey.

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

Authorization

Two authorization methods are supported:

1. JWT token in the `token` header:

token: <jwt-token>

2. API Token (timeuuid) in the request body:

{"token": "<api-token>", "sessionId": "..."}

Without a token (neither in the header nor in the body), the request will return "access denied".

Query Parameters

Parameter	Type	Required	Description
`sessionId`	string (timeuuid)	no*	Session UUID v1 (timeuuid)
`clientKey`	string (non-empty)	no*	Client key (non-empty string, max 36 characters)

* At least one of the parameters sessionId or clientKey must be specified.

Parameter Priority

If both parameters are passed simultaneously, clientKey takes precedence — the search will be performed by clientKey, sessionId will be ignored.

Limitations

sessionId must be a valid timeuuid (UUID v1)
clientKey — a non-empty string with a maximum length of 36 characters

Response format

Successful Response (200)

{
  "status": "success",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "errors": [],
  "schemaId": "660e8400-e29b-41d4-a716-446655440000",
  "clientId": "770e8400-e29b-41d4-a716-446655440000",
  "spent": 24.184,
  "createdAt": "2026-03-19T10:31:06.000Z",
  "isClientNew": false,
  "clientKey": "my_client_key_123",
  "clientUser": "",
  "secondsToLive": 0,
  "responseTime": "2026-03-19T10:31:30.000Z",
  "results": [...],
  "email": "user@example.com",
  "wallet": "0x1234...abcd"
}

Description of response fields

Field	Type	Description
`status`	string	Session status (see table below)
`sessionId`	string (timeuuid)	Session UUID v1 (timeuuid)
`errors`	array	General session errors
`schemaId`	string (UUID)	KYC schema UUID
`clientId`	string (UUID)	Client UUID (empty string if client is not identified)
`spent`	number	Total processing time in seconds
`createdAt`	string (ISO 8601)	Session creation date and time
`isClientNew`	boolean	`true` — first client visit, `false` — repeat visit
`clientKey`	string	Client key passed during session creation
`clientUser`	string	Client user identifier
`secondsToLive`	number	Remaining session lifetime in seconds (0 = expired)
`responseTime`	string (ISO 8601)	Response generation time
`results`	array	Array of task results (see below)
`email`	string	Client email (optional)
`wallet`	string	Client crypto wallet address (optional)

Session Statuses

Status	Description
`idle`	Session created, processing not started
`processing`	Session is being processed
`success`	All tasks completed successfully
`failed`	One or more tasks failed
`exception`	System error occurred
`expired`	Session lifetime expired

Task Results

The results array contains the results for each KYC session task. Task types: document, selfie, faces.

`document` type task

{
  "status": "success",
  "type": "document",
  "spent": 1.367,
  "errors": [],
  "docName": "Passport (2006)",
  "tries": 1,
  "startedAt": "2026-03-19T10:31:08.000Z",
  "isBackSide": false,
  "countryCode": "RUS",
  "checks": [
    {
      "caption": "fraud",
      "items": [
        { "status": "success", "caption": "isPrinted", "confidence": 1 },
        { "status": "success", "caption": "isEdited", "confidence": 0.001 },
        { "status": "success", "caption": "isDisplay", "confidence": 0.938 }
      ]
    }
  ],
  "ocr": {
    "status": "success",
    "fields": [
      { "title": "Surname", "value": "DOE", "conf": "high" },
      { "title": "Given name(s)", "value": "JOHN", "conf": "high" },
      { "title": "Date of birth", "value": "01.01.1970", "conf": "high" }
    ]
  },
  "images": ["https://api.example.com/images/kyc/.../document_0/0"],
  "imagesFull": ["https://api.example.com/images/kycfull/.../document_0_0.jpg"],
  "imageObjects": ["https://api.example.com/images/kyc/.../stamp/0"],
  "history": [...]
}

Field	Type	Description
`status`	string	Task status: `idle`, `processing`, `success`, `failed`
`type`	string	Task type: `document`
`spent`	number	Processing time in seconds
`errors`	array	Processing errors (e.g. `"[document] unknown document type"`)
`docName`	string	Recognized document type (e.g. `"Passport (2006)"`, `"ePassport (2005-2008)"`)
`tries`	number	Number of recognition attempts
`startedAt`	string (ISO 8601)	Processing start time
`isBackSide`	boolean	Is it the back side of the document
`countryCode`	string	Document country code (ISO 3166-1 alpha-3)
`checks`	array	Check results (fraud checks)
`ocr`	object	Text recognition results
`images`	array	Links to processed images (thumbnails)
`imagesFull`	array	Links to full-size images
`imageObjects`	array	Links to recognized objects (stamps, signatures)
`history`	array	History of previous attempts (if `tries` > 1)

`selfie` type task

{
  "status": "success",
  "type": "selfie",
  "spent": 0.14,
  "errors": [],
  "docName": "Passport (2006)",
  "tries": 1,
  "withDoc": ["Domestic passport"],
  "checks": [
    {
      "caption": "fraud",
      "items": [
        { "status": "success", "caption": "isFaceDeepFake" },
        { "status": "success", "caption": "isAgeMismatch", "value": 15 },
        { "status": "success", "caption": "isDisplaySelfie", "confidence": 1 },
        { "status": "success", "caption": "isGenderMismatch", "value": "female" }
      ]
    }
  ],
  "faceSelfie": "https://api.example.com/images/kycthumb/.../selfie/0",
  "faceDoc": "https://api.example.com/images/kycthumb/.../selfie_document/0",
  "images": ["https://api.example.com/images/kyc/.../selfie_0/0"],
  "imagesFull": ["https://api.example.com/images/kycfull/.../selfie_0_0.jpg"]
}

Field	Type	Description
`withDoc`	array/string	Document(s) to which the selfie is matched
`faceSelfie`	string	Link to the face cutout from the selfie
`faceDoc`	string	Link to the face cutout from the document

`faces` type task

Face comparison result. Appears when both a document and a selfie are present in the session.

{
  "status": "success",
  "type": "faces",
  "spent": 0.003,
  "errors": [],
  "checks": [
    {
      "caption": "Face matching",
      "items": [
        {
          "status": "success",
          "caption": "document_0 & selfie",
          "value": "92%",
          "images": [
            "https://api.example.com/images/kycthumb/.../document_0",
            "https://api.example.com/images/kycthumb/.../selfie"
          ]
        },
        {
          "status": "success",
          "caption": "document_0 & selfie_document",
          "value": "96%",
          "images": [...]
        }
      ]
    }
  ]
}

Field	Type	Description
`checks[].items[].value`	string	Percentage of face match
`checks[].items[].images`	array	Pair of compared images

Errors

Invalid schema (400)

If the parameter format is violated:

{
  "status": "error",
  "message": "invalid schema",
  "details": [
    {
      "expected": {},
      "actual": "not-a-uuid",
      "path": "sessionId"
    }
  ]
}

Typical causes:

sessionId is not a valid timeuuid (UUID v1)
clientKey is longer than 36 characters
clientKey — empty string

Session not found (200)

{
  "status": "error",
  "message": "session not found"
}

Possible causes:

Sessions with the specified sessionId or clientKey do not exist

Identifier not specified (400)

{
  "status": "error",
  "message": "sessionId or clientKey is required"
}

Occurs when neither sessionId nor clientKey is passed in the body.

No authorization (401)

{
  "status": "error",
  "message": "access denied"
}

Example Queries

Search by sessionId

curl -X POST https://api.neuro-vision.ru/v1/kyc/session/status 
  -H 'Content-Type: application/json' 
  -H 'token: <jwt-token>' 
  -d '{"sessionId": "550e8400-e29b-41d4-a716-446655440000"}'

Search by clientKey

curl -X POST https://api.neuro-vision.ru/v1/kyc/session/status 
  -H 'Content-Type: application/json' 
  -H 'token: <jwt-token>' 
  -d '{"clientKey": "my_client_key_123"}'

Typical fraud checks

For documents (`type: "document"`)

Caption	Description
`isMRZValid`	MRZ zone validity
`isStampsOk`	Stamp/seal check
`isPrinted`	Document is printed (not a screen photo)
`isDamaged`	Document is not damaged
`isOtherObjectsOk`	No extraneous objects
`isXerocopy`	Document is not a xerocopy
`isEdited`	Document is not edited
`isSignatureOwnerOk`	Owner’s signature
`isSignatureIssuerOk`	Issuer’s signature
`isDisplay`	Document is not photographed from a screen
`isFieldsModified`	Fields are not modified
`isCropped`	Document is not cropped
`isFieldsCorrected`	Fields are not corrected
`isMobile`	Taken with a mobile device
`isPhotoApplication`	Photo without an editor application
`isLogicalMismatch`	No logical mismatches

For selfies (`type: "selfie"`)

Caption	Description
`isFaceDeepFake`	Deepfake check
`isAgeMismatch`	Age match (value = difference in years)
`isCropped`	Photo is not cropped
`isXerocopy`	Not a xerocopy
`isGenderMismatch`	Gender match (value = determined gender)
`isDisplaySelfie`	Not a screen photo
`isMobile`	Taken with a mobile device