> 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/full-id-verification.md). # Full ID Verification ## Introduction The Full ID Verification API allows you to perform identity verification using a document and a selfie image. This API provides valuable information extracted from the provided images, including personal details and biometric data. ## Authentication To use the Full ID Verification API, you need to authenticate your requests by including your API credentials (`app-id` and `app-key`) in the HTTP headers. #### 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. #### **STEP 1 :** Submit Verification Request Submit a verification request by providing a document image and a selfie image. The API will process these images and provide you with a Unique Identifier (UUID) for tracking and retrieving the results. * **URL**: `https://idv-eu.kairos.com/v0.2/full-id-verification` * **Method**: `POST` * **Headers**: * `Content-Type`: `multipart/form-data` * `app-id`: Your API application ID. * `app-key`: Your API application key. * **Body**: * `selfie`: The selfie image for comparison. * `document`: The document front image to be verified. * `document_back`: The optional document back image to be verified. * `profile`: optional parameter with default value `optimal-v0`, you can ensure that the verification process aligns with your security requirements and use case scenarios. Check [link](/documentation/full-api-reference/full-id-verification/profile-use-case.md) for more details * **Image Size Requirements**: * `selfie` — minimum 300 px, recommended > 900 px, maximum 5000 px. * `document` — minimum 240 px, recommended > 1200 px, maximum 5000 px. * `document_back` — minimum 240 px, recommended > 1200 px, maximum 5000 px. \ **Example Request:** {% 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/full-id-verification', 'headers': { 'app_id': 'put_app_id_here', 'app_key': 'put_app_key_here' }, formData: { 'selfie': fs.createReadStream('/path/to/selfie_image'), 'document': fs.createReadStream('/path/to/document_image'), 'document_back': fs.createReadStream('/path/to/document_back_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/full-id-verification" files=[ ('selfie',('file',open('/path/to/selfie_image','rb'))), ('document',('file',open('/path/to/document_image','rb'))), ('document_back',('file',open('/path/to/document_back_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/full-id-verification' \ --header 'app_id: put_app_id_here' \ --header 'app_key: put_app_key_here' \ --form 'selfie=@"/path/to/selfie_image"' \ --form 'document=@"/path/to/document_image"' \ --form 'document_back=@"/path/to/document_back_image"' ``` {% endtab %} {% endtabs %} #### Response The verification request is processed asynchronously. The API response for this step will include a UUID (Unique Identifier) that you will use in the next step to fetch the verification results. ```json {"api_req_uid":"fca044bd-a6a7-4a4a-bc11-ecd012ec7af3"} ``` **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. #### **STEP 2 : Polling - Get Verification Results** Once you have obtained the UUID from the initial request, you can use it to retrieve the verification results in JSON format. * **URL**: `https://idv-eu.kairos.com/v0.2/full-id-verification/{uuid}` (Replace `{uuid}` with the actual UUID obtained in Step 1) * **Method**: `GET` * **Headers**: * `app-id`: Your API application ID. * `app-key`: Your API application key. **Polling strategy** Start polling 4 seconds after the initial POST request. Increase the polling interval by 2 seconds after each attempt (4s → 6s → 8s → 10s ...). Continue polling until the API returns an HTTP 200 response with `"response_code": 1`. Set a maximum polling timeout of 2 minutes to avoid polling indefinitely. * `200` with `response_code: null` — Request is queued, Results are not yet available. * `200` with `response_code: 1` — Processing complete — result is ready in `response_data` * `404` — Invalid `api_req_uuid`. The requested verification record does not exist. **Example Request** {% tabs %} {% tab title="Node.js" %} ``` var request = require('request'); var app_req_uuid = 'put_uuid_from_first_api_response'; var options = { 'method': 'GET', 'url': 'https://idv-eu.kairos.com/v0.2/full-id-verification/' + app_req_uuid, 'headers': { 'app_id': 'put_app_id_here', 'app_key': 'put_app_key_here' }, }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests api_req_uuid = 'put_uuid_from_first_api_response' url = f"https://idv-eu.kairos.com/v0.2/full-id-verification/{api_req_uuid}" headers = { 'app_id': 'put_app_id_here', 'app_key': 'put_app_key_here' } response = requests.request("GET", url, headers=headers) ``` {% endtab %} {% tab title="cURL" %} ```sh #!/bin/bash # Base URL base_url="https://idv-eu.kairos.com/v0.2/full-id-verification/" # Specify the api_req_uuid directly api_req_uuid="put_uuid_from_first_api_response" # Constructing the full URL with the provided api_req_uuid url="$base_url$api_req_uuid" # Making the curl request curl --location "$url" \ --header 'app_id: put_app_id_here' \ --header 'app_key: put_app_key_here' ``` {% endtab %} {% endtabs %} #### Response The API response for this step will contain detailed verification results in JSON format, including decision information, biometric data, and verification data. * **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:** ```json5 { "api_req_uid": "fca044bd-a6a7-4a4a-bc11-ecd012ec7af3", "processed_at": "2024-04-01 19:08:26", "requested_at": "2024-04-01 19:08:21", "response_code": 1, "response_data": { "biometric": { "document": { "faces_predicted":.. }, "face_match_confidence": 0.1565, "selfie": { "faces_liveness": 0.9999, "faces_predicted": .. } }, "decision": { "details": [ { "code": "DOCUMENT_EXPIRED", "confidence": 0.995, "decision": "reject", "description": "Document has already expired." }, { "code": "FAKE_ID", "confidence": 1, "decision": "reject", "description": "The document uploaded is a fake or sample document, not an authentic document. Matching personal number from database." }, { "code": "FAILED_FACE_MATCH", "confidence": 1, "decision": "reject", "description": "Faces do not match; threshold failed: 0.4 < 0.15651057958602907 (actual) < 0.56" } ], "reject_score": 4, "review_score": 1, "warning_score": 0 }, "document": { "data": { "age": ., "country_full": .., "country_iso2": .., "country_iso3": .., "days_from_issue": .., "days_to_expiry": .., "dob": .., "dob_day": .., "dob_month": .., "dob_year": .., "document_name": .., "document_type": .., "expiry": .., "expiry_day": .., "expiry_month": .., "expiry_year": .., "first_name": .., "full_name": .., "internal_id": .., "issued": .., "issued_day": .., "issued_month": .., "issued_year": .., "last_name": .., "nationality_full": .., "personal_number": .., "place_of_birth": .., "sex": .. } } } } ``` ## 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 document 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. #### Document 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 document. * **Face Match Confidence**: The confidence score for matching the detected face(s) in the selfie image with the document image. A higher score indicates a stronger match between the two images. ## Document Data The document data section contains detailed information extracted from the document and selfie images, providing insights into the personal details of the individual being verified: * **Address**: Extracted address details, including confidence scores and input box coordinates. * **Age**: Extracted age information with confidence scores and input box coordinates. * **Country**: Extracted country information, including full name and ISO codes. * **Date of Birth (DOB)**: Extracted date of birth information, including day, month, year, and full DOB, along with confidence scores and input box coordinates. * **Document Number**: Extracted document number with confidence scores and input box coordinates. * **Document Type**: The type of the document, such as "D." * **Expiry Date**: Extracted expiry date information with confidence scores and input box coordinates. * **First Name**: Extracted first name with confidence scores and input box coordinates. * **Full Name**: Extracted full name with confidence scores and input box coordinates. * **Internal ID**: Internal identification information with confidence scores. * **Issue Authority**: The authority that issued the document, with confidence scores and input box coordinates. * **Issued Date**: Extracted issued date information with confidence scores and input box coordinates. * **Last Name**: Extracted last name with confidence scores and input box coordinates. * **Middle Name**: Extracted middle name with confidence scores and input box coordinates. * **Nationality**: Extracted nationality information, including full name and ISO codes. * **Place of Birth**: Extracted place of birth with confidence scores and input box coordinates. * **Vehicle Class**: Extracted vehicle class information with confidence scores and input box coordinates. This comprehensive set of verification data offers insights into the individual's personal information and document details, including any other data present in the document. The example provided is specific to a driving license, but the API will extract relevant information from various types of documents as applicable. --- # 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/full-id-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.