NAV Navbar
cURL JSON CodeSnippet

1. Introduction

Veri5’ eSign Platform offers APIs that can be used to esign documents using Aadhaar based esign platform.

2. Prerequisite

For a client to get access to APIs, client registration is mandatory. Veri5Digital provides two environments :

It’s recommended to have the client first do technical integration of the API in the Sandbox environment, followed by testing and certification.

Post certification in Sandbox Environment, for actual production purposes, clients should move to Production Environment.

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

Client Code (client_code), that uniquely identifies the client that is onboarded with the Veri5. Salt (salt), that uniquely identifies the client that is onboarded with the Veri5 and will be used to generate hash for validation.

For invoking APIs, client_code has to be mandatorily passed.

3. API Specification

eSign’s APIs can be consumed at exposed REST Endpoints. Request and Response Payloads are JSON documents or GET requests. 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.

API Domain Purpose
uploadDocument Veri5 Upload document for eSign.
_initiateEsign Veri5 Initiate the eSign process.
clientResponseUrl Client Client needs to provide. After successfully e-signing the user will be redirected to this url.
_downloadDocument Veri5 The signed document can be downloaded using this API

4.1 API : uploadDocument [ POST ]

InputType : Multipart Form Request

Method : POST

URL : https:///esign/uploadDocument

_upload Request Details

Type Size Value Requirement Requirement
ENC String 1 Y/N Mandatory when data is encrypted

Refer below table for the request body parameters. Client application should POST these parameters as a FORM Submit Action.

Table : _upload API Request Body Parameters

Fields Type Size Value Requirement
client_code AlphaNumeric 10 Will be provided on onboarding Mandatory
client_request_id Alphanumeric 45 A unique request Id for each case Mandatory
doc_no Numeric 1 The document index No incase of multiple docs Optional
doc_type String pdf Mandatory
reason String 64 Minimum size should be 10 Mandatory
igner_name String 32 Optional
filename AlphaNumeric 32 Mandatory
rectangle String NA Mandatory
page_no AlphaNumeric NA Single Page: Page no, Multiple Pages: Page nos, separated by <,>, All pages: ’all’ Mandatory
hash Alphanumeric NA Digestmethod:-SHA256, Value: SHA256(salt client_request_id
file File NA Pdf file. Should not have embedded JS. Mandatory

4.1.1 Sample Request Payload

Below given code snippet demonstrates how to invoke the Veri5 Digital eSign SDK from a form in clients application.

<form action="" method="post"
<input type="text" name="client_code" value="<<your sa code>>">
<input type="text" name="<<client_request_id>>" >
<input type="text" name="<<doc_no>>" >
<input type="text" name="<<doc_type>>" >
<input type="text" name="<<reason>>">
<input type="text" name="<<signer_name>>" >
<input type="text" name="<<signer_location>>" >
<input type="text" name="<<filename>>" >
<input type="text" name="<<rectangle>>" >
<input type="text" name="<<page_no>>" >
<input type="text" name="<<hash>>" >
<input type="file" name="<<file>>" >
<button type="submit">Submit</button>

Rectangle Field Details

This defines the coordinates of the rectangular box where eSign will appear in the document.

Rectangle(50, 400, 200, 500) <==> (x1, y1, x2, y2)

Points to Note

4.1.2 _upload Response Details

Response structure is as given below, where fields

success : Indicates the status of the API execution. Possible values are true or false.

errorCode : Contains the error code whose details are given in below table.

message : Message corresponding to the error code.

Note : Error Code is Empty String in case of success is true.

  "code":"<< 000 | 001 >>", 
  “responseData”:"only on success"

4.1.3 Response Codes And Messages

Status Code message
SUCCESS 000 Uploaded Document
FAIL 001 Reason for failure

4.2 API : _initiateEsign

Once the document is successfully uploaded, this API will be used to initiate the eSign process. On success, the user will be redirected to the consent page.

Method : POST

URl : https://hostname/esign/_initiateEsign?id=$id&h=$hash

type: document/Redirect

Fields Type Size Value Requirement
id AlphaNumeric NA responseData received in success response of ‘uploadDocument’ api call Mandatory
hash Alphanumeric NA Digestmethod: SHA256, Value:SHA256(hash_sequence) Mandatory

Note: alt will be shared when the client is on boarded.

hash_sequence = id|salt

4.2.1 Response Details

4.3 API : Client Response URL(Client Redirection Portal)

As per the flow after aadhaar verification from ESP page the user will be redirected to client response url.

Type : document/Redirect

URL : https://<clientResponseUrl>/<path>?esign_status=/<success/fail>&id=<id>&h=<hash>

Params Type size value Requirement
id AlphaNumeric NA This id will be used to request _downloadDocument for downloading the document Mandatory
hash Alphanumeric NA This can used by the client to verify the redirection Digestmethod:-SHA256, Value:SHA256(hash_sequence) Mandatory
esign_status String NA success/fail Mandatory

hash_sequence = <id>|<salt>

4.4 API : _downloadDocument[ POST ]

This API is used to download the signed document.

Url : https://<hostname>/esign/_downloadDocument InputType : JSON

Params Type size value Requirement
id AlphaNumeric NA The id received in client response url Mandatory
hash Alphanumeric NA This can used by the client to verify the redirection Digestmethod:-SHA256, Value:SHA256(hash_sequence) Mandatory

hash_sequence = <id>|<salt>

Request Payload

"hash":"`<hash value>`"

Request Payload

           "code":"<< 000 | 001 >>", 
           "responseData":         //Only on success response
"fileContent":<Base64 encoded String of signed file>,
                    "fileName":<Original File Name>,

Response Codes And Messages

Status Code message
SUCCESS 000 Download Success
FAIL 001 Reason for failure

Appendix A: Hash generation

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

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

For validation:

Sample Code Snippet uploadDocument Request Hash Calculation

Function to calculate Hash based on the input hash sequence parameters.Below given function depicts hash calculation for _upload ( Document Upload ) Api.

private String calculateHash(String salt, String clientRequestId, String filename, String pageNo, String docType) throws NoSuchAlgorithmException {
  MessageDigest digest;
  digest = MessageDigest.getInstance("SHA-256");         
  if (digest != null) {
      byte[] hash = digest.digest((salt + "|" + client_request_id + "|" + filename + "|" + page_no + "|" + doc_type).getBytes());
      return bytesToHex(hash);
  return null;

private final static char[] hexArray = "0123456789ABCDEF".toCharArray();
public static String bytesToHex(byte[] bytes) {
  char[] hexChars = new char[bytes.length * 2];
  for (int j = 0; j < bytes.length; j++) {
  int v = bytes[j] & 0xFF;
  hexChars[j * 2] = hexArray[v >>> 4];
  hexChars[j * 2 + 1] = hexArray[v & 0x0F];
  return new String(hexChars);