Getting Started

ID Analyzer API is accessed through the HTTP protocol by making a POST request with the document image file and extra parameters to the API endpoint:

Uploading Image

There are three different methods of uploading the document and face image to ID Analyzer API, through either multipart/form-data file upload, base64 encoded image, or remote URLs.

Multipart/form-data File Upload

In multipart/form-data, each value is sent as a block of data ("body part"), with a user agent-defined delimiter ("boundary") separating each part. This type of encoding is very common when uploading files through web browser. To upload files using this method, simply make sure you use they field key file and face.

Key Value Description
file multipart/form-data encoded image file with filename The identity document image which will be analyzed by ID Analyzer system. JPG, PNG, BMP, GIF, PDF files are supported.
face multipart/form-data encoded image of a person [Optional] Required only if you wish to perform biometric verification.

Base64 Encoded Image

You may also submit base64 encoded images using HTTP POST with content-type application/x-www-form-urlencoded or application/json.

Key Value Description
file_base64 Base64 encoded document image The identity document image which will be analyzed by ID Analyzer system. The API will automatically determine input image type. JPG, PNG, BMP, GIF, PDF supported.
face_base64 Base64 encoded image of a person [Optional] Required only if you wish to perform biometric verification.

Remote URLs

Our API is capable of downloading remote document images on your server for scanning and verification.

Key Value Description
url URL to identity document image A remote URL to document image.
faceurl URL to image of a person [Optional] A remote URL to image of a person.

Post Parameters

Here is a list of parameters that should be included in the post request to the API.

Key Value Description
apikey API key Your private API key is available under your account dashboard.
authenticate true: Enable
false: Disable (Default)
[Optional] Authenticate the document to check whether the document is real and has not been tampered.
log true: Log response results under your account dashboard (Default)
false: All information will be wiped upon completion of API request
[Optional] Enable or disable logs which can be viewed from your account dashboard. For highest level of security and data privacy, we recommend turning off this parameter for production to ensure that no identity information will be stored on our server. For more information plaese view our Data Protection Policy.
outputimage true: Enable
false: Disable (Default)
[Optional] Produce a cropped version of the document. (This feature cannot be used if logging is disabled)
verify_expiry true: Enable
false: Disable (Default)
[Optional] Check if the document is still valid based on its expiry date.
verify_documentno Document number requiring verification [Optional] Attempt to match the supplied document number with number on document.
verify_name Full name including first name and last name requiring verification [Optional] Attempt to match the supplied name with the name on document.
verify_dob Date of birth requiring verification, in YYYY/MM/DD format [Optional] Attempt to match the supplied date of birth with the date of birth on document.
verify_age Age range, example: 18-40 [Optional] Check if the document holder is aged between the given range.
verify_address Full address requiring verification [Optional] Attempt to match the supplied address with the address on document.
verify_postcode Full postcode requiring verification [Optional] Attempt to match the supplied postcode with the postcode on document.
country ISO ALPHA-2 Country Code [Optional] Check if the document was issued by specified countries, if not error code 10 will be thrown. Separate multiple values with comma. For example "US,CA" would accept documents from United States and Canada.
region The state/region where the document is issued [Optional] Check if the document was issued by specified state, if not error code 11 will be thrown. Separate multiple values with comma. For example "CA,TX" would accept documents from California and Texas.
type P: Passport
D: Driver's License
I: Identity Card
[Optional] Check if the document was one of the specified types, if not error code 12 will be thrown. For example "PD" would accept both passport and drivers license.

Response

The API will return data encoded in JSON, an example of successful request:

{
    "result": {
        "address1": "2570 24TH STREET",
        "address2": "ANYTOWN, CA",
        "age": 42,
        "daysFromIssue": 3802,
        "daysToExpiry": -1975,
        "dob": "1977\/08\/31",
        "dob_day": 31,
        "dob_month": 8,
        "dob_year": 1977,
        "documentNumber": "11234568",
        "documentSide": "FRONT",
        "documentType": "D",
        "expiry": "2014\/08\/31",
        "expiry_day": 31,
        "expiry_month": 8,
        "expiry_year": 2014,
        "firstName": "IMA",
        "height": "5-05\"",
        "internalId": "2",
        "issued": "2009\/08\/31",
        "issued_day": "31",
        "issued_month": "08",
        "issued_year": "2009",
        "issuerOrg_full": "United States",
        "issuerOrg_iso2": "US",
        "issuerOrg_iso3": "USA",
        "issuerOrg_region_abbr": "CA",
        "issuerOrg_region_full": "California",
        "lastName": "CARDHOLDER",
        "nationality_full": "United States",
        "nationality_iso2": "US",
        "nationality_iso3": "USA",
        "postcode": "95818",
        "sex": "F",
        "weight": "125"
    },
    "face": {
        "isIdentical": false,
        "confidence": "0.091"
    },
    "verification": {
        "passed": false,
        "result": {
            "face": false,
            "notexpired": false,
            "name": true,
            "dob": true,
            "postcode": true,
            "address": false
        }
    },
    "authentication": {
        "score": 0.5,
    },
    "executionTime": 1.3062239170074462890625,
    "responseID": "25ca84e72040fcf060f6f20f76031cd0",
    "quota": 999,
    "credit": 999
}

