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

Endpoint

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

Parameters

• selfie (File) - The selfie image file for liveness verification. The image size must be at least 480x480 pixels.

• image (File) - The photo image file to check face similarity against selfie image. The image size must be at least 480x480 pixels.

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

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

Request

To make a biometric verification request, you can use the following examples:

Node.js

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

Python

import requests

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

cURL

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

Replace app_id, app_key, and selfie with your actual credentials and the path to your selfie image.

Response (HTTP 200)

If the request is successful, you will receive a response data:

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