Skip to content

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, 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

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
}