REST API: KYC
The session object
One object describes a session and all its steps.
Where it appears
Create session, session status, list sessions, filter sessions and recognize documents and selfies all return this object, or a list of it. The same object is what the widget hands to your page when a session succeeds.
Top-level fields
| Field | Type | Description |
|---|---|---|
sessionId | string (uuid) | The identifier of the session. Every other KYC operation takes it. |
status | string | The session status. See session statuses. |
schemaId | string (uuid) | The scenario the session was created from. |
clientId | string | The identity the session resolved to. Empty until the documents are recognized. |
clientKey | string | Your own identifier for the person, echoed back. See working with clientKey. |
clientUser | string | Your own identifier for the operator, echoed back. It need not be unique. |
isClientNew | boolean | Whether the resolved identity had not been seen on this account before. |
spent | number | Seconds from the creation of the session to the moment it first reached a final status; zero while it has not. |
secondsToLive | number | Seconds left before the session expires. At zero an idle or processing session is reported as expired. |
createdAt | string (date-time) | When the session was created. |
responseTime | string (date-time) | When this answer was built, by the server clock. |
errors | array of string | Session-level error codes. They are symbolic codes, not prose. |
results | array of object | One entry per step of the scenario. |
pdErased | boolean | true from the moment the destruction of personal data began. The object keeps identifiers, statuses, errors and verdicts and carries no recognized value, contact or media link. |
pdErasedAt | string (date-time) | When the destruction was completed, a UTC timestamp. Null while it is not complete. |
The results list
results holds one entry per step of the scenario, in order, and the faces entry last. While a session is still being processed asynchronously it can be empty, and the results are read back with session status. The fields below depend on the kind of step.
| Field | Type | Description |
|---|---|---|
results[].type | string | The kind of step: document, passport, id card, passport address, driving license, address_proof, selfie, liveness, faces or questionnaire. The faces entry is the face matching of the session: it is always present, it comes last, and the session does not pass without it. |
results[].status | string | The status of the step. It is forced to failed whenever errors is not empty. |
results[].errors | array of string | Symbolic error codes of the step. Treat an unknown entry as a failure with an unknown reason. |
results[].tries | number | Uploads made against the step. Absent when the step was never attempted. |
results[].startedAt | string (date-time) | The start of the current attempt at the step. |
results[].history | array of object | Earlier attempts at the step, oldest first. Filled from the second upload onwards. |
results[].docName | string | The recognized document, on document steps. |
results[].countryCode | string | The issuing country of the recognized document, on document steps. |
results[].isBackSide | boolean | Whether the image is the back side, on document steps. |
results[].ocr | string or object | The recognized fields of a document or address proof step, or the string Access denied. |
results[].checks | string or array of object | The verification groups run against the step, or the string Access denied. |
results[].images | array of string | Thumbnail links, one per upload attempt. |
results[].faceSelfie | string | On a successful selfie step, the face taken from the selfie. |
results[].faces | array of string | On liveness steps, the faces captured during the challenge. |
results[].video | string | On liveness steps, the recorded video, present only when it was stored. |
results[].triesLeft | number | On liveness steps, the attempts still available. Zero means the step is over. |
results[].verified | boolean or null | On liveness steps, whether the verifying services confirmed a live person on the last charged attempt. Null while no attempt has been charged. It is false on an attempt that was judged without them, so a passing attempt can be unverified. |
results[].outcome | object or null | On liveness steps, how the last attempt ended, including attempts that cost nothing and are therefore invisible in errors and in status. Null before the first commit. outcome.class is one of success, verdict, technical, unverified and exhausted; outcome.code is a reason code in the shape of errors. |
results[].attempts | array of object | On liveness steps, one entry per charged attempt, oldest first, each with its number, time, class (success, verdict or unverified), code and verified. An attempt that cost nothing leaves no entry. |
results[].retake | array of integer | On the faces entry: the positions in results of the steps to shoot again after a failed face matching. |
Reading it correctly
- Branch on
statusof the session and of each step, never on message text. See response format and errors. - A successful status alone does not establish verified liveness. On a liveness step, read
verifiedandoutcome.classas well.successmeans the attempt passed and was verified.unverifiedmeans it passed without the verifying services.verdictmeans it was refused on a judgement about the person and the attempt is spent.technicalmeans the machinery failed and the attempt is given back.exhaustedmeans the budget is gone. Decide in your own flow whether an unverified pass is enough for the customer. - A step with errors is
failed, whatever else it holds. A session does not pass without thefacesentry passing. - Media links need the same
tokenheader as the API when you fetch them. - Verdicts of database checks are not in this object. Read them with database check results.
- After an erasure request
pdErasedistrueand the personal values are gone. See erase session personal data.