Flow Remote
Description#
Flow Remote - is a way to connect the biometric service using our frontend client.
Using this integration method involves receiving a session on the created Flow and then redirecting the end user to our client.
All the stages of connection are described in more detail below. You can also download the full example.
Stages:#
1. Flow creation#
The first thing you need to do is to create Flow in your personal cabinet. To do this, follow this link.
After the flow has been created you need to use its
API KEY in the second step. You can find API KEY on the page with the
list of created flows..
Simplified example of the personal cabinet flows table
| 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:
Also, you must specify the biometric method as the URL path.
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:
3.3. Additional Metadata#
Additional metadata extends the system's basic functionality, providing access to additional capabilities when working with the session.
The following additional functionality is currently available:
- Signed report generation: When the client's IIN is passed in metadata, it becomes possible to obtain via API signed reports about the results of:
- Liveness verification (Liveness)
- Face comparison (Face2Face)
Note
Obtaining reports requires calling specific API methods. Passing IIN in session metadata is a prerequisite for further work with these methods.
API KEY and metadata must be passed in the request body:
| Field name | Type | Required | Description |
|---|---|---|---|
| extra | No | Additional metadata | |
| iin | String | No | IIN (Individual Identification Number) of client |
Request examples:
import requests
import json
url = "https://kyc.biometric.kz/api/v1/flows/session/create/"
payload = json.dumps({
"api_key": "YOUR_FLOW_API_KEY",
"metadata": {
"extra": {
"iin": "<iin>"
}
}
})
headers = {
'Content-Type': 'application/json',
}
response = requests.post(url=url, headers=headers, data=payload)
print(response.json())
const apiKey = 'YOUR_FLOW_API_KEY';
const payload = {
api_key: apiKey,
metadata: {
extra: {
iin: '<iin>'
}
}
};
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 => console.log(data))
.catch(error => console.error(error));
The response will be a JSON with the following fields:
- session_id - one-time session identifier to pass the flow;
- technologies - ordered set of flow technologies.
Response example:
4. End user redirection#
As a result of the previous steps, we should get a session identifier - session_id.
Now it is necessary to redirect the end user to our frontend-client.
To do this we need to form the following URL:
https://remote.biometric.kz/flow/<session_id>
You can also declare the following address bar parameters:
- redirect - address to which the redirect will occur after the technology passes;
- locale - default language.
['ru', 'en'].
Example:
Next, the end user will go to the tab with biometric verification. According to the example, the following technologies will run sequentially:
| Technology code | Description |
|---|---|
| LD | Determining a person's liveliness by their face |
| F2F | Determining the similarity of two faces from a photo |
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"
...
6. Getting liveness video#
To get the liveness video of the sessions you can send a GET request to a special URL,
passing the session identifier and flow API KEY in request params:
Request URL:
https://kyc.biometric.kz/api/v1/liveness/video/download/
| Request format | Request method |
|---|---|
| JSON | GET |
session_id and flow API KEY must be passed in the parameters of the request:
| Parameter | Type | Obligatorily | Description |
|---|---|---|---|
| session_id | String | Yes | Session flow ID |
| flow_api_key | String | Yes | API KEY of the created flow in the personal cabinet |
Request examples:
7. Getting PDF Report#
To obtain a signed PDF report on technology completion, you can send a POST request to a special URL by passing the session identifier and technology type in the request parameters.
Important
For successful report generation, you must first pass the client's IIN in additional metadata when creating a session (see section 3.3. Additional Metadata).
Request URL:
https://kyc.biometric.kz/api/v1/flows/session/{session_id}/report/
| Request format | Request method |
|---|---|
| JSON | POST |
Request parameters:
Request body (JSON):
| Field name | Type | Required | Description |
|---|---|---|---|
| api_key | String | Yes | API KEY of the created flow in personal cabinet |
Path parameters:
| Field name | Type | Required | Description |
|---|---|---|---|
| session_id | String | Yes | Session identifier in UUID4 format |
Query parameters:
| Field name | Type | Required | Description |
|---|---|---|---|
| technology | String | Yes | Technology type. Available values: LDHP, LDD2, LDD, LDPM, F2F |
Request examples:
import requests
import json
url = f"https://kyc.biometric.kz/api/v1/flows/session/<session_id>/report/"
params = {
"technology": "F2F" # Or other technology type
}
payload = json.dumps({
"api_key": "<YOUR_FLOW_API_KEY>"
})
headers = {
'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, params=params, data=payload)
print(response.json())
const sessionId = '<session_id>';
const apiKey = '<YOUR_FLOW_API_KEY>';
fetch(`https://kyc.biometric.kz/api/v1/flows/session/${sessionId}/report/?technology=F2F`, {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
api_key: apiKey
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));
The response will be a JSON with the following fields:
- pdf - PDF document in base64 format
Response example:
Full example#
You can download a ready example on how to run Flow remote here.