Quick Start

Making your first API call

We've written a quick step-by-step guide to walk you through how to create a Kairos Developer account, make your first API call, and interpret the results.

Step 1: Register for an account

If you are an existing Kairos user, log in to your dashboard. If not, sign-up for Kairos - it's free to test.

Step 2: Get your APP ID and API Key

Once you’ve registered, and confirmed your email, you’ll be able to access your Dashboard. Here you’ll find your ‘App ID’ and ‘(API) Key’. Make a note of these credentials, you will use them in the next step.

Oh, and we automatically created your first app, to save you some time. You can rename this anytime.

This is a good example:

Step 1: Generate an API token

To start your integration, you will need an API token. To generate API tokens:

Access the Kairos Dashboard:
- Navigate to the 'Applications' section.
Application Registration:
- Provide the necessary details for your application, including the name and description.
Token Retrieval:
- Upon successful registration, copy the AppID and APPkey generated for your application.

Step 2: Create a verification request

Create a verification request by making a call to the Karios API. At a minimum, you will need to provide your_app_id, your_app_key, and file paths with your actual application ID, application key, and the paths to your identification document and selfie image, respectively.

This request can be made using any programming language that supports HTTPS requests.

Sample Code

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);
});

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 -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"'

The command returns a response containing the 'api_req_uuid', which is used in the next step to retrieve verification results.

Step 3: Retrieving verification results

Use the 'api_req_uuid' obtained from the previous step to request verification results.

This request can be made using any programming language that supports HTTP requests.

Sample Code

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);
});

import requests

# Specify the api_req_uuid directly
api_req_uuid = 'put_uuid_from_first_api_response'

# Base URL
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)

#!/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'

It may take some time to receive the verification results. It's recommended to try after 10 seconds from the previous step and repeat if necessary.

Sample Images

Sample Results

Note these are truncated results. For full JSON results try the demo images here.

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

Results breakdown

A successful response in the verification process includes an overall result for the verification check and detailed results for each individual report. The overall verification check result is derived from these individual report outcomes.

Components of the Response

Document Specifics:
- Detailed analysis and results pertaining to the document submitted for verification. This may include information about document authenticity, details extracted from the document, and any anomalies or issues detected.
Selfie Specifics:
- Analysis results related to the selfie submitted for verification. This typically involves facial recognition data, liveness detection, and comparison results between the selfie and the document photo, if applicable.
ID Verification:
- A comprehensive review of the identification verification process, including key points such as:
  - Success Indicator: Whether the ID verification was successful.
  - Transaction ID: A unique identifier for the verification transaction.
  - Warnings: List of any warnings or alerts generated during the verification process. These can include issues like unrecognized documents, multiple faces detected, liveness verification errors, and discrepancies between document and selfie images.
  - Decision: The final decision of the verification process (e.g., approved, rejected).
  - Scores: Any scoring metrics used to quantify aspects of the verification process, such as confidence scores, risk scores, etc.

PreviousDigital Identity Verification NextFull ID Verification

Last updated 1 month ago