API v2
Use our API services as building blocks to create a seamless KYC and verification process for any business or industry. Get an account and get started in minutes.
Use our Atlas API services as building blocks for creating seamless KYC and verification steps for your customers. The flow can be integrated into your existing mobile and web applications. And can be customised to your exact needs. Our APIs are RESTful and all our responses are returned as JSON.
For instance, let’s say you would like your users to upload a proof of ID (e.g. PAN or Passport), a live photograph and verify the user’s location to be India. You can achieve this by calling the following APIs: The extract API to verify and extract the details from the proof of ID; The verify API to verify that the document uploaded is authentic; The liveness check API to check that the photo/video uploaded is the true likeness of the user and is real and not spoof; The face match API to match the live photograph from the photograph from the ID; and the location check API to ensure that the geo location is India.
As you can note, if you can imagine a flow, then you can build them exactly they way you want it using our APIs. In addition to the APIs, we also provide mobile SDKs for document capture and face capture and face liveness. You can refer to our SDK for more information. If you do not want any integration, you can use our no code dashboard. You can get access to the dashboard by writing to [email protected]
All Atlas APIs are authenticated using Basic Auth. Basic auth requires the following:
[YOUR_KEY_ID] and [YOUR_KEY_SECRET]
Basic auth needs an Authorization Header for each request in the base64 format. Here, base64token is a base64 encoded string of YOUR_KEY_ID:YOUR_KEY_SECRET. Please ensure that you get this format right to prevent API authentication errors.
All server-side API requests need to be authenticated using the unique API Keys provided to the user. 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.
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.
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 missing or invalid). Codes in the 5xx range indicate an error with our backend AWS servers.
All successful responses are returned with HTTP Status code 200. In case of failure, Atlas API returns a JSON error response with the parameters that detail the reason for the failure.
For V2 we are maintaining standard error format, where "type", "message", "fields" are constant for all errors. The value "fields" are mentioned for validation schema errors to say that this particular input param is wrong , for other errors like invalid_enpoint/method_incorrect, "fields" will be null
Error Codes
Error Code | Message | What to do |
200 | Success | Process as normal. |
400 | Invalid request - missing parameters. | Please check API response for missing parameters. |
401 | Unauthorised. Access denied. | Make sure you have entered your API token correctly. If issue persists then contact support. |
402 | Request Failed. | The parameters were valid but the request failed. If the issue persists then contact support. |
403 | Access forbidden. | Client does not have the necessary permissions for the resource. This is most likely because you may not have taken this service. If this is the case, please contact support. |
404 | URL not found. | The requested resource does not exist. Make sure you have formatted the URL correctly. |
405 | Invalid request - Incorrect API request method used. | GET method is not supported for this request. Make sure POST method is selected for your request. |
422 | Unprocessable Entity. | Make sure the input file is valid. |
429 | Invalid request, too many requests. | The user has sent too many requests in a given amount of time or attempting to send a duplicate request. Please check and retry. |
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. |
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. |
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. |
Error Response Parameters
Parameter | Description |
error type | The type of error that is aligned to the http error code e.g. resource not found. |
message | A descriptive message for the developer to handle the error. |
fields | "fields" are presented when there are validation schema errors. This will inform the developer of the particular input param that is wrong. For all other errors 'fields' will be null. |
Sample Error Responses
{
"error": {
"type": "resource_not_found",
"message": "The requested resource doesn't exist.",
"fields": "null"
}
}
// Example validation error with improper input. Here the field 'file_batch' has an invalid input value.
{
"error": {
"type": "validation_error",
"message": "null",
"fields": [
{
"file_batch": {
"message": "Invalid Input value. The maximum file_batch limit is 25 images."
}
}
]
}
}
The list of countries and the IDs supported for OCR can be found here. If you do not find your ID here, please contact [email protected] We have a generic OCR engine from which the key value pairs are generated and we can quickly add your desired ID document once we process it through our OCR engine.
Country | ID Name | ID Type |
India | PERMANENT ACCOUNT NUMBER | PAN |
India | PAN CORPORATE | PAN |
India | AADHAAR FRONT | ADR |
India | AADHAAR BACK | ADR |
India | PAPPORT FRONT | PPT |
India | PASSPORT BACK (INDIA) | PPT |
India | VOTER FRONT | VID |
India | VOTER BACK | VID |
India | CHEQUE (INDIA) | CHQ |
India | DRIVING LICENCE | DRV |
India | REGISTRATION CERTIFICATE | RC |
Global | PASSPORT FRONT | PPT |
Global | NATIONAL ID | NID |
Philippines | TIN | TIN |
Philippines | UMID | UMID |
Philippines | VOTER FRONT | VID |
Philippines | PASSPORT FRONT | PPT |
Philippines | DRIVING LICENCE | DRV |
Indonesia | NPWP | NPWP |
Indonesia | KTP | KTP |
Indonesia | PASSPORT FRONT | PPT |
Indonesia | DRIVING LICENCE | DRV |
Italy | NATIONAL ID | NID |
Italy | DRIVING LICENCE | DRV |
Malaysia | MYKAD | NID |
UAE | CHEQUE (UAE) | CHQ |
UAE | NATIONAL ID | NID |
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 |
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 before you attempt the above steps. You can get postman from https://www.postman.com/downloads
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” or “Run for MAC” in “Run in Postman” window.
Step 3 – Now the “API Documentation” collection will be imported to your system postman.
Step 4 – Click on the API from the Collections and go to the Authorization tab and fill in the Basic Auth credentials (Username and Password) received from FRS Labs.
Step 6 – Now click on “Send” to get a response.
Last modified 8mo ago