API Documentation

Getting Started

IDAnalyzer 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.
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 Document issueing state/region [Optional] Limit the document scan to a particular state/region within a country, the scan will fail if the document is not issued by this region.
type Document type [Optional] Limit the document scan to a particular document type, the scan will fail if the document is not of specified type.
0: Passport
1: Driver's License
2: Identity Card
3: Other
log Log API Response [Default = true] Enable or disable request/response logging which can be viewed from account dashboard.
true: Log results on secure server
false: Disable result logging, no data will be kept on server

Response

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

{
    "result": {
        "documentNumber": "l1234568",
        "firstname": "IMA",
        "lastname": "CARDHOLDER",
        "dob_day": 31,
        "dob_month": 8,
        "dob_year": 1977,
        "sex": "F",
        "height": "5'-05\"",
        "weight": "125 lb",
        "issued_day": "31",
        "issued_month": "08",
        "issued_year": "2009",
        "expiry_day": 31,
        "expiry_month": 8,
        "expiry_year": 2014,
        "address1": "2570 24TH STREET",
        "address2": "ANYTOWN, CA",
        "postcode": "95818",
        "dob": "31\/08\/1977",
        "expiry": "31\/08\/2014",
        "issued": "31\/08\/2009",
        "documentSide": "FRONT",
        "documentType": "D",
        "issuerOrg_region_full": "California",
        "issuerOrg_region_abbr": "CA",
        "issuerOrg_full": "United States",
        "issuerOrg_iso2": "US",
        "issuerOrg_iso3": "USA",
        "nationality_full": "United States",
        "nationality_iso2": "US",
        "nationality_iso3": "USA",
        "internalId": "51"
    },
    "face": {
        "isIdentical": false,
        "confidence": 0.09812
    },
    "executionTime": 1.3062239170074462890625,
    "computeTime": 1.005443096160888671875,
    "responseID": "25ca84e72040fcf060f6f20f76031cd0",
    "quota": 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
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 DD/MM/YYYY
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 DD/MM/YYYY
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 DD/MM/YYYY
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 confidence score

Upon Error, will return a different array:
error: always return 1
error_message: error message. ex: Could not find face data within facial image
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 identification quota for your account
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';
$header = array('Content-Type: multipart/form-data');
$path_to_image = realpath('images/test.jpg');
$fields = array('file' => '@' . $path_to_image, 'apikey' => 'your api key');
$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($result['error']==0){
    //success
    print_r($result);
}else{
    //failed
    echo("Error #" . $result['error_code'] . " " . $result['error_message']);
}

?>
import java.io.File;
import java.io.IOException;

import org.apache.commons.io.IOUtils;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.ContentType;
import org.apache.http.entity.mime.MultipartEntityBuilder;
import org.apache.http.entity.mime.content.FileBody;
import org.apache.http.entity.mime.content.StringBody;
import org.apache.http.impl.client.HttpClientBuilder;
import org.json.JSONException;
import org.json.JSONObject;

public class Upload1 {

    public static String upload() throws IllegalStateException, JSONException, IOException {


        /* load image from file
         * This snippet is using Apache HttpComponent libraries ver 4.4. You can down load it here:
         * http://mvnrepository.com/artifact/org.apache.httpcomponents/httpclient
         * http://mvnrepository.com/artifact/org.apache.httpcomponents/httpmime
         * JSON library at json.org
         */

        String urlString = "https://www.idanalyzer.com/api";
        File file = new File("your_path");
        HttpClient httpClient = HttpClientBuilder.create().build();
        HttpPost postRequest = new HttpPost(urlString);

        // build request parameters
        StringBody apiKey = new StringBody("apikey", ContentType.MULTIPART_FORM_DATA);
        FileBody fileBody = new FileBody(file, ContentType.MULTIPART_FORM_DATA);

        MultipartEntityBuilder builder = MultipartEntityBuilder.create();
        builder.addPart("apikey", apiKey);
        builder.addPart("file", fileBody);

        postRequest.setEntity(builder.build());
        HttpResponse res = null;

        // execute the request
        res = httpClient.execute(postRequest);

        JSONObject jsonObject = new JSONObject();
        if (res != null) {

            jsonObject = new JSONObject(IOUtils.toString(res.getEntity().getContent(), "UTF-8"));
            String error = jsonObject.get("error").toString();
            if (error.equals("0")) {
                // success
                System.out.println(jsonObject.getString("country"));
            } else {

                System.out.println("Error #" + jsonObject.get("error_code") + " " + jsonObject.get("error_message"));
            }
        }

        return jsonObject.toString();
    }

    public static void main(String[] args) throws IllegalStateException, JSONException, IOException {

        upload();
    }
}
import requests

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

payload = {'apikey': 'your_apikey'}
files = {'file': file}
r = requests.post("https://www.idanalyzer.com/api", data=payload, files=files)
result = r.json()
if result['error'] == 0:
    #success
    print(result['result'])
else:
    #failed
    print("Error #" + str(result['error_code']) + " " + result['error_message'])
require 'rest_client'
require 'json'
class Upload2
  #upload from url
  request = RestClient::Request.new(
      :method => :post,
      :url => 'https://www.idanalyzer.com/api',
      :payload => {
          :multipart => true,
          :url => 'your_url',
          :apikey => 'your_apikey'
      })
  response = request.execute
  json = JSON.parse(response.body)
  if(json['error'].equal? 0)
    #success
    print json['result']
  else
    #failed
    print 'Error #' + json['error_code'].to_s + ' ' + json['error_message']
  end
end
Load from a remote image
<?php

$url = 'https://www.idanalyzer.com/api';
$fields = array('url' => 'http://www.idanalyzer.com/images/photoid.jpg', 'apikey' => 'your api key');
$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($result['error']==0){
    //success
    print_r($result);
}else{
    //failed
    echo("Error #" . $result['error_code'] . " " . $result['error_message']);
}

?>
import java.io.IOException;
import org.apache.commons.io.IOUtils;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.ContentType;
import org.apache.http.entity.mime.MultipartEntityBuilder;
import org.apache.http.entity.mime.content.StringBody;
import org.apache.http.impl.client.HttpClientBuilder;
import org.json.JSONException;
import org.json.JSONObject;

public class Upload2 {

    public static String upload() throws IllegalStateException, JSONException, IOException {

        /* load image from url
         * This snippet is using Apache HttpComponent libraries ver 4.4. You can down load it here:
         * http://mvnrepository.com/artifact/org.apache.httpcomponents/httpclient
         * http://mvnrepository.com/artifact/org.apache.httpcomponents/httpmime
         * JSON library at json.org
         */

        String urlString = "https://www.idanalyzer.com/api";
        String imageURL = "your_url";
        HttpClient httpClient = HttpClientBuilder.create().build();
        HttpPost postRequest = new HttpPost(urlString);

        // build request parameters
        StringBody apiKey = new StringBody("your_apikey", ContentType.MULTIPART_FORM_DATA);
        StringBody url = new StringBody(imageURL, ContentType.MULTIPART_FORM_DATA);

        MultipartEntityBuilder builder = MultipartEntityBuilder.create();
        builder.addPart("apikey", apiKey);
        builder.addPart("url", url);

        postRequest.setEntity(builder.build());
        HttpResponse res = null;

        // execute the request
        res = httpClient.execute(postRequest);

        JSONObject jsonObject = new JSONObject();
        if (res != null) {

            jsonObject = new JSONObject(IOUtils.toString(res.getEntity().getContent(), "UTF-8"));
            String error = jsonObject.get("error").toString();
            if (error.equals("0")) {
                // success
                System.out.println(jsonObject.getString("result"));
            } else {

                System.out.println("Error #" + jsonObject.get("error_code") + " " + jsonObject.get("error_message"));
            }
        }

        return jsonObject.toString();
    }

    public static void main(String[] args) throws IllegalStateException, JSONException, IOException {

        upload();
    }
}
import requests

#load image from url
file = open('your_image_path', 'rb')
headers = {'content-type': 'multipart/form-data'}
payload = {'apikey': 'your_apikey', 'url': 'your_url'}
r = requests.post("https://www.idanalyzer.com/api", data=payload)
result = r.json()
if result['error'] == 0:
    #success
    print(result['result'])
else:
    #failed
    print("Error #" + str(result['error_code']) + " " + result['error_message'])
require 'rest_client'
require 'json'
class Upload1
  #upload from file
  request = RestClient::Request.new(
      :method => :post,
      :url => 'https://www.idanalyzer.com/api',
      :payload => {
          :multipart => true,
          :file => File.new('path to file', 'rb'),
          :apikey => 'your apikey'
      })
  response = request.execute
  json = JSON.parse(response.body)
  if(json['error'].equal? 0)
    #success
    print json['result']
  else
    #failed
    print 'Error #' + json['error_code'].to_s + ' ' + json['error_message']
  end
end