Persons Backend API#

Description#

Persons Backend API is a REST API for programmatic management of persons (user profiles) in the system. The API allows creating, updating persons, and managing their aliases and photos through external systems.

For convenient integration through Backend API, use Swagger (OpenAPI)

Terms#

Person - a profile of an individual in the system containing their identification data, photos, and verification history.
Alias - a person identifier (phone, IIN, document number, custom ID) used for search and duplicate prevention.
Verification - person's identity confirmation status (is_verified).
API KEY - key for organization authentication when accessing the API.
Base64 - method of encoding binary data (images) into text format for transmission through JSON.

Steps:#

1. Obtaining Organization API-KEY#

The first step to use the API is obtaining the organization's API-KEY. To get the organization's API-KEY, you need to log into the Personal Cabinet via this link. The API-KEY is located in the Backend Api Key field.

backend_api_key

Organization API-KEY example:

API-KEY: Efy202XKbVAWRu...

Note

For clarity, a shortened length of API KEY is used. Its actual length is 47 or more characters.

2. Creating a Person#

Important

To use this API, you must have an active subscription to the "Persons" technology. You can read more about subscriptions here.

When creating a person, data in JSON format is used. Photo and organization API key are mandatory.

Request URL:

https://kyc.biometric.kz/api/v1/backend/persons/

Request Format	Request Method
JSON	POST

Field Name	Type	Required	Description
api_key	String	Yes	Organization API KEY in personal cabinet
image_b64	String	Yes	Person image in Base64 format
photo_type	String	Yes	Photo type: `digital`, `scan`, `live`, `other`
is_verified	Boolean	Yes	Person verification status
aliases	Array	No	Array of person aliases

Alias structure:

Field Name	Type	Required	Description
value	String	Yes	Alias value (phone number, IIN, document number, etc.)
type	String	Yes	Alias type: `phone`, `personal_number`, `document_number`, `custom`

Request examples:

cURLPythonJavaScript

curl -X 'POST' \
'https://kyc.biometric.kz/api/v1/backend/persons/' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "api_key": "<organization_api_key>",
  "image_b64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
  "photo_type": "other",
  "is_verified": true,
  "aliases": [
    {
      "value": "+77071234567",
      "type": "phone"
    },
    {
      "value": "123456789012",
      "type": "personal_number"
    }
  ]
}'

import requests
import base64

# Encode image to base64
with open('photo.jpg', 'rb') as image_file:
    encoded_image = base64.b64encode(image_file.read()).decode('utf-8')
    image_b64 = f"data:image/jpeg;base64,{encoded_image}"

url = 'https://kyc.biometric.kz/api/v1/backend/persons/'

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}

data = {
    'api_key': '<organization_api_key>',
    'image_b64': image_b64,
    'photo_type': 'other',
    'is_verified': True,
    'aliases': [
        {
            'value': '+77071234567',
            'type': 'phone'
        },
        {
            'value': '123456789012',
            'type': 'personal_number'
        }
    ]
}

response = requests.post(url, headers=headers, json=data)

print(response.json())

const url = 'https://kyc.biometric.kz/api/v1/backend/persons/';

// Function to encode file to base64
function fileToBase64(file) {
    return new Promise((resolve, reject) => {
        const reader = new FileReader();
        reader.readAsDataURL(file);
        reader.onload = () => resolve(reader.result);
        reader.onerror = error => reject(error);
    });
}

const headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
};

const data = {
    api_key: '<organization_api_key>',
    image_b64: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...',
    photo_type: 'other',
    is_verified: true,
    aliases: [
        {
            value: '+77071234567',
            type: 'phone'
        },
        {
            value: '123456789012',
            type: 'personal_number'
        }
    ]
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));

Response example:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440001",
  "is_verified": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "aliases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "value": "550e8400-e29b-41d4-a716-446655440000",
      "type": "system_id"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "value": "+77071234567",
      "type": "phone"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440004",
      "value": "123456789012",
      "type": "personal_number"
    }
  ],
  "photos": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440005",
      "type": "other",
      "is_default": true,
      "is_uploaded": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

3. Updating a Person#

Allows changing the verification status of an existing person.

Request URL:

https://kyc.biometric.kz/api/v1/backend/persons/{person_id}/update

Request Format	Request Method
JSON	POST

Field Name	Type	Required	Description
api_key	String	Yes	Organization API KEY in personal cabinet
is_verified	Boolean	Yes	New verification status of the person

Request examples:

cURLPythonJavaScript

curl -X 'POST' \
'https://kyc.biometric.kz/api/v1/backend/persons/550e8400-e29b-41d4-a716-446655440000/update' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "api_key": "<organization_api_key>",
  "is_verified": false
}'

import requests

person_id = '550e8400-e29b-41d4-a716-446655440000'
url = f'https://kyc.biometric.kz/api/v1/backend/persons/{person_id}/update'

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}

data = {
    'api_key': '<organization_api_key>',
    'is_verified': False
}

response = requests.post(url, headers=headers, json=data)

print(response.json())

const personId = '550e8400-e29b-41d4-a716-446655440000';
const url = `https://kyc.biometric.kz/api/v1/backend/persons/${personId}/update`;

const headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
};

const data = {
    api_key: '<organization_api_key>',
    is_verified: false
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));

4. Adding a Photo to Person#

Allows adding an additional photo to an existing person.

Request URL:

