REST API reference
ID R&D provides a simple REST API service for testing the technology.
In addition to the present REST API reference, the IDLive Doc Server Docker container exposes the OpenAPI specification at http://<host>:8080/v3/api-docs
. It can be imported in tools like Swagger Editor or Postman. Also the container exposes the Swagger UI at http://<host>:8080/swagger-ui/index.html
.
API v2 ¶
POST /check_liveness
¶
Request parameters
This endpoint expects application/json
request body of the following format:
{
"image": "<base64 encoded image data>",
"pipelines": [
{
"pipeline_name": "vulture-sr",
"calibration": "REGULAR"
},
{
"pipeline_name": "woodpecker-pc"
},
{
"pipeline_name": "xenops-ps"
}
],
"errors_to_ignore": ["DOCUMENT_CROPPED"]
}
image
- input image to check liveness from, requiredpipelines
- the pipelines that should be used to check the liveness, requiredpipeline_name
- the pipeline name, requiredcalibration
- calibration to be used for checking liveness (REGULAR
,SOFT
orHARD
), optional (REGULAR
by default)
errors_to_ignore
- defines which validation errors should be ignored during the liveness check (DOCUMENT_CROPPED
orDOCUMENT_IS_COLORLESS
), optional (empty by default)
Note
Default equivalent names (default-sr
, default-pc
, default-ps
) can be used instead of the actual pipeline name. See usage example below.
Note
The following validation errors can not be ignored: DOCUMENT_NOT_FOUND
, DOCUMENT_PHOTO_NOT_FOUND
Response
HTTP 200/OK
API function ‘OK’ response data is always in JSON format.
Usage example
import base64
data = open("/data/image0.png", "rb").read()
post_res = requests.post(
url="<URL>/check_liveness",
json={
"image": base64.b64encode(data).decode("utf-8"),
"pipelines": [
{"pipeline_name": "default-sr", "calibration": "REGULAR"},
{"pipeline_name": "default-pc"},
{"pipeline_name": "xenops-ps"},
],
},
)
const url = '<URL>/check_liveness';
function checkLiveness(image_buffer) {
const data = {
"image": btoa(image_buffer),
"pipelines": [
{
"pipeline_name": "default-sr",
"calibration": "REGULAR"
},
{
"pipeline_name": "default-pc"
},
{
"pipeline_name": "xenops-ps"
}
]
};
const req = new XMLHttpRequest();
req.open('POST', url, true);
req.setRequestHeader("Content-Type", "application/json;charset=UTF-8");
req.onreadystatechange = function () {
if (this.readyState == 4 && this.status == 200) {
alert(this.responseText);
}
};
req.send(JSON.stringify(data));
}
(echo -n '{
"image": "'; base64 image0.png; echo '",
"pipelines": [
{"pipeline_name": "default-sr", "calibration": "REGULAR"},
{"pipeline_name": "default-pc"},
{"pipeline_name": "xenops-ps"}
]
}') | \
curl -H "Content-Type: application/json" \
-X POST -d @- "<URL>/check_liveness"
Response body examples
{
"aggregate_liveness_probability": 1.0,
"aggregate_image_quality_warnings": [],
"pipeline_results": [
{
"pipeline_name": "default-sr",
"calibration": "REGULAR",
"result" : {
"liveness_probability": 1.0,
"liveness_score": 1.0,
"image_quality_warnings": [],
"status_code": "OK"
}
},
{
"pipeline_name": "default-pc",
"calibration": "REGULAR",
"result" : {
"liveness_probability": 1.0,
"liveness_score": 1.0,
"image_quality_warnings": [],
"status_code": "OK"
}
},
{
"pipeline_name": "xenops-ps",
"calibration": "REGULAR",
"result" : {
"status_code": "DOCUMENT_PHOTO_NOT_FOUND"
}
}
]
}
Interpretation of result
Field | Description |
---|---|
status_code | Image validation status code (image validation is performed beforehand each liveness check) |
liveness_score | Raw liveness checking score, can be used for calibration |
liveness_probability | Document liveness probability from 0 to 1 |
image_quality_warnings | Image quality warnings |
aggregate_liveness_probability | Aggregate document liveness probability from 0 to 1 |
aggregate_image_quality_warnings | Aggregate image quality warnings |
Note
In case if any liveness check result's from the pipeline_results
status code is not OK
, the aggregate_liveness_probability
, and aggregate_image_quality_warnings
fields are not present since in that case it's impossible to aggregate liveness check results
Aggregate liveness probability is the main response of the system, and it should always be used to make a liveness check decision. The image is accepted as "live" when probability is greater than 0.5. Probability value range is [0; 1].
Raw liveness score can be used for BPCER / APCER tuning and is provided mostly for calibration purposes. The range of score value is unbound.
We highly advise you to analyze the image quality warnings and reject inappropriate images.
POST /check_liveness_file
¶
Query parameters
Parameter | Type | Description | Required |
---|---|---|---|
pipelines | String[] | Liveness pipelines to be used for checking liveness | True |
calibrations | String[] | Calibrations to be used for checking liveness ("REGULAR", "SOFT" or "HARD") | False |
errors_to_ignore | String[] | Defines which validation errors should be ignored during the liveness check ("DOCUMENT_CROPPED" or "DOCUMENT_IS_COLORLESS") | False |
Note
The following validation errors can not be ignored: DOCUMENT_NOT_FOUND
, DOCUMENT_PHOTO_NOT_FOUND
Request parameters
Parameter | Type | Description | Required |
---|---|---|---|
file | File | The binary image data uploaded as a file | True |
This is a convenience endpoint duplicating the /check_liveness
one's functionality, but supporting file uploads instead of base64-encoded data. It's mostly intended for quick tests and evaluations conducted using software which doesn't operate well with base64-encoded data, e.g. Postman.
You can specify only pipelines from the list of pipelines of the IDLIVEDOC_SERVER_AVAILABLE_PIPELINES environment variable.
The number of calibrations provided should either be zero or match the number of pipeline names provided.
Response
HTTP 200/OK
API function ‘OK’ response data is always in JSON format.
Usage example
data = open('/data/image0.png', 'rb').read()
post_res = requests.post(
url='<URL>/check_liveness_file?pipelines=default-sr,default-pc,xenops-ps&calibrations=REGULAR,REGULAR,REGULAR',
files={'file': data}
)
const url = '<URL>/check_liveness_file?pipelines=default-sr,default-pc,xenops-ps&calibrations=REGULAR,REGULAR,REGULAR';
function checkLiveness(file) {
const data = new FormData();
data.append('file', file);
const req = new XMLHttpRequest();
req.open('POST', url, true);
req.onreadystatechange = function () {
if (this.readyState == 4 && this.status == 200) {
alert(this.responseText);
}
};
req.send(data);
}
curl -F file=@/data/image0.png -X POST "<URL>/check_liveness_file?pipelines=default-sr,default-pc,xenops-ps&calibrations=REGULAR,REGULAR,REGULAR"
Response body examples
{
"aggregate_liveness_probability": 1.0,
"aggregate_image_quality_warnings": [],
"pipeline_results": [
{
"pipeline_name": "default-sr",
"calibration": "REGULAR",
"result" : {
"liveness_probability": 1.0,
"liveness_score": 1.0,
"image_quality_warnings": [],
"status_code": "OK"
}
},
{
"pipeline_name": "default-pc",
"calibration": "REGULAR",
"result" : {
"liveness_probability": 1.0,
"liveness_score": 1.0,
"image_quality_warnings": [],
"status_code": "OK"
}
},
{
"pipeline_name": "xenops-ps",
"calibration": "REGULAR",
"result" : {
"status_code": "DOCUMENT_PHOTO_NOT_FOUND"
}
}
]
}
Interpretation of result
Field | Description |
---|---|
status_code | Image validation status code (image validation is performed beforehand each liveness check) |
liveness_score | Raw liveness checking score, can be used for calibration |
liveness_probability | Document liveness probability from 0 to 1 |
image_quality_warnings | Image quality warnings |
aggregate_liveness_probability | Aggregate document liveness probability from 0 to 1 |
aggregate_image_quality_warnings | Aggregate image quality warnings |
Note
In case if any liveness check result's from the pipeline_results
status code is not OK
, the aggregate_liveness_probability
, and aggregate_image_quality_warnings
fields are not present since in that case it's impossible to aggregate liveness check results
Aggregate liveness probability is the main response of the system, and it should always be used to make a liveness check decision. The image is accepted as "live" when probability is greater than 0.5. Probability value range is [0; 1].
Raw liveness score can be used for BPCER / APCER tuning and is provided mostly for calibration purposes. The range of score value is unbound.
We highly advise you to analyze the image quality warnings and reject inappropriate images.
GET /license_info
¶
Response
HTTP 200/OK
API function ‘OK’ response data is always in JSON format. API returns list of features allowed by the present license along with their expiration dates.
Response body examples
[
{
"attackType": "SCREEN_REPLAY",
"pipelineName": "vulture-sr",
"expirationDate": "2025-05-22"
},
{
"attackType": "PRINTED_COPY",
"pipelineName": "woodpecker-pc",
"expirationDate": "2025-05-22"
},
{
"attackType": "PRINTED_COPY",
"pipelineName": "robin-pc",
"expirationDate": "2025-05-22"
},
{
"attackType": "PORTRAIT_SUBSTITUTION",
"pipelineName": "xenops-ps",
"expirationDate": "2025-05-22"
},
{
"attackType": "DIGITAL_MANIPULATIONS",
"pipelineName": "hawk-sd",
"expirationDate": "2025-05-22"
}
]
GET /api_version
¶
Response
HTTP 200/OK
API function ‘OK’ response data is always in JSON format. API returns actual server name, version, license expiration date and the value of the IDLIVEDOC_SERVER_AVAILABLE_PIPELINES environment variable.
Response body examples
{
"product": "IDLive Doc Server",
"version": "2.4.1",
"availablePipelines": [
"vulture-sr",
"default-sr"
],
"pipelineAliases": {
"default-sr": "vulture-sr",
},
"expirationDates": {
"vulture-sr": "2025-05-22"
}
}
GET /bi_report
¶
Query parameters
Parameter | Type | Description | Required |
---|---|---|---|
date_from | Date | The date from which it needs to calculate metrics. Date format: yyyy-MM-dd | True |
date_to | Date | The date to which it needs to calculate metrics. Date format: yyyy-MM-dd | True |
The method accepts two dates date_from and date_to forming a date range for which it needs to calculate metrics. Both dates are inclusive.
Response
HTTP 200/OK
API function ‘OK’ response data is always in JSON format. API returns basic system performance metrics.
Response body examples
{
"total": 12,
"auk_UNKNOWN_DOCUMENT_NOT_FOUND": 7,
"auk_UNKNOWN_probability_0.9-1.0": 5
}