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 support@frslabs.com.

Authentication

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.

Environment

We provide a production environment with trial access. You can use the trial API key to integrate and test the APIs and use the production key for going live with your integration.

Note that your trial keys will not work once you go live, so please ensure you use the correct keys in the production environment. Trial keys are valid for short durations for testing. Production keys by default are valid for a year.

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 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 support@frslabs.com.

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."
                            }
                        }
                    ]
                }
            }

Document Types

The list of countries and the IDs supported for OCR can be found here. If you do not find your ID here, please contact support@frslabs.com. 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

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 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 5 – Now you have to pass values in “Params” and “Body” referring to the API documentation.

Step 6 – Now click on “Send” to get a response.

Core Resources

Last updated