API Documentation

Getting Started

ID Analyzer API is accessed through the HTTP interface by posting a multipart/form-data request with the image file and relevant parameters to the API URL. multipart/form-data will not be required if you choose to load the image from a remote image file.

https://www.idanalyzer.com/api

Post Parameters

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

Key Value Description
apikey 16 digit API key API key is available under your account dashboard.
file Multipart encoded image file with filename The identity document image which will be analyzed by ID Analyzer system.
url URL of remote identity document image [Optional] Allows you to specify a remote URL instead of uploading the identity document image file.
face Multipart encoded image of a person's face [Optional] Required only if you wish to compare a person's face against photo identity document.
faceurl URL of remote facial image file [Optional] Allows you to specify a remote URL instead of uploading the facial image file.
authenticate true: Enable
false: Disable (Default)
[Optional] Whether to authenticate the document and produce an authentication score.
verify_expiry true: Enable
false: Disable (Default)
[Optional] Whether to check if the is still valid based on its expiry date.
verify_documentno Document number needing verification [Optional] The system will attempt to match the provided document number with number on document.
verify_name Full name including first name and last name needing verification [Optional] The system will attempt to match the provided name with the name on document.
verify_dob Date of birth needing verification, in YYYY/MM/DD format [Optional] The system will attempt to match the date of birth with the date of birth on document.
verify_address Full address needing verification [Optional] The system will attempt to match the provided address with the address on document.
verify_postcode Full postcode needing verification [Optional] The system will attempt to match the provided postcode with the postcode on document.
country ISO ALPHA-2 Country Code [Optional] Limit the document scan to a particular country, the scan will fail if the document is not issued by this country.
region The state/region where the document is issued [Optional] Limit the document scan to a particular state or region within a country, the scan will fail if the document is not issued by this region.
type 0: Passport
1: Driver's License
2: Identity Card
3: Other
[Optional] Limit the document scan to a particular document type, the scan will fail if the document is not of specified type.
log true: Log results on secure server (Default)
false: Disable result logging, no data will be kept on server
[Optional] Enable or disable request/response logging which can be viewed from account dashboard.

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,
    "computeTime": 1.005443096160888671875,
    "responseID": "25ca84e72040fcf060f6f20f76031cd0",
    "quota": 999,
    "credit": 999
}

Example of failed request:

{
    "error": {
        "message": "Document not recognized",
        "code": 9
    },
    "executionTime": 0.0062239170074462890625,
    "computeTime": 0.005443096160888671875,
    "responseID": "45ca84e72040fcf060f6f20f76031cd0"
}
Key Description
result Contains an array of matched fields and their value. Possible values are:
documentNumber: The unique identifier of the document (Passport No./Driver License No. etc)
firstName: First name
middleName: Middle name
lastName: Last name
fullName: If first name and last name cannot be distinguished, will return full name instead
personalNumber: A secondary identifier number on the document
dob_day: Date of birth day 1 to 31
dob_month: Date of birth month 1 to 31
dob_year: Date of birth year in YYYY
dob: Date of birth in YYYY/MM/DD
age: Age of the document holder sex: M=Male, F=Female, X=Unspecified
height: Height of person
weight: Weight of person
expiry_day: Day of expiry 1 to 31
expiry_month: Month of expiry 1 to 12
expiry_year: Year of expiry in YYYY
expiry: Expiry date of document in YYYY/MM/DD
daysToExpiry: Number of days before the document expires issued_day: Day of issue 1 to 31
issued_month: Month of issue 1 to 12
issued_year: Year of issue in YYYY
issued: Issue date of document in YYYY/MM/DD
daysFromIssue: Number of days since the document was issued address1: Address line 1
address2: Address line 2
postcode: Address postcode
placeOfBirth: Place of birth
documentSide: FRONT, BACK, BIODATA
documentType: P=Passport, D=Driver's License, I=Identity Card, V=Visa, R=Residence Card, O=Other
issuerOrg_region_full: Document issuer subregion/state
issuerOrg_region_abbr: Document issuer subregion/state abbreviation
issuerOrg_full: Document issued country
issuerOrg_iso2: Document issued country code in ISO2
issuerOrg_iso3: Document issued country code in ISO3
nationality_full: Document holder nationality
nationality_iso2: Document holder nationality in ISO2
nationality_iso3: Document holder nationality in ISO3
internalId: Used to identify the internal ID of this document under ID Analyzer systen
optionalData: Optional data included in the document
optionalData2: Optional data included in the document
face If a face comparison request was submitted, will return an array:
isIdentical: true or false whether the face submitted matches the face on document
confidence: value between 0~1 on how similar the two faces are, 1 being identical.

Upon Error, will return a different array:
error: always return 1
error_message: error message. ex: Could not find face data within facial image
verification If any of the verification parameters were submitted, will return an array:
passed: true or false whether all the verification requested have passed
result: A list key-value array of verifications done including notexpired, name, dob, address, postcode, and their whether each item has passed verification (true or false).
authentication If authenticate is set to true, the response will return authenticate key containing score. 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
executionTime Time taken to upload the documents and compute result.
computeTime Time taken to compute result.
responseID A unique identifier to identify the request/response.
quota Remaining API quota for your monthly subscription plan. If you have a monthly plan, your monthly quota will be used before prepaid credit.
credit Remaining prepaid credit for your account. If you have a monthly plan, your monthly quota will be used before prepaid credit.
error This field will only be returned if there was an error, containing the following array:
code
1: Invalid API Key
2: Invalid remote image URL
3: Download remote image failed
4: Invalid remote image MIME type
5: No input file detected. (both file and url parameters are missing)
6: Invalid file extension for file upload
7: The input image file is corrupted
8: You have exhausted your quota, please purchase or upgrade your subscription plan.
9: No recognizable document found in input image
99: Unexpected API error

message: Description of the error encountered.

Example Request

This is what a raw request would look, don't worry if it looks complex, the coding to produce the same result is actually very easy through libraries such as cURL, check the code examples.

curl -v -F apikey=a7412c8ac8c8d738 -F file=@image.jpg https://www.idanalyzer.com/api

POST /api HTTP/1.1
Content-Length:17778
Content-Type:multipart/form-data; boundary=---------------------------3339166599332
Host:www.idanalyzer.com

---------------------------3339166599332
Content-Disposition: form-data; name="file"; filename="image.jpg"
Content-Type: image/png

{image data here}
---------------------------3339166599332
Content-Disposition: form-data; name="apikey"

a7412c8ac8c8d738
---------------------------3339166599332

Code Examples

Standard image file upload
<?php

$url = 'https://www.idanalyzer.com/api';
$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://www.idanalyzer.com/api", 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://www.idanalyzer.com/api';
$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://www.idanalyzer.com/api", data=payload)
result = r.json()
if "error" in result:
    #failed
    print("Error #" + str(result['error']['code']) + " " + result['error']['message'])
else:
    #success
    print(result['result'])