NAV Navbar
cURL JSON CodeSnippet

Revision History

Sl# Ver# Modified By Update Updated On
1 1.0 Tech Team - Initial Draft 29/05/2019

1. Introduction

Khosla Labs’ Veri5 Digital Platform offers Verification APIs that can be used to verify the authenticity of OVD ( Officially Verified Documents ) like PAN,VoterId,Aadhaar etc by doing a check against original data source. For example, authenticity of PAN data can be assured by doing check against Income Tax Database, Voter Id data can be verified against Election Commission Database.

The list of core APIs include :

2. Prerequisite

For a client to get access to APIs, client registration is mandatory. Khoslalabs provide two environments :

The client has to obtain the following values for the following params :

For invoking API client_code, api_key, and hash have to be mandatorily passed

Refer to Appendix A for Request Headers Information.

Refer to Appendix B for Error Codes.

Refer to Appendix C for Input Image Specifications for achieving better results.

Refer to Appendix D for how to capture good images

3. API Specification

Khosla Lab’s APIs can be consumed at exposed REST Endpoints. Request and Response Payloads are JSON documents. API communications should be made over HTTPS.

APIs are exposed to consumers in different environments like SandBox and Production. The primary purpose of the sandbox environment is to expose the APIs to consumers where they can test and do technical integrations before moving to actual production.

curl -X POST \
  https://sandbox.veri5digital.com/service/api/2.0/verifyUserIdDoc \
  -H 'Accept: */*' \
  -H 'Accept-Encoding: gzip, deflate' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'Content-Length: 301696' \
  -H 'Content-Type: application/json' \
  -H 'Host: sandbox.veri5digital.com' \
  -H 'Postman-Token: 46d52114-ebfc-46f9-a5ba-d911044b44bd,d3287cdf-e15e-4320-966f-a4bd8254aa44' \
  -H 'User-Agent: PostmanRuntime/7.18.0' \
  -H 'cache-control: no-cache' \
  -d '{
  "headers": {
    "client_code": "<<client_code>>",
    "sub_client_code": "<<client_code>>",
    "channel_code": "",
    "channel_version": "1.0.0",
    "stan": "<<unique_stan>>",
    "client_ip": "<<your_ip>>",
    "transmission_datetime": "<<current time in millis>>",
    "operation_mode": "SELF",
    "run_mode": "TRIAL",
    "actor_type": "OTHER",
    "user_handle_type": "EMAIL",
    "user_handle_value": "a@b.com",
    "location": "NA",
    "function_code": "VERIFY_PAN",
    "function_sub_code": "DOCUMENT"
  },
  "request": {
    "pan_details": {
      "pan_number": "",
      "name": "",
      "dob": "",
      "pan_type": "",
      "document": "<<id_card_image>>"
    },
    "consent": "",
    "consent_message": ""
  }
}'

3.1 API : verifyUserIdDoc [ PAN ]

