Enrolment

Redirect to Web Enrolment

After successfully generating a token you should have a valid accessToken and webEnrolmentUrl.

You may initiate a HTTP redirect action for your client to the provided URL, for example:

  • /web-enrolment/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uSWQiOiJhZDkwYzgyMS1lNWVhLTQzODUtYmU1Yi00ZmM5ZjllYTI0ZWU iLCJjdXN0b21lciI6IjEyZjUwMjM1LWFkNmYtNDVmNi1iOGM1LTE2ZGM1N2QwOTI1MyIsIm5iZiI6MTY0Mzk3NDMyMywiZXhwIjoxNjQzOTc3OTIzfQ.t5zU

After the redirection, the user will see our WEB Enrolment UI:

The number of steps depends on the configuration; the standard configuration is a document capture followed by a face capture. After completion of these steps, the user is redirected to the URL defined in returnUrl attribute earlier.

iFrame

If you prefer to avoid redirecting your customers to external pages, you can use iframe approach, i.e. to insert URL of webEnrolmentUrl (appended by iframe parameter set to true &iframe=true) attribute into iframe tag of your page - so user will remain on your page all the time.

To force the iframe to use a locale, append an URL with following parameter: “&lang=<ISO 639-1 standard language code>”. List of the supported languages:

LanguageCode
Arabicar-SA
Czechcs-CZ
Danishda-DK
Englishen-US
Finnishfi-FI
Frenchfr-FR
French (Canada)fr-CA
Germande-DE
Hungarianhu-HU
Japanesejp-JP
Latvianlv-LV
Portuguesept-PT
Romanianro-RO
Slovaksk-SK
Spanishes-ES
Swedishsv-SE
Ukrainianuk-UA

crossDevice parameter

If for some reason you would like to skip QR screen in case of iframe integration, please add &crossDevice=false to the URL and you will be navigated to the next screen immediately. Please note this parameters works only in case of iframe, i.e. if there is &iframe=true parameter!

onlyMobile parameter

If for some reason you wish to disable session continuity or the desktop (remove the [Continue on this device] button) during iframe integration, please append &onlyMobile=true to the URL. Please note that this parameter only works in the case of iframe, i.e., when there is the &iframe=true parameter.

Event Listener

Please set Event Listener (check it below) to wait for the event of the process finishing. This event contains data object with following markers of session completion: data.hasCompleted or data.hasError. data.hasError means it is not possible to continue the process, a new session should be initialized. This is the list of possible errors, it is possible to create a custom screen for each error if needed:

  • SESSION_ALREADY_COMPLETED
  • SESSION_UNAUTHORIZED
  • INTERNAL_ERROR

Please find example of the web page containing iframe:

<!DOCTYPE html>
<html>
<body>
    <iframe src='https://<domain name>/web-enrolment/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uSWQiOiI
    1MzU2YTA4Yi03NzIzLTQzOTgtYTgyNi00MTc4ZGFiYzZjMjkiLCJ0ZW5hbnQiOiJyb290IiwibmJmIjoxNjY2MjY0NzIxLCJleHAiOjE2NjYyNjgzMjF
    9.nbyhHhv2Yl2kjp9pfYKw3wOwv4rLFE4ZgTCPYj9Esk4&iframe=true&lang=en-US' style='width:70%;height:750px;' allow='camera'></iframe>
    <script type="text/javascript">
      window.addEventListener("message", enrolmentCompleted, false);
      function enrolmentCompleted(event) {
        const data = event.data;
        if (data.hasCompleted) {
          console.log('Session ID: ' + data.sessionId);
          // Success
        } else if (data.hasError) {
          console.log('Error: ' + data.error);
          // Error handling
        }
      }
    </script>
</body>
</html>

‘data’ object description:

interface IframeEventData {
  sessionId: string;
  hasCompleted: boolean;
  hasError: boolean;
  error?: string;
}

Direct Processing

If you choose to use your own image capture solution, feel free to bypass the steps mentioned above and move straight to the endpoints detailed in the following section. This allows you to integrate your existing system seamlessly with our service.

Document

To send document images to the API. Endpoint requires a JWT in the header (Authorization: Bearer).

Send a HTTP POST request to:

  • /api/v1/enrolment/document

The following parameters are used for requests and responses:

ParameterDirectionDescription
imageBaserequestonboarded person document, Base64 format or URL link to it
hasErrorresponsetrue if there was an error, false if the result is ok
errorresponseoptional, available if hasError= true. Error description
isTwoSideDocumentresponsetrue if document has 2 sides (ID card, driver license), false if it is not (passport)
pageSideresponseFRONT or BACK
countryresponseISO 3166 Alpha-3 country code
typeresponsedocument type, IDENTITY_CARD, PASSPORT etc.

If you scan two sides document, you should call this endpoint twice, one call per each side - it is important to start with a front side!

List of errors

ErrorDescription
DOCUMENT_NOT_RECOGNIZEDThe document image submitted could not be recognized by the API.
FACE_QUALITY_LOWThe quality of the face (on the document) in the image is too low for reliable recognition.
INTERNAL_ERRORAn internal error occurred while processing the submitted document image.
SESSION_ALREADY_COMPLETEDThe session has already been completed and cannot be reused.
WRONG_SIDEThe wrong side of the document has been submitted to the API.
Request:
{
  "imageBase": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQEBAQIBAQECAgICAgQDAgICAgUEBAMEBgUGBgYFBgYGBwkIBgcJBwYGCAsICQoKCgoKBggLDAsKDAkKCgr"
}

