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 |
Portuguese | pt-PT |
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>
‘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 ""