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

Try importing below postman collection or link to check our apis

6KB

Kairos IDV APIs.json

STEP 1 : Get UUID

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.1/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 document back image to be verified.

Example Request:

Node.js

var request = require('request');
var fs = require('fs');
var options = {
  'method': 'POST',
  'url': 'https://idv-eu.kairos.com/v0.1/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);
});

Python

import requests

url = "https://idv-eu.kairos.com/v0.1/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)

cURL

curl -X POST --location 'https://idv-eu.kairos.com/v0.1/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"'

Response

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.

{"api_req_uuid":"fca044bd-a6a7-4a4a-bc11-ecd012ec7af3"}

STEP 2 : 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.1/full-id-verification/{uuid} (Replace {uuid} with the actual UUID obtained in Step 1)

• Method: GET

• Headers:

  • Content-Type: application/json

  • app-id: Your API application ID.

  • app-key: Your API application key.

Example Request

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.1/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);
});

Python

import requests

api_req_uuid = 'put_uuid_from_first_api_response'
url = f"https://idv-eu.kairos.com/v0.1/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)

cURL

#!/bin/bash

# Base URL
base_url="https://idv-eu.kairos.com/v0.1/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'

Response

The API response for this step will contain detailed verification results in JSON format, including decision information, biometric data, and verification data.

{
  "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.