Example of failed request:

{
    "error": {
        "message": "Document not recognized",
        "code": 9
    },
    "executionTime": 0.0062239170074462890625,
    "responseID": "45ca84e72040fcf060f6f20f76031cd0"
}
Key Description
result[array] Contains an array of matched fields and their value. Possible values are:

Document Numbers

documentNumber[str]
The unique identifier of the document (Passport No./Driver License No. etc)
personalNumber[str]
A secondary identifier number on the document

Names

firstName[str]
First name / Given name
middleName[str]
Middle name(s)
lastName[str]
Last name / Family name
fullName[str]
If the first name and last name cannot be distinguished, full name will be returned instead
firstName_local[str]
First name in local language if available
middleName_local[str]
Middle name in local language if available
lastName_local[str]
Last name in local language if available
fullName_local[str]
Full name in local language if available

Dates

dob[str]
Date of birth in YYYY/MM/DD
dob_day[int]
Date of birth day 1 to 31
dob_month[int]
Date of birth month 1 to 12
dob_year[int]
Date of birth year in YYYY
expiry[str]
Expiry date of document in YYYY/MM/DD
expiry_day[int]
Day of expiry 1 to 31
expiry_month[int]
Month of expiry 1 to 12
expiry_year[int]
Year of expiry in YYYY
issued[str]
Date of issue in YYYY/MM/DD
issued_day[int]
Day of issue 1 to 31
issued_month[int]
Month of issue 1 to 12
issued_year[int]
Year of issue in YYYY
daysToExpiry[int]
Number of days before the document expires
daysFromIssue[int]
Number of days since the document was issued

Personal Information

age[int]
Age of the document holder
sex[str]
Gender M=Male, F=Female, X=Unspecified
height[str]
Height of person
weight[str]
Weight of person
address1[str]
Address line 1
address2[str]
Address line 2
postcode[str]
Address postcode
placeOfBirth[str]
Place of birth

Document Information

documentSide[str]
Side of the document: FRONT, BACK or BIODATA
documentType[str]
Type of document: P=Passport, D=Driver's License, I=Identity Card, V=Visa, R=Residence Card, O=Other
documentName[str]
If documentType is "O", a document name will be included.
issuerOrg_region_full[str]
Document issuer subregion/state. Example: California
issuerOrg_region_abbr[str]
Document issuer subregion/state abbreviation. Example: CA
issuerOrg_full[str]
Document issued country. Example: United States
issuerOrg_iso2[str]
Document issued country code in ISO2. Example: US
issuerOrg_iso3[str]
Document issued country code in ISO3. Example: USA
nationality_full[str]
Document holder nationality. Example: United States
nationality_iso2[str]
Document holder nationality in ISO2. Example: US
nationality_iso3[str]
Document holder nationality in ISO3. Example: USA

Other Data

optionalData[str]
Extra unspecific data included in the document
optionalData2[str]
Extra unspecific data included in the document
internalId[int]
Used to identify the unique document ID under ID Analyzer system, same type of document should have the same ID.
face[array] If a biometric verification request was submitted, an array will be returned:
isIdentical[bool]
true
Biometric verification passed
false
Biometric verification failed
confidence[float]
Value between 0 to 1 on how similar the two faces are, 1 being identical.
Upon Error, a different array will be returned:
error[int]
This value will always return 1
error_message[str]
Error message. Example: Could not find face data within facial image
authentication[array] If authenticate is set to true, an array will be returned:
score[float]
The score will be a float between 0 to 1. Genuine authentic documents will have a score closer to 1 while fake or edited documents will have a score closer to 0. It is your discretion to decide the boundary, a good starting point would be rejecting score less than 0.5
verification[array] If any of the verification parameters were submitted, an array will be returned:
passed[bool]
true
Document has passed all verification
false
Document has failed at least one verification type
result[array]
Array containing keys for individual verification including notexpired, name, dob, address, postcode, and the corresponding verification result: true|false.
matchrate[float] The ratio of fields successfully recognized by the API, a low ratio would indicate the document image is too blurry.
output[str] If outputimage is set to true, the response will include an URL pointing to the cropped document image. The image will expire and be deleted in 600 seconds for security.
executionTime[float] Time taken for the API operation in seconds.
responseID[str] A unique identifier to identify the request/response.
quota[int] Remaining API quota this month, resets beginning of each month. If you have a monthly plan, your monthly quota will be used before prepaid credit.
credit[int] Remaining prepaid credit for your account. If you have a monthly plan, your monthly quota will be used before prepaid credit.
error[array] This field will only be returned if there was an error, containing the following array:
code[int]
1
Invalid API Key
2
Invalid remote image URL
3
Download remote image failed
4
Invalid remote image MIME type
5
No input document image detected
6
Invalid file extension for file upload
7
Image file format not supported or corrupted
8
You have exhausted your quota, please purchase or upgrade your subscription plan.
9
Document not recognized
10
Document was not issued by one of the specified countries
11
Document was not issued by one of the specified regions
12
Document of this type is not accepted
99
Unexpected API error
message[str]
Description of the error encountered.

