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": "toucan-sr",
            "calibration": "REGULAR"
        },
        {
            "pipeline_name": "robin-pc"
        },
        {
            "pipeline_name": "umbrellabird-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)

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": "umbrellabird-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": "umbrellabird-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": "umbrellabird-ps"}
               ]
          }') | \
curl -H "Content-Type: application/json" \
     -X POST -d @- "<URL>/check_liveness"

Response body examples

{
    "aggregate_liveness_probability": 1.0,
    "aggregate_quality_score": 1.0,
    "aggregate_image_quality_warnings": [],
    "pipeline_results": [
        {
            "pipeline_name": "default-sr",
            "calibration": "REGULAR",
            "result" : {
                "liveness_probability": 1.0,
                "liveness_score": 1.0,
                "quality_score": 0.0,
                "image_quality_warnings": [],
                "status_code": "OK"
            }
        },
        {
            "pipeline_name": "default-pc",
            "calibration": "REGULAR",
            "result" : {
                "liveness_probability": 1.0,
                "liveness_score": 1.0,
                "quality_score": 0.0,
                "image_quality_warnings": [],
                "status_code": "OK"
            }
        },
        {
            "pipeline_name": "umbrellabird-ps",
            "calibration": "REGULAR",
            "result" : {
                "status_code": "DOCUMENT_PHOTO_NOT_FOUND"
            }
        }
    ]
}

Interpretation of result

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.

Quality score is a mark of image "goodness". High values indicate that image is quality enough for liveness checking.

We highly advise you to analyze the image quality warnings and reject inappropriate images.

POST /check_liveness_file¶

Query parameters

Request parameters

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,umbrellabird-ps&calibrations=REGULAR,REGULAR,REGULAR',
    files={'file': data}
)

const url = '<URL>/check_liveness_file?pipelines=default-sr,default-pc,umbrellabird-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,umbrellabird-ps&calibrations=REGULAR,REGULAR,REGULAR"

Response body examples

{
    "aggregate_liveness_probability": 1.0,
    "aggregate_quality_score": 1.0,
    "aggregate_image_quality_warnings": [],
    "pipeline_results": [
        {
            "pipeline_name": "default-sr",
            "calibration": "REGULAR",
            "result" : {
                "liveness_probability": 1.0,
                "liveness_score": 1.0,
                "quality_score": 1.0,
                "image_quality_warnings": [],
                "status_code": "OK"
            }
        },
        {
            "pipeline_name": "default-pc",
            "calibration": "REGULAR",
            "result" : {
                "liveness_probability": 1.0,
                "liveness_score": 1.0,
                "quality_score": 1.0,
                "image_quality_warnings": [],
                "status_code": "OK"
            }
        },
        {
            "pipeline_name": "umbrellabird-ps",
            "calibration": "REGULAR",
            "result" : {
                "status_code": "DOCUMENT_PHOTO_NOT_FOUND"
            }
        }
    ]
}

Interpretation of result

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.

Quality score is a mark of image "goodness". High values indicate that image is quality enough for liveness checking.

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": "toucan-sr",
          "expirationDate": "2025-05-22"
      },
      {
          "attackType": "PRINTED_COPY",
          "pipelineName": "robin-pc",
          "expirationDate": "2025-05-22"
      },
      {
          "attackType": "PRINTED_COPY",
          "pipelineName": "penguin-pc",
          "expirationDate": "2025-05-22"
      },
      {
          "attackType": "PORTRAIT_SUBSTITUTION",
          "pipelineName": "umbrellabird-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": [
        "toucan-sr",
        "default-sr"
    ],
    "pipelineAliases": {
        "default-sr": "toucan-sr",
    },
    "expirationDates": {
        "toucan-sr": "2025-05-22"
    }
}

GET /bi_report¶

Query parameters

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_quality_0.9-1.0": 5,
    "auk_UNKNOWN_probability_0.9-1.0": 5
}