Flow Widget
Description#
The Flow Widget is a way to integrate a biometrics service into a client-side web application using an off-the-shelf solution in the form of a JavaScript library.
Using this integration method involves receiving a session on the created flow and then redirecting the end user to our server.
Below is a more detailed description of all the steps of the connection. You can also download the full example .
Note
The current version of the documentation covers plugging a widget into a HTML page.
Stages:#
1. Creating a Flow#
The first thing you need to do is to create a Flow in your personal account. To do this, go to this link.
Once the flow has been created it is necessary to use its API KEY in the second step. You can find the API KEY on the list of created flows page .
Simplified example of the table of personal account flows:
| Flow name | API KEY | Technologies |
|---|---|---|
| Flow for everyone | TTpme201NiUMBA... | LD, F2F |
| Flow for individuals | Efy202XKbVAWRu... | LD, ED, F2F |
| Flow for legal entities | UuuH4V1XC-M9je... | LD, DR, F2F |
Note
The following examples will use the first flow from the table above: "Flow for everyone".
Also, a shortened API KEY length is used for clarity.
Its actual length is 47 characters or more.
2. Session Creation#
To work with the service you need to create a session.
To do this, you need to send a POST-request to create a session, using the
API KEY of the created flow. Read more about sessions here.
Requests to our service use only data in JSON format. Response data from the service will be presented in the same format.
Request URL:
https://kyc.biometric.kz/api/v1/flows/session/create/
| Request format | Request method |
|---|---|
| JSON | POST |
API KEY must be passed in the request body:
| Field name | Type | Obligatorily | Description |
|---|---|---|---|
| api_key | String | Yes | API KEY of the created flow in the personal cabinet |
Request examples:
const apiKey: string = 'YOUR_FLOW_API_KEY' // flow api key
interface SessionResponseData {
session_id: string,
technologies: string[]
}
fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
method: 'POST',
body: JSON.stringify({
api_key: apiKey
})
})
.then(response => response.json())
.then(data => {
const { session_id, technologies }: SessionResponseData = data
})
The response will be JSON with the following fields:
- session_id - one-time session identifier to pass the flow;
- technologies - an ordered set of flow technologies.
Response example:
3. Session Metadata#
When creating a flow, certain metadata can be included to facilitate a more flexible and dynamic process, as well as to simplify the verification procedure.
API KEY and metadata must be sent in the request body. The value for metadata is an object that includes an object with the technology name (face2face, edocument) consisting of metadata for the technology.
| Field Name | Type | Required | Description |
|---|---|---|---|
| api_key | String | Yes | The API KEY of the created flow in the personal cabinet |
| metadata | No | Session metadata |
Metadata for Face2Face technology:
| Field Name | Type | Required | Description |
|---|---|---|---|
| face2face | No | Metadata for Face2Face technology | |
| photo1 | String | No | Photo used for matching in base64 format |
Metadata for E-Document technology:
| Field Name | Type | Required | Description |
|---|---|---|---|
| edocument | No | Metadata for E-Document technology | |
| iin | No | IIN field | |
| phone | No | Subject's phone number field, format: 77********* |
|
| value | String | No | Field values |
| changeable | Boolean | No | Ability for the user to change the data |
| skip_input | Boolean | No | Skip user data input (Move to OTP code input step) |
General metadata:
| Field Name | Type | Required | Description |
|---|---|---|---|
| general | No | General metadata | |
| interchangeable_tech | Array | No | List of interchangeable technologies |
Note
If metadata is absent, the flow will proceed by default.
3.1. Metadata for Face2Face#
If a user's face photo is available, it can be included in the session metadata. This helps simplify and shorten the verification process and prevent errors that might occur during user verification. The metadata field must be sent in the request body.
Important to Note
Face2Face technology metadata will only work for the following flows:
- Liveness + Face2Face
- E-Document + Face2Face
- Document Recognition + Face2Face
| Field Name | Type | Required | Description |
|---|---|---|---|
| face2face | No | Metadata for Face2Face technology | |
| photo1 | String | No | Photo used for matching in base64 format |
Request URL:
https://kyc.biometric.kz/api/v1/flows/session/create/
| Request Format | Request Method |
|---|---|
| JSON | POST |
Request Examples:
import requests
import json
import base64
url = "https://kyc.biometric.kz/api/v1/flows/session/create/"
with open('path/to/your/image.jpg', 'rb') as image_file:
encoded_image = base64.b64encode(image_file.read()).decode('utf-8')
payload = json.dumps({
"api_key": "YOUR_FLOW_API_KEY",
"metadata": {
"face2face": {
"photo1": encoded_image,
},
},
})
headers = {
'Content-Type': 'application/json',
}
response = requests.post(url=url, headers=headers, data=payload)
print(response.json())
const apiKey = 'YOUR_FLOW_API_KEY';
const imageFilePath = 'path/to/your/image.jpg'; // Path to your image
const fs = require('fs');
const path = require('path');
const imageBase64 = fs.readFileSync(path.resolve(imageFilePath), { encoding: 'base64' });
const payload = {
api_key: apiKey,
metadata: {
face2face: {
photo1: imageBase64
}
}
};
fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => {
const { session_id, technologies } = data;
})
The response will be a JSON with the following fields:
- session_id - a one-time session identifier for passing the flow;
- technologies - an ordered set of flow technologies.
Example response:
3.2. Metadata for E-Document#
If user data such as IIN, phone number, or presence in the Mobile Citizen Database is available, it can be sent to the input form when passing the EDocument technology. This helps simplify and shorten the verification process and prevent errors that might occur during user data entry. The metadata field must be sent in the request body.
Note
The skip_input field defaults to false (the data entry step is not skipped).
The changeable field defaults to true (the user can change the data entry field values).
| Field Name | Type | Required | Description |
|---|---|---|---|
| edocument | No | Metadata for E-Document technology | |
| iin | No | IIN field | |
| phone | No | Subject's phone number field, format: 77********* |
|
| value | String | No | Field values |
| changeable | Boolean | No | Ability for the user to change the data |
| skip_input | Boolean | No | Skip user data input |
Request URL:
https://kyc.biometric.kz/api/v1/flows/session/create/
| Request Format | Request Method |
|---|---|
| JSON | POST |
Case №1:
Note
Skipping the user data entry step is only possible if:
1) value for iin and phone is provided
2) changeable for iin and phone is provided with a value of false
3) skip_input is provided with a value of true
The user data entry step will be skipped. The user will be redirected to the OTP code input step from 1414.
curl --location --request POST 'https://kyc.biometric.kz/api/v1/flows/session/create/' \
--header 'Content-Type: application/json' \
--data-raw '{
"api_key": "YOUR_FLOW_API_KEY",
"metadata": {
"edocument": {
"iin": {
"value": "<subjects_iin>",
"changeable": false,
},
"phone": {
"value": "<subjects_phone>",
"changeable": false,
},
"skip_input": true
}
}
}'
import requests
import json
url = "https://kyc.biometric.kz/api/v1/flows/session/create/"
payload = json.dumps({
"api_key": "YOUR_FLOW_API_KEY",
"metadata": {
"edocument": {
"iin": {
"value": "<subjects_iin>",
"changeable": False,
},
"phone": {
"value": "<subjects_phone>",
"changeable": False,
},
"skip_input": True
},
})
headers = {
'Content-Type': 'application/json',
}
response = requests.post(url=url, headers=headers, data=payload)
print(response.json())
```js const apiKey = 'YOUR_FLOW
_API_KEY'; // Your flow API key const subjectsIIN = '123456789012'; // Example user's IIN const subjectsPhone = '77***'; // Example user's phone number
fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
api_key: apiKey,
metadata: {
edocument: {
iin: {
value: subjectsIIN,
changeable: false,
},
phone: {
value: subjectsPhone,
changeable: false,
},
skip_input: true
}
}
})
})
.then(response => response.json())
.then(data => {
const { session_id, technologies } = data;
})
```
Case №2:
At the data entry step, the user will see the values passed in the metadata fields, without the ability to change the IIN.
Note
The default value for changeable is true.
The default value for skip_input is false.
curl --location --request POST 'https://kyc.biometric.kz/api/v1/flows/session/create/' \
--header 'Content-Type: application/json' \
--data-raw '{
"api_key": "YOUR_FLOW_API_KEY",
"metadata": {
"edocument": {
"iin": {
"value": "<subjects_iin>",
"changeable": false,
},
"phone": {
"value": "<subjects_phone>",
}
}
}
}'
import requests
import json
url = "https://kyc.biometric.kz/api/v1/flows/session/create/"
payload = json.dumps({
"api_key": "YOUR_FLOW_API_KEY",
"metadata": {
"edocument": {
"iin": {
"value": "<subjects_iin>",
"changeable": False,
},
"phone": {
"value": "<subjects_phone>",
},
},
})
headers = {
'Content-Type': 'application/json',
}
response = requests.post(url=url, headers=headers, data=payload)
print(response.json())
const apiKey = 'YOUR_FLOW_API_KEY'; // Your flow API key
const subjectsIIN = '123456789012'; // Example user's IIN
const subjectsPhone = '77*********'; // Example user's phone number
fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
api_key: apiKey,
metadata: {
edocument: {
iin: {
value: subjectsIIN,
changeable: false,
},
phone: {
value: subjectsPhone,
}
}
}
})
})
.then(response => response.json())
.then(data => {
const { session_id, technologies } = data;
})
Case №3:
At the data entry step, the user will see the values passed in the metadata fields, with the ability to change the IIN and phone number.
import requests
import json
url = "https://kyc.biometric.kz/api/v1/flows/session/create/"
payload = json.dumps({
"api_key": "YOUR_FLOW_API_KEY",
"metadata": {
"edocument": {
"iin": {
"value": "<subjects_iin>",
},
"phone": {
"value": "<subjects_phone>",
},
},
})
headers = {
'Content-Type': 'application/json',
}
response = requests.post(url=url, headers=headers, data=payload)
print(response.json())
const apiKey = 'YOUR_FLOW_API_KEY'; // Your flow API key
const subjectsIIN = '123456789012'; // Example user's IIN
const subjectsPhone = '77*********'; // Example user's phone number
fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
api_key: apiKey,
metadata: {
edocument: {
iin: {
value: subjectsIIN,
},
phone: {
value: subjectsPhone,
}
}
}
})
})
.then(response => response.json())
.then(data => {
const { session_id, technologies } = data;
})
The response will be a JSON with the following fields:
- session_id - a one-time session identifier for passing the flow;
- technologies - an ordered set of flow technologies.
Example response:
4. Widget integration into a web application#
After successfully creating flow and generating session_id, you need to integrate the finished widget into the client side web application. Widget integration consists of the following steps:
4.1 Creating a container for a widget in a web application#
It is necessary to create a container inside which the generated HTML widget structure will be embedded. The container must have an id attribute with a unique value.
Styles that are based on the height and width of the container will be used inside the application. To display it correctly, create an additional container in which the application itself will be placed.
Important information
For the parent container, you must specify the width and height (not max-width/max-height, namely height and width). For the container of the application itself, it is worth setting height and width styles of 100%, as well as relative positioning (see the example below)
Example:
.flow-widget-container {
width: 400px;
height: 600px;
}
#flow-widget {
width: 100%;
height: 100%;
position: relative;
}
4.2 Widget loading in a web application#
To load a JavaScript file into a web application, you must add a HTML script tag.
The script tag must contain a type attribute with a module value and a src attribute, which will contain the URL from which the JavaScript file will be loaded.
Currently, the file should be uploaded via the following URL https://remote.biometric.kz/widget/flow-widget.js
Example:
4.3 Starting the verification process in a web application#
If you need to start the verification process, you must call the startSession method from the FlowWidget library.
Since the current example considers plugging into a HTML page, another HTML tag script will need to be added to start the verification process, specifying the type attribute with a value of module.
The startSession method accepts a configuration object that has the following mandatory fields:
| Field name | Type | Description |
|---|---|---|
| session_id | string | Unique session identifier received from the server |
| selector | string | Identifier of HTML container in which the widget will be generated |
| locale | string | Language in which the widget should run, currently implemented languages: ru, en, kz |
Example:
<script type="module">
FlowWidget.startSession({
id: '<session_id>',
selector: '#flow-widget',
locale: 'ru'
})
</script>
4.4 Catching widget termination#
At the end of its work the widget triggers an event called finish, in which the data collected by the forntend part of this widget through the detail field of the data object will also be transferred. To catch this event you should add the following code:
<script type="module">
window.addEventListener('finish', (data) => {
console.dir(data.detail)
})
</script>
4.5 Getting the result#
To get the overall result of the sessions you can send a GET request to a special URL, passing the session identifier in the parameters:
Request URL::
https://kyc.biometric.kz/api/v1/flows/session/result/
| Request format | Request method |
|---|---|
| JSON | GET |
session_id must be passed in the request parameters:
| Parameter | Type | Obligatorily | Description |
|---|---|---|---|
| session_id | String | Yes | flow session identifier |
| flow_api_key | String | Yes | API KEY of the created flow in the personal cabinet that was used when creating the session |
Request examples:
The response will be JSON with the following fields:
- id - session identifier;
- technologies - an ordered set of technologies according to the created flow;
- liveness_result - Liveness passing result;
- document_recognition_result - Document Recognition passing result;
- face2face_result - Face2face passing result.
- edocument_result - Edocument passing result
Important information
The fields liveness_result, document_recognition_result, face2face_result, edocument_result
are displayed only if the client passed these technologies during Flow.
Response example:
{
"id": "session_id",
"technologies": [
{
"name": "Document Recognition",
"description": "Parse document data from image"
}
],
"document_recognition_result": {
"first_name": "First",
"last_name": "Last",
"patronymic": "Patronymic",
"personal_number": "pers_number",
"date_of_birth": "01.01.2000",
"document_number": "doc_number",
"authority": "authority"
...
Final connection example#
<div id="flow-widget"></div>
<script type="module" src="https://remote.biometric.kz/widget/flow-widget.umd.js"></script>
<script type="module">
FlowWidget.startSession({
id: '2569aadc-9ff2-4da3-a1c8-44057520e1d6',
selector: '#flow-widget',
locale: 'ru'
})
window.addEventListener('finish', (data) => {
console.dir(data.detail)
})
</script>