REST API reference¶
This reference contains all endpoints the IAD Server provides.
api_version¶
GET /api_version
Returns the information about IAD Server:
- Version of IAD Server.
- Expiration date for the license.
{
"product": "IADServer",
"version": "2.1.0",
"expirationDate": "2025-11-24T23:59:59Z"
}
check_capture_liveness¶
POST /check_capture_liveness
Performs a capture liveness check on a bundle generated by IAD client. Bundle should be sent as an application/octet-stream request.
On success response will contain capture_liveness field
{ "capture_liveness": { "probability": 1.0, "score": 1.0, "rejection": [] } }
If IAD Server is configured to check face liveness, then the response will contain additionaly the "face_liveness" field.
{
"face_liveness": { "probability": 0.9969119 },
"capture_liveness": { "probability": 1.0, "score": 1.0, "rejection": [] }
}
Whenever an image is rejected with a probability smaller than 0.5, the rejection field will contain one or more of the following reasons:
| Rejection reason | Description |
|---|---|
| UNTRUSTED_ENVIRONMENT | The environment in which the application runs is not trusted to be safe |
| SUSPICIOUS_ACTIVITY | Some activity has been detected in the device associated with an attack |
| UNTRUSTED_DEVICE | The device is not trusted to be the one it reports |
| SDK_INTEGRITY_VIOLATION | The capture librares have been modified |
| UNTRUSTED_CORRUPTED_PAYLOAD | The payload received is corrupted or has been modified |
| UNTRUSTED_CONTENT | Injection was detected in the image |
| UNTRUSTED_CONTENT_LOW_CONFIDENCE | Injection was detected in the image but the system classified the result with low confidence |
This rejections results are for analysis and metrics only and should not be forwared to the capture client to avoid giving information to potential bad actors.
For security purposes, we recommend treating UNTRUSTED_CONTENT_LOW_CONFIDENCE outcome as a valid rejection. Even at low confidence, the system has detected indicators consistent with an injection attempt, and accepting such cases may increase risk exposure. We are continuously working to minimize occurrences of low-confidence outcomes, especially on devices and environments that may have higher False Rejection Rates (FRR). To accelerate these improvements, we recommend sharing bi_records on monthly cadence. This enables us to better analyze device-specific behavior and deliver targeted optimizations more quickly.
On error response will contain message field with error description and error_code field with the corresponding error code for image validation errors or UNKNOWN for any other error.
{"timestamp":"2222-1-30T00:30:00.000+00:00","status":400,"error":"Bad Request","message":"Face not found","path":"/check_capture_liveness","error_code":"FACE_NOT_FOUND"}
This request can return the following errors:
| HTTP code | Message | Error code | Description |
|---|---|---|---|
| 400 | Face not found | FACE_NOT_FOUND | No faces have been detected in the image |
| 400 | Face is cropped | FACE_CROPPED | Face is only partially inside the image |
| 400 | Face is occluded | FACE_IS_OCCLUDED | Face is beeing partially hidden behind an object |
| 400 | Too many faces detected | TOO_MANY_FACES | More than one face is visible in the image |
| 400 | Facial out-of-plane rotation angle is extremely large | FACE_ANGLE_TOO_LARGE | Angle of the face corresponding to camera view point is to large |
| 400 | Absolute face size is too small | FACE_TOO_SMALL | Face pixel density is too small, it should be closer to the camera view point or image should be higher resolution |
| 400 | Relative face size is too small | FACE_TOO_SMALL | Face is too small, it should be closer to the camera view point, so it occupies a higher portion of the image |
| 400 | Face is too close to one or more borders | FACE_CLOSE_TO_BORDER | Face is to close to the limit of the camera's view point, it should be centered correponding with camera view. |
| 400 | Image too small to be processed | IMAGE_TOO_SMALL | Resolution of image in the payload is below 480p resolution |
| 400 | Failed to parse file | UNKNOWN | File is not a correct encrypted blob payload or is corrupted |
| 400 | Failed to read a meta data | UNKNOWN | Encrypted blob data is not generated with the correct format |
| 400 | Failed to decrypt message | UNKNOWN | Wrong public-private key pair is set on server and capture library (see Payload encryption) |
Error codes match with corresponding error codes from IDLiveFace.
extract_image¶
POST /extract_image
Extracts an image from a bundle. Bundle should be sent as an application/octet-stream request.
The response contains binary data with an image/jpeg media type.
This request can return the following errors:
| HTTP code | Message | Description |
|---|---|---|
| 400 | Failed to parse file | File is not a correct encrypted blob payload or is corrupted |
| 400 | Failed to decrypt message | Wrong public-private key pair is set on server and capture library (see Payload encryption) |
extract_data¶
POST /extract_data
Extracts specified data from a bundle. Bundle should be sent as an application/octet-stream request. This endpoint expects a types list query parameter.
https://iad-server/extract_data?types=external,photo
| types | response data |
|---|---|
| photo | photo from a bundle encoded in base64 |
| external | external data from a bundle |
This request can return the following errors:
| HTTP code | Message | Description |
|---|---|---|
| 400 | Failed to parse file | File is not a correct encrypted blob payload or is corrupted |
| 400 | Failed to decrypt message | Wrong public-private key pair is set on server and capture library (see Payload encryption) |
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.
bi_records¶
GET /bi_records
Returns Business Intelligence records collected by the 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. |