API

Use our API services as building blocks to create a seamless KYC and verification process for any business or industry.

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.

Key

Description

Authorization

Hashed string of api_key with timestamp using AES256 key_id=abeb3372xxxxaf530,api_key= (KEY_ID|KEY_SECRET|TIMESTAMP),timestamp=yyyyMMddHHmmssSSS

request_id

Any Unique Reference ID or Time in milliseconds format (e.g 1588695375434) to identify each request uniquely.

Authorization consists of the key_id, api_key and the timestamp

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

Kye_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.

Response

Status Code: 200 OK Content-Type: application/json

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.

Production base URL

Pre-production base URL

https://api.atlaskyc.com/prod

https://api.atlaskyc.com/preprod

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.

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 Code

Message

What to do

200

Success

400

Invalid request - missing parameters.

Please,check API response for missing parameters.

401

Access denied.

Make sure you have entered your API token correctly.If issue persists then contact support at support@frslabs.com.

403

Access forbidden.

Client does not have the necessary permissions for the resource.Please contact support at support@frslabs.com

404

URL not found.

Make sure you have formatted the url correctly.

405

Invalid request-WRONG API REQUEST METHOD TYPE

GET method is not supported for this request. Make sure POST method is selected for your request.

408

Request Timeout error.

Requests are not connected to atlas services. Please contact support at support@frslabs.com

413

Request entity too large.

Make sure, size limit of your request does not exceed 100 mb.if issue persists then contact support at support@frslabs.com.

414

Request URL too large.

URL for your request is longer than the server is willing to interpret. Please check URL.

415

Invalid request, unsupported media type.

Make sure format of your request is as per defined resource's content-type or content-encoding headers.

429

Invalid request, too many requests.

The user has sent too many requests in a given amount of time.Please retry after specified time.

500

Internal server error.

The server encountered an error. Please, try again.If issue persists then contact support at support@frslabs.com.

502

Bad gateway error.

The server has received an invalid response. If issue persists then contact support at support@frslabs.com.

503

Service unavailable.

The server is currently unable to handle your request due to a temporary overloading or maintenance of the server. Please, try again.If issue persists then contact support at support@frslabs.com.

505

HTTP version not supported.

The server can't handle the http version used in the request. We support http 2.0 and http 1.0 version. Please, contact support at support@frslabs.com.

Error Response Parameters

Parameter

Description

code

Data type: String. Code of the error e.g. 400

message

A human-readable message giving more details about the error

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.

ID

Abbreviation

Type

PPT

Passport

String

PAN

Permanent Account Number

String

NID

National Identity Card

String

DRV

Driving Licence

String

SSN

Social Security Number

String

VID

Voter Identity

String

ADR

Aadhaar Card (India)

String

RC

Registration Card

String

TIN

Tax Identification Number

String

UMID

Unified Multi-Purpose ID

String

Country Codes

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

Country

Code

Australia

AUS

Austria

AUT

Bahrain

BHR

Belgium

BEL

Canada

CAN

Denmark

DNK

Egypt

EGY

Finland

FIN

France

FRA

Germany

DEU

Greece

GRC

Greenland

GRL

Hungary

HUN

Iceland

ISL

India

IND

Indonesia

IDN

Ireland

IRL

Israel

ISR

Italy

ITA

Japan

JPN

Malaysia

MYS

Philippines

PHL

Poland

POL

Portugal

PRT

United Arab Emirates

ARE

United Kingdom

GBR

United States

USA

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 – Prerequest 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

Text recognition uses advanced deep learning technologies for accurate and fast ID scanning and OCR. OCR is available for a variety of government issued documents and countries. You can view the full list of supported documents here.

Core features of Text Recognition APIs

View all Text Recognition APIs

Face Recognition

This service extracts the key features, landmarks and quality aspects of a face image. The face features can then be used for a wide variety of uses cases such as customer verification, customer identification and comparison between images.

Core features of Face Verification APIs

  • Face Comparison - Compare two faces to see how likely they look alike

  • Face Verification - Verify or Authenticate a face against a face template already on file. Mostly used for authentication or attendance purposes where the face is enrolled once and verified multiple times.

  • Face Identification - Identify a face from several faces to find a match.

  • Face Quality - This is useful to analyse the input images for quality issues before they are used at scale for critical functions (e.g. authentication) to remove bias from your matches.

  • Face Crop - Crop face image from ID or application documents.

View all Face Recognition APIs

Aadhaar Services

Aadhaar is the unique identity document issued to every Indian citizen. Aadhaar services includes Aadhaar Offline verification, Aadhaar Masking as per multiple regulations and Aadhaar eSign.

Core features of Aadhaar Services APIs

  • Aadhaar Offline - A unique way to verify Aadhaar in offline mode, instantly and securely.

  • Aadhaar Masking - Redact the first 8 digits of Aadhaar from Aadhaar images.

  • Aadhaar eSign - Aadhaar eSign facilitates an Aadhaar holder to digitally sign a document.

View all Aadhaar Services APIs

Video Verification

As the name suggests video verification refers to verifying the identity of the User through a video. The verification can be unassisted, whereby all of the steps are carried out by the User for verification. Assisted verification is done through a live video call with a Bank official. Video verification removes the need for face to face meetings and can vastly reduce the cost of verification and improve customer experience.

Core features of Video Verification APIs

  • Video Capture - Capture and compress a video as part of your onboarding face verification.

  • Video Liveness - Verify the liveness of the user through a video and spoken token.

  • Video Face Match - Match the face in a video against a face on file for verification.

  • Video Face Crop - Crop a perfect face image from a video. Useful to get a selfie out of a video.

View all Video Verification APIs

Post Issuance Verification

Following pre-approval of many of the services, in particular for insurance products, a pre or post issuance verification call (PIVC) is essential to confirm the details directly with the customer and remain compliant with current regulations. PIVC services provide a simple way to initiate such PIVC calls to customer and customer completing the verification over a recorded video call.

Core features of PIVC APIs

View all PIVC APIs

ID Verification

ID verification refers to verifying the legitimacy of the details in the ID document presented by the customer for verification. It doesn’t check for document tampering but rather that the details in the ID has a legitimate match against the issuing authority.

Core features of ID Verification APIs

  • Verify Bank Account - Penny Drop verification to verify a Bank Account (Indian Customers only).

  • Verify PAN - Verify PAN card against issuing authority (Indian Customers only).

  • Verify Voter ID - Verify Voter ID against issuing authority (Indian Customers only).

  • Verify Driving License - Verify Driving License against issuing authority (Indian Customers only).

  • Verify GSTN - Verify GSTN against issuing authority to verify a business (Indian Customers only).

View ID Verification APIs