POST /kyc/session/reference
Description
The method binds a reference session to a future KYC session — a past successful session of the same person. When the user goes through the new session, the system compares their face with the face from the reference session.
The request involves two sessions:
- the reference session — a past session that has already succeeded. It is set by
referenceSessionUuid: the value of thesessionIdfield from the kyc/session/status response or from the webhook for that session. NotclientKey; - the future session — the session you are about to open. It is set by
clientKey: the same client key you will open the widget with, encrypted with the scenario secret key.
Call the method before you open the widget.
If the face does not match the reference, the session gets the suspicious status and closes (see Session statuses).
Request format
- HTTP method:
POST - URL:
/kyc/session/reference - Content type:
application/json
Authorization
Pass the token in one of two ways:
- the
token: <jwt-token>header — a temporary JWT token obtained with theuser/loginmethod; - the
tokenfield in the request body — a permanent API token (UUID) from the personal account.
Without a token the request returns 401 access denied. See Authentication for details.
Request parameters
| Parameter | Type | Passed in | Required | Description |
|---|---|---|---|---|
| token | string (UUID) | body | — | Permanent API token, if there is no token header |
| schemaId | string (UUID v1) | body | ✅ | ID of the scenario the future session will use |
| clientKey | string | body | ✅ | Client key of the future session, encrypted with the scenario secret key, in base64. From 1 to 100 characters. Encrypted the same way as when opening the widget |
| referenceSessionUuid | string (UUID v1) | body | ✅ | Reference session ID — the sessionId of a past successful session from the kyc/session/status response or the webhook. Not to be confused with clientKey |
| clientUser | string | body | ❌ | User ID in your system, from 1 to 36 characters. If it is set both here and in the reference session, the values must match |
Request example (cURL)
curl -X POST "https://api.neuro-vision.ru/v1/kyc/session/reference" -H "token: <jwt-token>" -H "Content-Type: application/json" -d '{"schemaId": "00000000-0000-1000-8000-000000000000", "clientKey": "<encrypted-client-key>", "referenceSessionUuid": "00000000-0000-1000-8000-000000000001", "clientUser": "user-0001"}' Reference session requirements
- It belongs to you.
- It finished successfully.
- Its document is confirmed and its face is saved.
Only one reference session can be bound to one clientKey. A repeated call with the same reference session succeeds; with a different one it returns the reference_conflict error. If there is already a successful session for this clientKey, a reference cannot be bound.
Comparison result
The result comes in the faceReference block of the kyc/session/status response and in the SESSION_COMPLETE webhook (see Webhooks). The block holds no personal data, so it also comes in the mode without personal data.
| Field | Type | Description |
|---|---|---|
| sessionId | string or null | Reference session ID (the one passed in referenceSessionUuid). null if no reference is bound |
| matched | boolean or null | Whether it is the same person. Changes only when reason is matched or mismatch, so read it together with reason. null until a comparison has produced an answer |
| reason | string | Comparison outcome, see below |
| reason | Meaning |
|---|---|
matched | Compared — the same person |
mismatch | Compared — a different person |
reference_unusable | The reference is no longer suitable: deleted, no longer successful, or has no face to compare. Bind another one |
reference_missing | The scenario requires a reference, but none is bound for this clientKey |
no_own_face | The reference is fine, but this session has no face to compare |
compare_failed | The comparison could not be performed. This is not a conclusion about the person |
stale | The result belongs to a previous attempt of the session, and the latest attempt did not reach the comparison |
not_evaluated | No comparison was performed: the steps did not finish successfully or the session expired |
Only mismatch means a different person.
Response examples
Success (200 OK)
{
"status": "ok"
} Error (400 Bad Request)
{
"status": "error",
"reason": "reference_not_success",
"message": "reference_not_success"
} | reason | message | When |
|---|---|---|
invalid_schema | invalid schema | The body does not match the schema. The details field names the invalid fields |
bad_schema_id | bad schemaId | You have no scenario with this schemaId |
schema_secret_key_not_configured | schema secret key not configured | The scenario has no secret key |
bad_encrypted_client_key | bad encrypted client key value | clientKey cannot be decrypted with the scenario secret key |
bad_client_key | bad_client_key | clientKey is empty after decryption |
client_key_finalized | client_key_finalized | There is already a successful session for this clientKey |
reference_not_found | reference_not_found | You have no session with this referenceSessionUuid |
reference_not_success | reference_not_success | The reference session did not finish successfully |
reference_no_document | reference_no_document | The reference session has no confirmed document |
reference_no_face | reference_no_face | The reference session has no saved face |
reference_embedding_mismatch | reference_embedding_mismatch | The face of the reference session cannot be compared with a new image. Choose a more recent session |
reference_client_user_mismatch | reference_client_user_mismatch | clientUser does not match the clientUser of the reference session |
reference_conflict | reference_conflict | Another reference session is already bound to this clientKey |
Session busy (409 Conflict)
The session for this clientKey is being processed. Retry later.
{
"status": "error",
"message": "[request] session is busy"
} Temporarily unavailable (503 Service Unavailable)
{
"status": "error",
"reason": "storage_unavailable",
"message": "storage_unavailable"
} Retry later.
Error (500 Internal Server Error)
{
"status": "error",
"message": "internal error"
}