ID Document Verification

Introduction

The Upload Document Verification Data API allows you to verify and extract information from various identity documents such as passports, driving licenses, and more. This API is powered by Kairos and provides a seamless way to authenticate and validate identity documents.

Endpoint : https://idv-eu.kairos.com/v0.1/document-verification

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

Try importing below postman collection or link to check our apis

6KB

Kairos IDV APIs.postman

Endpoint 1: Upload Document for Verification

• Endpoint: POST /document-verification

• Description: Upload a document image for verification and receive a UUID (unique identifier).

• Parameters:

  • document: The identity document image file (Supported formats: JPG, PNG, PDF).

Example Request

Node.js

var request = require('request');
var fs = require('fs');
var options = {
  'method': 'POST',
  'url': 'https://idv-eu.kairos.com/v0.1/document-verification',
  'headers': {
    'app_id': 'put_app_id_here',
    'app_key': 'put_app_key_here'
  },
  formData: {
    '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/document-verification"
files=[
    ('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/document-verification' \
--header 'app_id: put_app_id_here' \
--header 'app_key: put_app_key_here' \
--form 'document=@"/path/to/document_image"' \
--form 'document_back=@"/path/to/document_back_image"'

Response

• Status Code: 201 (Created)

• Response Body:

{
  "api_req_uuid": "f55996c7-fcee-4f57-80f1-fff4a1b2388b"
}

Endpoint 2: Get Document Verification Data by UUID

• Endpoint: GET /document-verification/{api_req_uuid}

• Description: Retrieve data extracted from the uploaded document using the UUID obtained in the first request.

• Parameters:

  • api_req_uuid (URL parameter): The UUID received from the first request.

Example Request

Node.js

var request = require('request');
var app_req_uid = 'put_uuid_from_first_api_response';
var options = {
  'method': 'GET',
  'url': 'https://idv-eu.kairos.com/v0.1/document-verification/' + app_req_uid,
  '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/document-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/document-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'

Successful Response

• Status Code: 200 (OK)

• Response Body:

{
  "api_req_uid": "f55996c7-fcee-4f57-80f1-fff4a1b2388b",
  "processed_at": "2024-04-01 19:47:24",
  "requested_at": "2024-04-01 19:47:20",
  "response_code": 1,
  "response_data": {
    "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."
        },..
      ],
      "reject_score": 3,
      "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_side": ..,
        "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": ..
      }
    }
  }
}

Review and Reject Scores

• 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.

These scores and decisions are essential for determining whether the document verification process was successful, whether manual review is necessary, or whether the document should be rejected outright based on the confidence levels and specific criteria set by the verification system.

Users can interpret these scores and decisions to take appropriate actions in their application, such as flagging documents for review, rejecting documents with low confidence scores, or processing documents with high confidence scores automatically.

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.