https://kyc.biometric.kz/api/v1/backend/persons/{person_id}/photo/

Request Format	Request Method
JSON	POST

Field Name	Type	Required	Description
api_key	String	Yes	Organization API KEY in personal cabinet
image_b64	String	Yes	Image in Base64 format
photo_type	String	Yes	Photo type: `digital`, `scan`, `live`, `other`
is_default	Boolean	Yes	Make this photo the default for the person

Request examples:

cURLPythonJavaScript

curl -X 'POST' \
'https://kyc.biometric.kz/api/v1/backend/persons/550e8400-e29b-41d4-a716-446655440000/photo/' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "api_key": "<organization_api_key>",
  "image_b64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
  "photo_type": "digital",
  "is_default": true
}'

import requests
import base64

# Encode image to base64
with open('new_photo.jpg', 'rb') as image_file:
    encoded_image = base64.b64encode(image_file.read()).decode('utf-8')
    image_b64 = f"data:image/jpeg;base64,{encoded_image}"

person_id = '550e8400-e29b-41d4-a716-446655440000'
url = f'https://kyc.biometric.kz/api/v1/backend/persons/{person_id}/photo/'

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}

data = {
    'api_key': '<organization_api_key>',
    'image_b64': image_b64,
    'photo_type': 'digital',
    'is_default': True
}

response = requests.post(url, headers=headers, json=data)

print(response.json())

const personId = '550e8400-e29b-41d4-a716-446655440000';
const url = `https://kyc.biometric.kz/api/v1/backend/persons/${personId}/photo/`;

const headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
};

const data = {
    api_key: '<organization_api_key>',
    image_b64: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...',
    photo_type: 'digital',
    is_default: true
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));

5. Adding an Alias to Person#

Allows adding a new identifier (alias) to an existing person.

Request URL:

https://kyc.biometric.kz/api/v1/backend/persons/{person_id}/alias/

Request Format	Request Method
JSON	POST

Field Name	Type	Required	Description
api_key	String	Yes	Organization API KEY in personal cabinet
value	String	Yes	Alias value (phone number, IIN, document number, etc.)
type	String	Yes	Alias type: `phone`, `personal_number`, `document_number`, `custom`

Important to consider

Cannot create aliases of type system_id - they are created automatically
Alias values must be unique within the organization
Attempting to add an existing alias will return an error with conflict details

Request examples:

cURLPythonJavaScript

curl -X 'POST' \
'https://kyc.biometric.kz/api/v1/backend/persons/550e8400-e29b-41d4-a716-446655440000/alias/' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "api_key": "<organization_api_key>",
  "value": "AB1234567",
  "type": "document_number"
}'

import requests

person_id = '550e8400-e29b-41d4-a716-446655440000'
url = f'https://kyc.biometric.kz/api/v1/backend/persons/{person_id}/alias/'

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}

data = {
    'api_key': '<organization_api_key>',
    'value': 'AB1234567',
    'type': 'document_number'
}

response = requests.post(url, headers=headers, json=data)

print(response.json())

const personId = '550e8400-e29b-41d4-a716-446655440000';
const url = `https://kyc.biometric.kz/api/v1/backend/persons/${personId}/alias/`;

const headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
};

const data = {
    api_key: '<organization_api_key>',
    value: 'AB1234567',
    type: 'document_number'
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));

Photo Types#

Value	Priority	Description
digital	1	Digital photo from document chip
scan	2	Portrait from scanned document
live	3	Best frame from liveness verification
other	4	Manually uploaded or other photos

Automatic default photo management

When adding a photo with higher priority and is_default: true flag, it automatically becomes the default, and the previous default photo loses this status.

Alias Types#

Value	Description	Features
system_id	Internal person UUID	Created automatically, immutable
phone	Phone number	Format: +77071234567
personal_number	IIN (personal number)	12 digits
document_number	Document number (passport, ID card)	Any format
custom	Custom identifier	Any format

Errors#

Status Code	Response	Description
400	Invalid API key	Invalid or missing organization API key
400	Person not found	Person with specified ID not found or doesn't belong to your organization
400	Invalid image format	Invalid image format or corrupted Base64 data
400	Invalid photo type	Invalid photo type. Allowed values: digital, scan, live, other
400	Invalid alias type	Invalid alias type. Allowed values: phone, personal_number, document_number, custom
400	Cannot create system_id alias	Aliases of type system_id are created automatically and cannot be added manually
400	Alias already exists	Alias with this value already exists in the organization
400	Person limit exceeded	Person limit exceeded for your subscription
400	Cannot delete default photo	Cannot delete the only default photo of a person
400	Client does not have access to Persons technology	Client doesn't have access to "Persons" technology. Reasons: subscription is missing, expired, or technology is not active
400	Subscription has not started	Subscription has not been activated yet
400	No active or future subscription for technology	No active or future subscription for "Persons" technology
400	Client does not have subscription	Client doesn't have a subscription, you can read more about subscriptions here
400	File extension is not allowed	Unsupported file extension. Only allowed: JPEG, JPG, PNG
404	Organization not found	Organization with specified API key not found
422	Validation error	Input data validation error. Check required fields and their formats
500	Internal server error	Internal server error. Contact technical support

Error details

For validation errors (codes 400, 422), the response will contain detailed information about which field contains the error and what needs to be fixed.

Alias error handling

When attempting to add an already existing alias, the response will include a list of all conflicting values and IDs of persons they belong to.