This API can be used to verify the PAN document details ( PAN#, Name and Dob ) of the user against Income Tax Database.

This API supports different options as mentioned below :

Method : POST

Url : https://hostname/service/api/1.0/verifyUserIdDoc

### 3.1.1 Request Payload

{
    "headers": // Please refer Appendix A for details.
    {
      "client_code": "<your_client_code>",
      "sub_client_code": "<your_sub_client_code>",
      "channel_code": "",
      "channel_version": "",
      "stan": "<a_unique_integer>",
      "client_ip": "",
      "transmission_datetime": "",
      "operation_mode": "SELF",
      "run_mode": "",
      "actor_type": "",
      "user_handle_type": "",
      "user_handle_value": "",
      "location": "NA",
      "function_code": "<< VERIFY_PAN >>",
      "function_sub_code": << DATA | DOCUMENT>>
    },
    "request": {
            "pan_details": {
            "pan_number": "",
            "name": "",
            "dob": "dd/mm/yyyy", // Can also be any other date depending on the pan type.
            "pan_type" : "" // Please refer Table 1 below for types of PANs
            "document": "" // Base64 PAN card image if function subcode is DOCUMENT
            },
    "consent": "",
    "consent_message": ""
  }
}

Table 1: PAN Type Info

Sl# Type Description
1 IND Individual
2 HUF Hindu Un-divided Family
3 AOP Association Of Persons
4 BOI Body Of Individuals
5 COM Company
6 GOV Government
7 AJP Artificial Juridical Person
8 LOA Local Authority
9 FIR Firm
10 TST Trust 
### 3.1.2 Response Payload

API will respond with verification status as SUCCESS or FAIL depending on the authenticity of
the data.

{
  "verified_by":"Income tax e-Filing Portal",
  "verified_data":"", // Refer to Table 2 below for details.
  "verification_method":"", // VERIFY_PAN_DATA | VERIFY_PAN_DOCUMENT
  "stan":"",
  "verification_status":"<< SUCCESS | FAIL >>",
  "verified_using":"Database Check",
  “verification_code”: “”,
  "response_status":
  {
      "code":"",// 000 in case of Success
      "message":"",// Refer to Table 2 below for details.
      "status":"<< SUCCESS | FAIL >>"
  }
}

Table 2 : PAN - Verification Codes And Messages

Sl# Verification Status Verification Code verified_data [Message]
1 SUCCESS 000 Verification done Successfully and details are matching with the PAN Database.
2 FAIL 400101 PAN format is correct and PAN number is correct matching against DOB. However, Name is Incorrect.
3 FAIL 400102 PAN format is correct but PAN or Name or DOB is incorrect.
4 FAIL 400103 Invalid PAN
5 FAIL 410007 Verification Service Not Available.
6 FAIL 400099 Unknown Error Occurred.Please try after some time.

3.2 API : verifyUserIdDoc [ VoterId ]

This API can be used to verify VoterId document details against Election Commission Database.

This API supports different options as mentioned below :

Method : POST

Url : https://hostname/service/api/1.0/verifyUserIdDoc

### 3.2.1 Request Payload

{
    "headers": // Please refer Appendix A for details.  
    {
        "client_code": "<your_client_code>",
        "sub_client_code": "<your_sub_client_code>",
        "channel_code": "",
        "channel_version": "",
        "stan": "<a_unique_integer>",
        "client_ip": "",
        "transmission_datetime": "",
        "operation_mode": "SELF",
        "run_mode": "",
        "actor_type": "",
        "user_handle_type": "",
        "user_handle_value": "",
        "location": "NA",
        "function_code": "<< VERIFY_VOTER_ID >>",
        "function_sub_code": << DATA | DOCUMENT>>
    },
    "request": {
        "voter_id_details":
              {
                "epic_number": "",
                "document": ""
              },
        "consent": "",
        "consent_message": ""
        }
}

### 3.2.2 Response Payload


Incase of Voter ID data or document, API will respond with verification status as SUCCESS or FAIL depending on the data and also receive the below fields in “verified_data” .

{
    "verified_by":"National Voters Service Portal",
    "verified_data":
    {
      "assemblyConstituency":"",
      "district":"",
      "parliamentaryConstituency":"",
      "name":"",
      "pollingStation":"",
      "voterId":"",
      "state":"",
      "age":"",
      "fatherName/husbandName":""
    }
    “verification_method” :”VERIFY_VOTER_ID_DATA”,
    “stan” :””,
    “verification_status” :”SUCCESS | FAIL “,
    “verification_code” : “”,// Refer Table 3 below
    “verified_using” : “Database Check”,
    "response_status":
    {
      "code":"",// “000” in case of Success
      "message":"",
      "status":"<< SUCCESS | FAIL >>"
    }
}

Table 3 : Voter Id - Verification Codes And Messages

Sl# Verification Status Verification Code verified_data [Message]
1 SUCCESS 000 Verification done Successfully and details are matching with the Voter Database.
2 FAIL 400201 EPIC format is correct, but EPIC number is incorrect and not matching against customer details
3 FAIL 400202 Invalid EPIC
5 FAIL 410007 Verification Service Not Available.
6 FAIL 400099 Unknown Error Occurred.Please try after some time.

3.3 API : verifyUserIdDoc [ Aadhaar ]

This API can be used to verify the Aadhaar document number against the government database.

This API supports different options as mentioned below :

Method : POST

Url : https://hostname/service/api/1.0/verifyUserIdDoc

### 3.3.1 Request Payload

{
  "headers": // Please refer Appendix A for details.
          {
            "client_code": "<your_client_code>",
            "sub_client_code": "<your_sub_client_code>",
            "channel_code": "",
            "channel_version": "",
            "stan": "<a_unique_integer>",
            "client_ip": "",
            "transmission_datetime": "",
            "operation_mode": "SELF",
            "run_mode": "",
            "actor_type": "",
            "user_handle_type": "",
            "user_handle_value": "",
            "location": "NA",
            "function_code": "<< VERIFY_AADHAAR >>",
            "function_sub_code": << DATA >>
          },
"request": {
            "aadhaar_details": {
            "aadhaar_number": ""
          },
          "consent": "",
          "consent_message": ""
        }
}

### 3.3.2 Response Payload

Incase of Aadhaar data, API will respond with verification status as SUCCESS or FAIL
depending on the authenticity of the data. In case Aadhaar number is valid, you will also get
“Age Band”, “Gender”, “State” and “Mobile Number” if linked, in “verified_data”

{
    "verified_by":"UIDAI Portal",
    "response_status":{
    "code":"",
    "message":"",
    "status":"<< SUCCESS | FAIL >>"
    },
    "Verified_data":
    {
    “Age_band” : “ “,
    “Gender” : “ “,
    “State” : “”,
    “Mobile_number” : “ “
    }
    "Verification_method":"", // VERIFY_AADHAAR_DATA
    "stan":"",
    "verification_status":"<< SUCCESS | FAIL >>",
    "Verified_using":"Database Check",
    “verification_code”: “”
}

Table 4 : Verification Codes And Messages

Sl# Verification Status Verification Code verified_data [Message]
1 SUCCESS 000 Verification done Successfully and details are matching with the PAN Database.
2 FAIL 400301 Aadhaar number is not present.
3 FAIL 400302 Verification is not complete. Please Try again.
4 FAIL 400303 Not a valid Aadhaar number.
5 FAIL 400304 UIDAI website not reachable.
6 FAIL 333 Unknown Error Occurred.Please try after some time.

3.4 API : verifyGSTIN [ GST Details ]

This API can be used to fetch and verify GST details.

Method : POST

Url : https://hostname/verification-service/api/v1/verifyGSTIN

### 3.4.1  Request Payload

{
        "headers":
    {
            "client_code": "<your_client_code>",
            "sub_client_code": "<your_sub_client_code>",
            "channel_code": "",
            "channel_version": "",
            "stan": "<a_unique_integer>",
            "client_ip": "",
      "transmission_datetime": "",
            "operation_mode": "SELF",
            "run_mode": "",
            "actor_type": "",
            "user_handle_type": "",
            "user_handle_value": "",
            "location": "NA",
            "function_code": "<< VERIFY_VOTER_ID >>",
            "function_sub_code": << DATA | DOCUMENT>>
        },
        "request": {
                “request_id” : “”,
                “gstin” : “”,
                “api_key” : “”,
                “hash” :  “”    
        }
}

### 3.4.2  Response Payload
API will respond with verification status as SUCCESS or FAIL depending on the authenticity of the data.

{  
   "response_status":{  
      "code":"",
      "message":"",
      "status":"<< SUCCESS | FAIL >>"
   },
  { 
   “gstin” : “ “,
   “lgnm” : “ “,
   “stj” : “ “,
   “ctj” : “ “,
   “rgdt” : “ “,
   “ctb” : “ “,
   “dty” : “ “,
   “nba” : “ “,
    “sts” : “ “,
    “cxdt” : “ “,
      “lstupdt” : “ “,
    “stjCd” : “ “,
      “ctjCd”: “ “,
        “tradeNam” : “ “,
    “adadr” : “ “,
        “addr” : “ “,
        “bnm” : “ “,
        “st” : “ “,
        “loc”: “ “,
        “bno”: “ “,
        “stcd” : “ “,
        “flno”: “ “,
        “lt” : “ “,
        “lg” : “ “,
        “pncd” : “ “,
        “ntr” : “ “,
        “pradr” : “ “
 }
}

Table : Response Status Fields

SI# Type Description
1 gstin GSTIN of the Tax Payer
2 lgnm Legal Name of Business
3 stj State Jurisdiction
4 ctj Centre Jurisdiction
5 rgdt Date of Registration
6 ctb Constitution of Business
7 dty Taxpayer type
8 nba Nature of Business Activity
9 sts GSTN status
10 cxdt Date Of Cancellation
11 lstupdt Last Updated Date
12 stjCd State Jurisdiction Code
13 ctjCd Centre Jurisdiction Code
14 tradeNam Trade Name
15 adadr Additional Place of Business Fields
16 addr Additional place of business address
17 bnm Building Name
18 st Street
19 loc Location
20 bno Door Number
21 stcd state name
22 flno floor nbr
23 lt latitude
24 lg longitude
25 pncd pin code
26 ntr Nature of Additional place of business
27 pradr Principal Place of Business Address

Table 5 :VerifyGSTIn - Verification Codes And Messages

Sl# Verification Status Verification Code verified_data [Message]
1 SUCCESS 000 Verification done Successfully.
2 FAIL 400401 Hash Validation Failed
3 FAIL 400402 Sorry, You have exceeded the consumption limit. Please contact customer.support@aadhaarbridge.com
4 FAIL 400403 request_id is mandatory
5 FAIL 400404 gstin field is mandatory
6 FAIL 400405 api_key is mandatory
7 FAIL 400406 hash is mandatory

Refer Appendix E for hash calculation.

Appendix A: Request Header Field Details

Every APIs Request Payload has a custom “header” field, whose details are given below. Fields marked ( * ) are mandatory.

S.NO Field Name Mandatory Description Example
1 client_code* A unique code assigned to a client while onboarding. client123
2 sub_client_code* Unique code assigned to a sub client of a hosted client.In case not applicable, an EMPTY (“”) string can be passed. client123
3 actor_type* Type of person who is making the request.If not relevant, "DEFAULT" can also be used. CUSTOMER/DEFAULT
4 channel_code* Channel code used by the client to initiate the request. ANDROID_SDK
5 stan* System Trace Number - A unique number generated per request by the client. It is used to uniquely identify a request from a client. It can be used for troubleshooting. 98321892319
6 user_handle_type* Indicates the type of the user identifier, who has initiated the request. Eg: UUID, MSISDN, EMAIL. If not relevant, "DEFAULT" can also be used. EMAIL
7 user_handle_value* Value of user_handle_type.If not relevant, "DEFAULT" can also be used. a@b.com/DEFAULT
8 location Specifies the geo location of the device that initiated the request.
9 transmission_datetime* Time in System Milli Seconds at which the request was initiated by the client. 155325508029
10 run_mode* TRIAL - Indicates need for mock run of the transaction. No transaction posting will happen. REAL - Indicates the actual transaction posting request. If not relevant, "DEFAULT" can also be used. DEFAULT/TRIAL/REAL/RETRY
11 client_ip IP Address of the client device.In case not applicable, an EMPTY ( "") string can be passed.
12 operation_mode* The way in which the request is executed. SELF - aadhaar holder doing the transaction. ASSISTED - where auth/ekyc is done in operator assisted mode. SYSTEM- where transaction is automated by system (batch processes). If not relevant, "DEFAULT" can also be used. DEFAULT/SELF/ASSISTED/SYSTEM
13 channel_version* The version of the channel application like ANDROID_SDK. 3.1.7
14 function_code* DEFAULT: Indicates default behavior for this API DEFAULT
15 function_sub_code DEFAULT: Indicates default behavior for this API DEFAULT
16 request_id* Client generated Id for referencing the transaction uniquely. requestid123
17 hash* Hash to be calculated by the client to verify the integrity of the request. Please refer APPENDIX B to see how to generate the hash.
18 api_key* api_key shared with the client during onboarding. samplekey123

Appendix B : Error Codes

Code Scenario Message
380024 General user_id is mandatory
380025 General hash is mandatory
380026 General api_key is mandatory
380048 General Invalid api_key or client_code
380048 General Invalid api_key or client_code
380091 General Hash validation failed
380076 General No such user-id exists
333 General Unexpected Error Occurred
410003 verifyUserIdDoc Invalid name.
410004 verifyUserIdDoc Invalid DOB Format. Please use dd/MM/YYYY format.
410005 verifyUserIdDoc Invalid PAN format.
410006 verifyUserIdDoc Data extraction from the PAN card was unsuccessful.
410008 verifyUserIdDoc Name is mandatory.
410009 verifyUserIdDoc Date of Birth is mandatory.
410010 verifyUserIdDoc PAN Number is mandatory.
410011 verifyUserIdDoc Document is mandatory.
410012 verifyUserIdDoc Operation Code Not Valid.
410013 verifyUserIdDoc Epic number is mandatory
410014 verifyUserIdDoc Epic number format is invalid.

Appendix C: Input Image Specification

For better results, it is recommended to ensure that Input Image complies to the following specifications :

Appendix D: Important things to consider before uploading images

Appendix E: Hash Generation

It is essential that there is a definitive protocol to verify the integrity of all the communication between Khosla Labs and Client.Hence for every request coming to KL Platform, client have to supply a hash which we will use as the first step of verification.

In return, all responses will also contain hash supplied by KL. You should not entertain any request at your callbackUrl if the hash does not match.

Hash Sequence is specified as follows(no space, no commas, no single/double quotes). Hash sequence is defined for each request and response.

Example(for _init request), If your
client_code=INFO9378,
api_key=abc,
requestId=abcd,
salt=abc,
gstin=29AAECK9415C1ZJ
then
Hash-Sequence=INFO9378|abcd|abc|abc|29AAECK9415C1ZJ
hash =SHA-256(Hash-Sequence)
hash=e3f10f1787428a75e5f0c9331c3bacde36df54e855744a3ccc1f0ff9c7b518fe

For validation:

sample link for calculating hash : https://www.tools4noobs.com/online_tools/hash/

cURL JSON CodeSnippet