Skip to main content

Start a new Digital Onboarding session

POST 
/v1/digital-onboarding/start

Start a New Digital Onboarding Session​

This endpoint starts a new Digital Onboarding session, which initializes the session and returns a session ID. A Digital Onboarding collects the user's identity document images, and runs a Document Analysis on them. When started with withLiveness, it also collects liveness selfie images, and runs a Face Match between the document and the selfies.

Request Body Details​

The country (ISO alpha 2 code) and the type of the document the user will capture are required. They are used to know whether both sides of the document are captured, and to verify them against the detected country and type. Combinations without a country specific schema are accepted too: both sides of the document are captured, and the Document Analysis falls back to a generic extraction.

Optionally, you can include a customerId to associate the session with an internal customer record. This allows the API to return the customerId in the response, making it easier to track who the Digital Onboarding session belongs to in your system.

Set withLiveness to true for the user to also take liveness selfies, matched against the document photo. It is false by default: only the document is captured.

Set runNationalRegistryLookup to true to also look the individual up in the national registry, using the data extracted from the document. It only runs for the country and document type combinations with a national registry provider: for the others, the result simply has no national registry lookup. Set failOnUnsupportedRegistryLookup to true as well to reject the session creation for those combinations instead.

Set runDocumentProof to true to also run Document Proof (anti-spoofing) on the document images: image manipulation, online duplicate, photocopy and suspicious words detection.

Example Flow​

  1. Initiate Session: Send the country and type of the document (and optionally customerId and withLiveness) to the startDigitalOnboardingSession endpoint.
  2. Response: The server returns a session ID that can be used to compose the URL to the Digital Onboarding client interface, where the user will capture the document images (and the liveness selfie images, with withLiveness).
  3. Liveness Verification: With withLiveness, the selfie images are checked for liveness, to ensure that the user is physically present and not using static or spoofed images.
  4. Session Usage: The same session ID can be used to track the status of the session, and to retrieve the results using the getDigitalOnboardingResult endpoint once the onboarding is done.
  5. Credits: No credits are deducted upon initiating the session. When the session is processed, the credits for a Document Analysis (plus Face Match with withLiveness, the national registry check with runNationalRegistryLookup, and Document Proof with runDocumentProof) are deducted. The credits of the operations that fail are refunded, and the session ends up PartiallyCompleted. If all of them fail, all the credits are refunded and the session ends up Failed.

Request​

Responses​