> For the complete documentation index, see [llms.txt](https://docs.kairos.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kairos.com/documentation/full-api-reference/biometric-verification.md). # Biometric Verification ## Introduction This API allows you to perform biometric verification using a selfie image and Photo image. It analyzes the provided images and returns information about the detected face, face match confidence and the liveness score of selfie image ### Authentication To access the API, you need to include the following headers in your request: * `app_id`: Your application's unique identifier. * `app_key`: Your application's authentication key. #### Postman Collection Open the [Kairos Postman Collection](https://www.postman.com/martian-shuttle-95013/kairos-public/collection/0cj8cw1/kairos-idv-apis) to explore and test our APIs. #### Submit Verification Request Submit a verification request by providing a selfie image and a reference face image. * **URL**: `https://idv-eu.kairos.com/v0.2/biometric-verification` * **Method**: `POST` * **Headers**: * `Content-Type`: `multipart/form-data` * `app-id`: Your API application ID. * `app-key`: Your API application key. * **Body**: * `selfie` (File) - The selfie image file for liveness verification. * `image` (File) - The photo image file to check face similarity against selfie image. * `image_multiface`(optional, boolean)- Default is `false`. If the photo contains multiple faces, set the `image_multiface` parameter to `true` to analyze all faces and return the match confidence score. **Image Size Requirements**: * `selfie` — minimum 300 px, recommended > 900 px, maximum 5000 px. * `image` — minimum 300 px, recommended > 900 px, maximum 5000 px. **Sample Request** To make a biometric verification request, you can use the following examples: {% tabs %} {% tab title="Node.js" %} ``` var request = require('request'); var fs = require('fs'); var options = { 'method': 'POST', 'url': 'https://idv-eu.kairos.com/v0.2/biometric-verification', 'headers': { 'app_id': 'put_app_id_here', 'app_key': 'put_app_key_here' }, formData: { 'selfie': fs.createReadStream('/path/to/selfie_image'), 'image': fs.createReadStream('/path/to/photo_image'), } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://idv-eu.kairos.com/v0.2/biometric-verification" files=[ ('selfie',('file',open('/path/to/selfie_image','rb'))), ('image',('file',open('/path/to/photo_image','rb'))) ] headers = { 'app_id': 'put_app_id_here', 'app_key': 'put_app_key_here' } response = requests.request("POST", url, headers=headers, files=files) ``` {% endtab %} {% tab title="cURL" %} ```sh curl -X POST --location 'https://idv-eu.kairos.com/v0.2/biometric-verification' \ --header 'app_id: put_app_id_here' \ --header 'app_key: put_app_key_here' \ --form 'selfie=@"/path/to/selfie_image"' \ --form 'image=@"/path/to/photo_image"' ``` {% endtab %} {% endtabs %} Replace app\_id, app\_key, and selfie with your actual credentials and the path to your selfie image. #### Response * **Status Code:** 200 (OK) * **Response Headers:** * `Content-Type` — Media type of the response. Always `application/json`. * `Content-Length` — Size of the response body in bytes. * `X-Request-ID` — A unique identifier assigned to each request. * `X-Content-Type-Options: nosniff` — Prevents MIME type sniffing on the response. * `X-Frame-Options: DENY` — Prevents the response from being embedded in a frame or iframe. * `Strict-Transport-Security: max-age=86400; includeSubDomains` — Enforces HTTPS-only connections. * **Response Body:** ```json { "api_req_uid": "601d8377-03be-481e-a314-d61675154d3e", "processed_at": "2024-04-22 06:36:50", "requested_at": "2024-04-22 06:36:50", "response_code": 1, "response_data": { "biometric": { "face_match_confidence": 0.4803, "image": { "faces_predicted": [ { "confidence": 0.9999, "delta": { "x": 63.2991, "y": 86.6425 }, "top_left": { "x": 40.3778, "y": 42.5628 } } ], "img": { "height": 200, "width": 150 } }, "selfie": { "faces_liveness": 0.0026, "faces_predicted": [ { "confidence": 1, "delta": { "x": 235.0864, "y": 290.2446 }, "top_left": { "x": 153.1597, "y": 169.8101 } } ], "img": { "height": 666, "width": 500 } } }, "decision": { "details": [ { "code": "FAILED_FACE_MATCH", "confidence": 1, "decision": "review", "description": "Faces do not match; threshold failed: 0.4 < 0.4803 (actual) < 0.56" }, { "code": "FAILED_SELFIE_LIVENESS", "confidence": 1, "decision": "reject", "description": "Selfie liveness threshold failed: 0.4 < 0.0026 (actual) < 0.6" } ], "reject_score": 1, "review_score": 1, "warning_score": 0 } } } ``` ## Decision Information **Review Score**: This score indicates the level of review needed for the verification. A higher score may suggest a need for additional scrutiny or manual review. **Reject Score**: This score indicates the likelihood of rejection based on the verification results. A higher score may imply a higher probability of rejection. **Details**: This section may contain additional information or comments related to the verification decision. It can provide insights into why a particular decision was made. ## Biometric Data The Biometric Data section contains information related to the biometric aspects of the verification, including the photo and selfie images: #### Selfie Face Information: * **Image Width**: The width of the selfie image in pixels. * **Image Height**: The height of the selfie image in pixels. * **Faces Predicted**: Details about the predicted face(s) in the selfie image, including their positions and confidence scores. This information helps identify faces in the selfie. * **Faces Liveness**: The liveness score indicates the likelihood that the detected face(s) in the selfie are from a live person. A higher score suggests a higher level of confidence in the liveness of the faces. #### Photo Face Information: * **Image Width**: The width of the document image in pixels. * **Image Height**: The height of the document image in pixels. * **Faces Predicted**: Details about the predicted face(s) in the document image, including their positions and confidence scores. This information helps identify faces in the photo image. * **Face Match Confidence**: The confidence score for matching the detected face(s) in the selfie image with the photo image. A higher score indicates a stronger match between the two images. ### Other Responses * **5xx**: Server errors may occur, and the server will respond with an appropriate 5xx status code. In this case, please check your request and try again later. * **4xx**: Authentication failures may result in a 4xx status code. Make sure you have provided valid `app_id` and `app_key` in the request headers. * **403**: If limits are exceeded, you may receive a 403 Forbidden status code indicating that you have reached a usage limit. Check your account limits and consider upgrading your plan if needed. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kairos.com/documentation/full-api-reference/biometric-verification.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.