Skip to content

REST API reference

This reference contains all endpoints the IDLive Face Server provides. You can also explore the REST API via Swagger UI, it's available locally at:

http://localhost:8080/swagger-ui/index.html

api_version

GET /api_version

Returns the information about IDLive Face Server:

  1. Version of IDLive Face.
  2. Default and available pipelines.
  3. Expiration date for the license.
Response
{
  "product": "IDLive Face Server",
  "version": "1.46.0",
  "defaultPipeline": "astraea",
  "availablePipelines": ["astraea", "aphrodite"],
  "expirationDate": "2023-04-01T23:59:59Z"
}

check_liveness

POST /check_liveness

Performs a liveness check on an image or a series of images. Images should be send as a multipart/form-data request. In case of the series of images a single result will be produced by accumulating the results from the all images processed.

If you have configured IDLive Face Server to use multiple pipelines you can specify which one to use with the pipeline query parameter.

Parameter Type Description Required
pipeline query Pipeline to use.
Meta header Additional image characteristics.

The endpoint always replies with 200 OK response. If the image was rejected or any other error has occurred the response will contain the error field.

Positive response
{ "probability": 0.9946032, "quality": 0.72107375, "score": 5.2165456 }
Negative response
{
  "error": "Interpupillary distance is too small",
  "error_code": "FACE_TOO_SMALL"
}

check_image

POST /check_image

Performs an image check on a single image. Images should be sent as a multipart/form-data request, along with a JSON description specifying the pipelines and optional calibrations to be used for the checks.

Parameters

Parameter Type Description Required
data part JSON containing pipeline info.
image file The image file to be checked.

JSON structure for data parameter

'data' parameter structure
{
  "domain": "GENERAL",
  "pipelines": [
    {
      "pipeline": "perseus",
      "calibration": "HARDENED"
    },
    {
      "pipeline": "dfd-1",
      "calibration": "REGULAR"
    }
  ]
}
Field Type Description Required
domain string Image domain GENERAL or MOBILE.
pipelines list List of pipelines to execute.
pipelines[].pipeline string Name of pipeline to execute.
pipelines[].calibration string Pipeline calibration.

The endpoint returns 400 Bad Request in case of malformed request data, in all other cases the endpoint returns 200 OK. If the image was rejected by one of the pipelines corresponding result will contain the error field.

Positive response
{
  "serverVersion": "1.0.0",
  "licenseExpirationDate": "2025-01-01",
  "results": [
    {
      "pipeline": "perseus",
      "calibration": "HARDENED",
      "score": 0.85,
      "probability": 0.9946032,
      "quality": 0.72107375
    },
    {
      "pipeline": "dfd-pipeline",
      "calibration": "REGULAR",
      "score": 0.75,
      "probability": 0.8854023,
      "quality": 0.657824
    }
  ]
}
Negative response
{
  "serverVersion": "1.0.0",
  "licenseExpirationDate": "2025-01-01",
  "results": [
    {
      "pipeline": "perseus",
      "calibration": "REGULAR",
      "error": "Failed to detect face",
      "error_code": "FACE_NOT_FOUND"
    },
    {
      "pipeline": "dfd-pipeline",
      "calibration": "REGULAR",
      "error": "Failed to detect face",
      "error_code": "FACE_NOT_FOUND"
    }
  ]
}
Field Type Description
serverVersion string The current version of the server.
licenseExpirationDate string The expiration date of the license used by the server.
results list A list of results for each pipeline.
results[].pipeline string The name of the pipeline.
results[].calibration string The calibration applied to the pipeline.
results[].score float Score returned by the pipeline.
results[].probability float The probability assigned to the image by the pipeline.
results[].quality float The quality score indicating the overall quality of the image.
results[].error_code string Error code.
results[].error string Error description.

Example cURL Request

curl -X POST \
  http://localhost:8080/check_image \
  -H "Content-Type: multipart/form-data" \
  -F "image=@/path/to/your/image.jpg" \
  -F 'data={"domain":"GENERAL","pipelines":[{"pipeline":"perseus","calibration":"HARDENED"},{"pipeline":"dfd-pipeline","calibration":"REGULAR"}]}'

check_liveness_batch

POST /check_liveness_batch

Performs a batch of liveness checks on a series of images. Images should be send as a multipart/form-data request. Unlike the /check_liveness a response will contain results for all images.

If you have configured IDLive Face Server to use multiple pipelines you can specify which one to use with the pipeline query parameter.

Parameter Type Description Required
pipeline query Pipeline to use.
Meta header Additional image characteristics.

The endpoint always replies with 200 OK response. For rejected images the error will be a part of a response entry specific to this image. For any other errors the response will contain the error field.

Positive response
[
  {
    "file_name": "image1",
    "probability": 0.94960946,
    "quality": 0.72107375,
    "score": 2.9362469
  },
  {
    "file_name": "image2",
    "probability": 1.2596924e-5,
    "quality": 0.8110471,
    "score": -11.282045
  },
  {
    "file_name": "image3",
    "error": "Interpupillary distance is too small",
    "error_code": "FACE_TOO_SMALL"
  }
]

Note that an order of entries in the response is not guaranteed to match an order of images in the request. You need to rely on the file_name field to match the images and their results.

Negative response
{
  "error": "The request contains an unsupported pipeline, rejecting",
  "error_code": null
}

bi_report

GET /bi_report

Queries Business Intelligence records collected by IDLive Face Server and returns aggregated metrics about the Server's responses. You can optionally specify a required time frame.

Metrics for the quality and the probability are represented as a histogram with 0.1 interval.

Parameter Type Description Required
date_from query The beginning of time frame in yyyy-MM-dd format.
date_to query The end of time frame in yyyy-MM-dd format. Inclusive.

Note

Before the version 1.30 the date_from and date_to parameters were mandatory.

Response
{
  "theia_DESKTOP_probability_0.0-0.1": 2,
  "theia_DESKTOP_quality_0.8-0.9": 2,
  "theia_IOS_probability_0.9-1.0": 1,
  "theia_IOS_quality_0.7-0.8": 1,
  "theia_UNKNOWN_FACE_TOO_SMALL": 3,
  "theia_UNKNOWN_probability_0.0-0.1": 4,
  "theia_UNKNOWN_probability_0.9-1.0": 3,
  "theia_UNKNOWN_quality_0.7-0.8": 3,
  "theia_UNKNOWN_quality_0.8-0.9": 4,
  "total": 13
}

bi_records

GET /bi_records

Returns Business Intelligence records collected by IDLive Face Server. You can optionally specify a required time frame.

Parameter Type Description Required
date_from query The beginning of time frame in yyyy-MM-dd format.
date_to query The end of time frame in yyyy-MM-dd format. Inclusive.

Warning

We strongly encourage you to share these records with us on a monthly basis. You can conveniently do so by uploading them through the customer portal or by emailing them to your designated ID R&D contact person. Your valuable input not only enables us to gather essential data for enhancing our overall product but also empowers us to provide personalized suggestions on optimizing your implementation for optimal results.

System endpoints

health

GET /health

Provides a means of checking the health of a running Server. Returns 200 if everything is ok, and 503 if there is a problem.

metrics

GET /metrics

The metrics in the Prometheus format. You can use them to monitor a license expiration date.