Response:
{
  "hasError": false,
  "isTwoSideDocument": true,
  "pageSide": "FRONT",
  "country": "SVK",
  "type": "IDENTITY_CARD"
}

Example:
curl -X POST "https://<domain name>/api/v1/enrolment/document" -H  "accept: application/json" -H  "Authorization: Bearer eyJhbGciOiJIUzI1NiasIn
f5cCI6IkpXVCJ9.eyJzZXNzaW9uSWQiOiIzZmE4NWY2NC01NzE3LTQ1NjItYjNmYy0yYzk2M2Y2NmFmYmMiLCJ0ZW5hbnQiO
 iJkb2NzIiwibmJmIjoxNjY2MjcwNjY1LCJleHAiOjE2NjYyNzQyNjV9.Y4rxrcFYf4nJ6aR3VII7rkPfX69JTKcDVyTDRPgON1w" -H
 "Content-Type: application/json" -d "{\"imageBase\":\"/9j/4Rd1RXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUAAAABAAAAYgEbAA
 UAAAABAAAAagEoAAMAAAABAAIAAAExAAIAAAAiAAAAcgEyAAIAAAAUAAAAlI..."

Face

To send a face image to the API. Endpoint requires a JWT in header (Authorization: Bearer).

Send a HTTP POST request to:

  • /api/v1/enrolment/face

The following parameters are used for requests and responses:

ParameterDirectionDescription
imageBaserequestonboarded person photo, Base64 format or URL link to it
hasErrorresponsetrue if there was an error, false if the result is ok
errorresponseoptional, available if hasError= true. Error description

List of errors

ErrorDescription
FACE_ANGLE_TOO_LARGEYaw/pitch/roll angle is too big
FACE_CLOSE_TO_BORDERFace too close to border, face to be placed in the middle of the image
FACE_CROPPEDPart of the face is not visible
FACE_IS_OCCLUDEDPart of the face is coveered by some object
FACE_NOT_FOUNDFace not detected
FACE_TOO_CLOSEFace too close, distance to be increased
FACE_TOO_SMALLFace too close, distance to be decreased
SESSION_ALREADY_COMPLETEDThe session has already been completed and cannot be reused.
TOO_MANY_FACESMore than one face on the image
Request:
{
  "imageBase": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQEBAQIBAQECAgICAgQDAgICAgUEBAMEBgUGBgYFBgYGBwkIBgcJBwYGCAsICQoKCgoKBggLDAsKDAkKCgr"
}

Response:
{
  "hasError": false,
}

Example:
curl -X POST "https://<domain name>/api/v1/enrolment/face" -H  "accept: application/json" -H  "Authorization: Bearer eyJhbGciOiJIUzI1NiasInf5c
CI6IkpXVCJ9.eyJzZXNzaW9uSWQiOiIzZmE4NWY2NC01NzE3LTQ1NjItYjNmYy0yYzk2M2Y2NmFmYmMiLC
 J0ZW5hbnQiOiJkb2NzIiwibmJmIjoxNjY2MjcwNjY1LCJleHAiOjE2NjYyNzQyNjV9.Y4rxrcFYf4nJ6aR3VII7rkPfX69JTKcDVyTDRPgON1w"
 -H  "Content-Type: application/json" -d "{\"imageBase\":\"/9j/4Rd1RXhpZgAATU0AKgAAAAgABwESA
 AMAAAABAAEAAAEaAAUAAAABAAAAYgEbAAUAAAABAAAAagEoAAMAAAABAAIAAAExAAIAAAAiAAAAcgEyAAIAAAAUAAAAl"

Complete

To notify API about the end of the session. Endpoint requires a JWT in header (Authorization: Bearer).

Send a HTTP POST request to:

  • /api/v1/enrolment/complete

The following parameters are used for requests and responses:

ParameterDirectionDescription
customerReturnUrlresponsecustom page to be displayed by the client solution after completion of the onboarding process

List of errors

ErrorDescription
INTERNAL_ERRORAn internal error occurred while processing the session.
MISSING_DOCUMENT_AND_FACENo selfie and/or ID document images were provided in previous calls. These images are required for the operation to proceed.
SESSION_ALREADY_COMPLETEDThe session has already been completed and cannot be reused.
Response:
{
  "customerReturnUrl": "https://www.customer-sample.com/end-of-session/"",
}

Example:
curl -X POST "https://<domain name>/api/v1/enrolment/complete" -H  "accept: application/json" -H  "Authorization: Bearer eyJhbGciOiJIUzI1NiIsI
nR5cCI6IkpXVCJ9.eyJzZXNzaW9uSWQiOiI0ZmE4NWY2NC01NzE3LTQ1NjItYjNmYy00Yzk2d2
 Y2NmFmYTYiLCJ0ZW5hbnQiOiJkb2NzIiwibmJmIjoxNjY2MjgwNDY0LCJleHAiOjE2NjYyODQwNjR9.teoXFWRwlghDSvlGTS9QpA3pl6FF_Yjne3uS2BWgklc" -d ""