Bind reference session

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 the sessionId field from the kyc/session/status response or from the webhook for that session. Not clientKey;
  • 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 the user/login method;
  • the token field 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

ParameterTypePassed inRequiredDescription
tokenstring (UUID)body—Permanent API token, if there is no token header
schemaIdstring (UUID v1)body✅ID of the scenario the future session will use
clientKeystringbody✅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
referenceSessionUuidstring (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
clientUserstringbody❌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.

FieldTypeDescription
sessionIdstring or nullReference session ID (the one passed in referenceSessionUuid). null if no reference is bound
matchedboolean or nullWhether 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
reasonstringComparison outcome, see below
reasonMeaning
matchedCompared — the same person
mismatchCompared — a different person
reference_unusableThe reference is no longer suitable: deleted, no longer successful, or has no face to compare. Bind another one
reference_missingThe scenario requires a reference, but none is bound for this clientKey
no_own_faceThe reference is fine, but this session has no face to compare
compare_failedThe comparison could not be performed. This is not a conclusion about the person
staleThe result belongs to a previous attempt of the session, and the latest attempt did not reach the comparison
not_evaluatedNo 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"
}
reasonmessageWhen
invalid_schemainvalid schemaThe body does not match the schema. The details field names the invalid fields
bad_schema_idbad schemaIdYou have no scenario with this schemaId
schema_secret_key_not_configuredschema secret key not configuredThe scenario has no secret key
bad_encrypted_client_keybad encrypted client key valueclientKey cannot be decrypted with the scenario secret key
bad_client_keybad_client_keyclientKey is empty after decryption
client_key_finalizedclient_key_finalizedThere is already a successful session for this clientKey
reference_not_foundreference_not_foundYou have no session with this referenceSessionUuid
reference_not_successreference_not_successThe reference session did not finish successfully
reference_no_documentreference_no_documentThe reference session has no confirmed document
reference_no_facereference_no_faceThe reference session has no saved face
reference_embedding_mismatchreference_embedding_mismatchThe face of the reference session cannot be compared with a new image. Choose a more recent session
reference_client_user_mismatchreference_client_user_mismatchclientUser does not match the clientUser of the reference session
reference_conflictreference_conflictAnother 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"
}