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": 0.30822694, "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": 0.30822694, "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 |
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.
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. |