Use our API services as building blocks to create a seamless KYC and verification process for any business or industry. Note that this is the older API version and you must use API v2.
The Basics
Simple steps to integrate our APIs
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
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.
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.
Response
Status Code: 200 OK
Content-Type: application/json
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 [email protected].
403
Access forbidden.
Client does not have the necessary permissions for the resource. Please contact support at [email protected]
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 [email protected]
413
Request entity too large.
Make sure, size limit of your request does not exceed 100 MB. If issue persists then contact support at [email protected].
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 [email protected].
502
Bad gateway error.
The server has received an invalid response. If issue persists then contact support at [email protected].
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 [email protected].
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 [email protected].
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 – 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).
Aside, we have also developed custom OCR for specific client needs using our pre-trained AI engine. Please reach out to us if you have a specific format that needs to be supported through our OCR engine.
Convert Documents
Convert multiple input file formats (e.g. jpg, tiff, pdf, png, bmp, webp etc) to a standard out format (e.g. PDF or JPG).
View API (coming soon)
Compress Documents
Compress your files to save valuable space in your document management systems for more digital documents to occupy the same unit space.
View API (coming soon)
Split Documents
Unlock the potential of greater analytics from input KYC documents by splitting the PDF file into its constituent parts (e.g. Single customer PDF file will split into PAN, Aadhaar, Payslip, Bank Statement, Application, Photograph and so on).
View API (coming soon)
Classify Document
Minimise document upload errors by classifying the documents correctly. For instance, verify that a PAN image or an Aadhaar Front image has been uploaded by the customer during your digital onboarding journey (mobile and web).
Signature Crop API allows you to crop a signature image from a document. This is most helpful when you are not meeting the customer face to face but will need to collect the signature offline or through a video. Once the signature document is capture, this API can crop the signature from the uploaded document. The supported file formats are JPG and PNG.
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.
Face Quality
Takes an input image and assesses for multiple input quality parameters including the presence of blur, reflection, sharpness, exposure, orientation (pitch, yaw, roll), eye and mouth positions and returns a quality score.
Takes two input images, detects and crops the face images, extracts the face features from the face landmarks, compares both the images and provides a match score.
Takes the input image, detects and crops the face image, extracts the face features from the face landmarks and compares the image with all the image templates already stored in your database.
Takes an input image or a video and identifies the face image and crops the image. This is useful for cropping face images from ID cards for face comparison against selfie of video face.
Aadhaar is the unique identity document issued to Indian citizens. Aadhaar services includes Aadhaar OCR, Aadhaar Offline verification, Aadhaar image and video masking and Aadhaar eSign.
Aadhaar OCR
Extracts data from multiple Aadhaar card versions issued by UIDAI. Extracts data accurately from both sides of the original Aadhaar image.
Extracts data from multiple QR codes (QR encrypted, QR plain, and QR with photo) versions issued by UIDAI. Extracts data accurately from original Aadhaar images. This is part of our OCR API which can be invoked to extract data from Aadhaar QR.
Allows the customer to download the Aadhaar Offline XML file seamlessly and verify the digital signature and extract the data and photograph from the XML file.
Aadhaar masking refers to redacting the first 8 digits of the Aadhaar Number in the Aadhaar card. The masking caters to short form and full form Aadhaar images and segregates them into multiple output folders. Note that this function is also available to run as a batch for your legacy images.
Allows for customers to digitally sign documents using Aadhaar and OTP seamlessly. We are an approved ASP and the Aadhaar signed documents are accepted on par with physical signatures in a court of law. Note that this function is also available as part of our no-code dashboard.
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 Validation
With a single input video captured of a customer, you can perform the following operations to validate and verify the person in the video.
Crop face from the video recording
Match multiple faces within the video
Match face cropped from ID document against face in video
The video verification is completed by the customer with the assistance of a trained agent over a live video call. You can use this API to initiate a video call link that can then be used by the customer and the Agent to come on the call.
Note that the video call can also be initiated from our no-code dashboard. A simple web link will be sent to the customer to take the call. You can learn more about the flow here.
There are webhooks and additional APIs that you can invoke to check the status of a video call and download the video and the call details once the video is completed. Alternatively, you can login to our dashboard to view the complete video KYC record.
Post Issuance Verification (PIVC)
Following pre-approval of many of the services, in particular for insurance products, a pre or post issuance verification call (PIVC or PCVC) 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.
ID verification refers to verifying the legitimacy of the details in the ID document presented by the customer against the issuing authority of those documents. It doesn’t check for document tampering but rather that the details in the ID has a legitimate match against the issuing authority. We offer the following verification services.
Bank Verification (Penny Drop)
Verifies the legitimacy of the Bank Account (for all Bank Accounts in India) by dropping INR 1 into the beneficiary’s Bank Account. The verified Bank Account will return the beneficiary name. Note that this function is also available as part of our no-code dashboard.
Verifies the legitimacy of the Permanent Account Number (PAN) against the issuing authority (Income Tax Department of India). Note that this function is also available as part of our no-code dashboard.
Verifies the legitimacy of the Goods and Services Tax Number (GST) against the issuing authority (GSTIN). Verified GSTIN returns the full business details of the GST number. Note that this function is also available as part of our no-code dashboard.
Verifies the legitimacy of the Voter ID (EPIC – Electors Photo ID Card) against the issuing authority. Note that this function is also available as part of our no-code dashboard.
Verifies the legitimacy of the Driving License against the issuing authority (Parivaahan). Verified Driving Licence returns the demographic details and the photo of the driver. Note that this function is also available as part of our no-code dashboard.