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:

Language	Code
Arabic	ar-SA
Czech	cs-CZ
Danish	da-DK
English	en-US
Finnish	fi-FI
French	fr-FR
French (Canada)	fr-CA
German	de-DE
Hungarian	hu-HU
Japanese	jp-JP
Latvian	lv-LV
Romanian	ro-RO
Slovak	sk-SK
Spanish	es-ES
Swedish	sv-SE
Ukrainian	uk-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>

💡

It is recommended to monitor is the process is finished (data.hasCompleted= true) to continue with the workflow (close an iframe, display 'Thank you!' screen etc.)

💡

Please be aware of the security aspect and consider the potential necessity to control (limit) the origin of messages posted by the iframe described above (for more details, please refer to: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#security_concerns)

‘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:

Parameter	Direction	Description
imageBase	request	onboarded person document, Base64 format or URL link to it
hasError	response	`true` if there was an error, `false` if the result is ok
error	response	optional, available if hasError= `true`. Error description
isTwoSideDocument	response	`true` if document has 2 sides (ID card, driver license), `false` if it is not (passport)
pageSide	response	FRONT or BACK
country	response	ISO 3166 Alpha-3 country code
type	response	document 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

Error	Description
DOCUMENT_NOT_RECOGNIZED	The document image submitted could not be recognized by the API.
FACE_QUALITY_LOW	The quality of the face (on the document) in the image is too low for reliable recognition.
INTERNAL_ERROR	An internal error occurred while processing the submitted document image.
SESSION_ALREADY_COMPLETED	The session has already been completed and cannot be reused.
WRONG_SIDE	The 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:

Parameter	Direction	Description
imageBase	request	onboarded person photo, Base64 format or URL link to it
hasError	response	`true` if there was an error, `false` if the result is ok
error	response	optional, available if hasError= `true`. Error description

List of errors

Error	Description
FACE_ANGLE_TOO_LARGE	Yaw/pitch/roll angle is too big
FACE_CLOSE_TO_BORDER	Face too close to border, face to be placed in the middle of the image
FACE_CROPPED	Part of the face is not visible
FACE_IS_OCCLUDED	Part of the face is coveered by some object
FACE_NOT_FOUND	Face not detected
FACE_TOO_CLOSE	Face too close, distance to be increased
FACE_TOO_SMALL	Face too close, distance to be decreased
SESSION_ALREADY_COMPLETED	The session has already been completed and cannot be reused.
TOO_MANY_FACES	More 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:

Parameter	Direction	Description
customerReturnUrl	response	custom page to be displayed by the client solution after completion of the onboarding process

List of errors

Error	Description
INTERNAL_ERROR	An internal error occurred while processing the session.
MISSING_DOCUMENT_AND_FACE	No selfie and/or ID document images were provided in previous calls. These images are required for the operation to proceed.
SESSION_ALREADY_COMPLETED	The 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 ""

Enrolment

Redirect to Web Enrolment #

iFrame #

crossDevice parameter #

onlyMobile parameter #

Event Listener #

Direct Processing #

Document #

List of errors #

Face #

List of errors #

Complete #

List of errors #

Redirect to Web Enrolment

iFrame

crossDevice parameter

onlyMobile parameter

Event Listener

Direct Processing

Document

List of errors

Face

List of errors

Complete

List of errors