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": "screen-replay_2024-09",
            "calibration": "REGULAR"
        },
        {
            "pipeline_name": "printed-copy_2024-09"
        },
        {
            "pipeline_name": "portrait-substitution_2024-09"
        }
    ],
    "errors_to_ignore": ["DOCUMENT_CROPPED"]
}

image - input image to check liveness from, required
pipelines - the pipelines that should be used to check the liveness, required
pipeline_name - the pipeline name, required
calibration - calibration to be used for checking liveness (REGULAR, SOFT or HARD), optional (REGULAR by default)
errors_to_ignore - defines which validation errors should be ignored during the liveness check (DOCUMENT_CROPPED or DOCUMENT_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

PythonJavaScriptBash

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": "portrait-substitution_2024-09"},
        ],
    },
)

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": "portrait-substitution_2024-09"
            }
        ]
    };

    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": "portrait-substitution_2024-09"}
               ]
          }') | \
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": "portrait-substitution_2024-09",
            "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

PythonJavaScriptBash

data = open('/data/image0.png', 'rb').read()
post_res = requests.post(
    url='<URL>/check_liveness_file?pipelines=default-sr,default-pc,portrait-substitution_2024-09&calibrations=REGULAR,REGULAR,REGULAR',
    files={'file': data}
)

const url = '<URL>/check_liveness_file?pipelines=default-sr,default-pc,portrait-substitution_2024-09&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,portrait-substitution_2024-09&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": "portrait-substitution_2024-09",
            "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": "screen-replay_2024-09",
          "expirationDate": "2025-11-24"
      },
      {
          "attackType": "PRINTED_COPY",
          "pipelineName": "printed-copy_2024-09",
          "expirationDate": "2025-11-24"
      },
      {
          "attackType": "PRINTED_COPY",
          "pipelineName": "printed-copy_2024-01",
          "expirationDate": "2025-11-24"
      },
      {
          "attackType": "PORTRAIT_SUBSTITUTION",
          "pipelineName": "portrait-substitution_2024-09",
          "expirationDate": "2025-11-24"
      },
      {
          "attackType": "DIGITAL_MANIPULATION",
          "pipelineName": "digital-manipulation_2024-11",
          "expirationDate": "2025-11-24"
      },
      {
          "attackType": "DIGITAL_MANIPULATION",
          "pipelineName": "digital-manipulation_2022-11",
          "expirationDate": "2025-11-24"
      }
]

`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": "3.0.0",
    "availablePipelines": [
        "screen-replay_2024-09",
        "default-sr"
    ],
    "pipelineAliases": {
        "default-sr": "screen-replay_2024-09",
    },
    "expirationDates": {
        "screen-replay_2024-09": "2025-11-24"
    }
}

`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
}

REST API reference

API v2 ¶

POST /check_liveness¶

POST /check_liveness_file¶

GET /license_info¶

GET /api_version¶

GET /bi_report¶

`POST /check_liveness`¶

`POST /check_liveness_file`¶

`GET /license_info`¶

`GET /api_version`¶

`GET /bi_report`¶