API v1.3 (deprecated)

Note that this is the older API version and has been deprecated. Please use API v2.

The Basics

Authentication

All server-side API requests need to be authenticated using the unique API Keys provided to the user. The API key is a combination of Key ID (as username) and Key Secret (as password). The keys must be stored securely as it carries many privileges and must not be shared in publicly accessible areas such as client-side code. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

You should use a Content-Type: application/json header with all PUT and POST requests except when uploading documents or photos. For these requests, use a Content-Type: multipart/form-data header. API credentials must be included in the header of all requests made to the API. A sample header format and its details are given below.

Environments

We provide two environments. A sandbox (pre-prod) environment for clients to integrate and test the APIs and a production environment for going live with your integration.

Note that all of the examples in this documentation points to the production environment. Your pre-production keys will not work in production and vice versa, so please take care when using the environment correctly.

Header

Authorization consists of the key_id, api_key and the timestamp

Key_ID: This is unique ID issued to identify the client application.

Key_Secret: A unique string only known to the creator of the client ID.

Timestamp: Timestamp in yyyyMMddHHmmssSSS format.

API_Key is the encrypted value of key_id, key_secret and timestamp. You can get the sample Java code for AES256 encryption algorithm for the api_key from our git page.

Request_ID is any unique ID for the request. You can use a unique customer_id and timestamp in milliseconds to make each request unique. No special characters are allowed as part of the request_id.

Errors

Atlas uses conventional HTTP response codes to indicate the success or failure of an API request.

In general: codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with Atlas servers (rare cases). The full list of error codes are listed below.

Error Codes

Error Response Parameters

Sample Error Response

{
    "status": "failed",
    "response_timestamp": "1595488026806",
    "data": null,
    "error": {
        "code": "500",
        "message": "Internal server error."
    }
}

Document Types

The document ID types are given below. The full list of countries and the IDs supported can be found here.

Country Codes

The supported country codes to be passed as parameters are outlined below.

Test in Postman

Postman is a simple application to test the APIs without having to write a line of code. This is pretty useful to have our APIs tested for your business needs before beginning your integration work. You can follow these steps to test our APIs in about 10 minutes.

Please ensure that you have Postman installed in your system from https://www.postman.com/downloads

For this example, let’s say that you would like to test our OCR API to extract text data from a Passport.

Step 1 – Once you have installed Postman, you can download our API collections by clicking on “Run in Postman” button from our API page.

Step 2 – Click on “Postman for Windows” in “Run in…” window.

Step 3 – Now the “API Documentation” collection will be imported to your system postman.

Step 4 – To create environment and variables, click on “Create New” and select “Environment”.

Step 5 – In “Manage Environments”, enter Environment Name (e.g. Atlas), and create variables and set your allocated values for KEY_ID, KEY_SECRET, AUTHORIZATION and REQUEST_ID and then click on “Update”.

Please read the introduction section of the documentation to understand the variables mentioned here and how to get your own credentials to get started.

Step 6 – Now you have to pass values in “Params” and “Body”. These are the values that are needed to complete the data extraction task by the API.

Step 7 – Pre-request script is added in each API request to generate “Authorization header” using API keys (KEY_ID, KEY_SECRET).

To generate the authorization header to use in postman, you can use this: https://apps.atlaskyc.com/atlas/api/auth/get_auth?key_id=your key ID&key_secret=your key secret. Please note that you will need to generate the authorization header for each individual API call you make.

Step 8 – Now click on “Send” to get response after selecting appropriate environment (e.g. Atlas).

Core Resources

Text Recognition

Powerful vision APIs and SDKs to extract data from ID cards and other supported documents.

Extract Data (OCR)

Extract data from globally supported documents (singled sided and multi-sided).

The Basics

Authentication

Environments

Header

Errors

Document Types

Country Codes

Test in Postman

Core Resources

Text Recognition

Extract Data (OCR)

Face Recognition

Aadhaar Services

Video Verification

Core features of Video Verification APIs

Video Validation

Video KYC - Live Video Call

Post Issuance Verification (PIVC)

Core features of PIVC APIs

ID Verification