Code Examples

Base64 Image upload
<?php
$pathToDocumentImage = "document.jpg";
$post = [
    'file_base64' => base64_encode(file_get_contents($pathToDocumentImage)),
    'apikey' => 'YOUR API KEY'
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.idanalyzer.com');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($post));
$response = curl_exec($ch);
var_export($response);
?>
import requests
import base64

documentpath = "documentimage.jpg"
facepath = "face.jpg"
apikey = "Your API Key"

with open(documentpath, "rb") as image_file:
    encoded_document_image = base64.b64encode(image_file.read())
with open(facepath, "rb") as faceimage_file:
    encoded_face_image = base64.b64encode(faceimage_file.read())

payload = {'apikey': apikey, 'file_base64': encoded_document_image, 'face_base64': encoded_face_image}

r = requests.post("https://api.idanalyzer.com", data=payload)
result = r.json()
if "error" in result:
    #failed
    print("Error #" + str(result['error']['code']) + " " + result['error']['message'])
else:
    #success
    print(result['result'])

Multipart/formdata image upload
<?php

$url = 'https://api.idanalyzer.com';
$apikey = 'Your API Key';

$header = array('Content-Type: multipart/form-data');
$path_to_document = realpath('document.jpg');
$path_to_face = realpath('face.jpg');

if (function_exists('curl_file_create')) {
	$image1 = curl_file_create($path1);
	$image2 = curl_file_create($path2);
} else {
	$image1 = '@' . $path1;
	$image2 = '@' . $path2;
}

$fields = array('file' => $image1, 'face' =>  $image2, 'apikey' => $apikey);
$resource = curl_init();
curl_setopt($resource, CURLOPT_URL, $url);
curl_setopt($resource, CURLOPT_HTTPHEADER, $header);
curl_setopt($resource, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($resource, CURLOPT_POST, 1);
curl_setopt($resource, CURLOPT_POSTFIELDS, $fields);
$result = json_decode(curl_exec($resource),true);
curl_close($resource);

if(!array_key_exists('error', $result)){
    //success
    print_r($result);
}else{
    //failed
    echo("Error #" . $result['error]['code'] . " " . $result['error']['message']);
}

?>
import requests

#load image from file
documentfile = open('document_image_path', 'rb')
facefile = open('face_image_path', 'rb')
headers = {'content-type': 'multipart/form-data'}

payload = {'apikey': 'your_apikey'}
files = {'file': documentfile, 'face': facefile}
r = requests.post("https://api.idanalyzer.com", data=payload, files=files)
result = r.json()
if "error" in result:
    #failed
    print("Error #" + str(result['error']['code']) + " " + result['error']['message'])
else:
    #success
    print(result['result'])

Load from a remote image
<?php

$url = 'https://api.idanalyzer.com';
$apikey = 'Your API Key';

$path_to_document = "https://www.idanalyzer.com/assets/images/sampleid.jpg";
$path_to_face = "https://www.idanalyzer.com/assets/images/sampleface.jpg";

$fields = array('url' => $path_to_document, 'faceurl' =>  $path_to_face, 'apikey' => $apikey);
$resource = curl_init();
curl_setopt($resource, CURLOPT_URL, $url);
curl_setopt($resource, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($resource, CURLOPT_POST, 1);
curl_setopt($resource, CURLOPT_POSTFIELDS, $fields);
$result = json_decode(curl_exec($resource),true);
curl_close($resource);

if(!array_key_exists('error', $result)){
	//success
	print_r($result);
}else{
	//failed
	echo("Error #" . $result['error']['code'] . " " . $result['error']['message']);
}

?>
import requests

#load image from url

path_to_document = "https://www.idanalyzer.com/assets/images/sampleid.jpg";
path_to_face = "https://www.idanalyzer.com/assets/images/sampleface.jpg";
headers = {'content-type': 'multipart/form-data'}
payload = {'apikey': 'your_apikey', 'url': path_to_document, 'faceurl': path_to_face}
r = requests.post("https://api.idanalyzer.com", data=payload)
result = r.json()
if "error" in result:
    #failed
    print("Error #" + str(result['error']['code']) + " " + result['error']['message'])
else:
    #success
    print(result['result'])