Setu
Aadhaar eSign

Integration guide

API Playground

Aadhaar eSign integration

eSign APIs can be used to collect legally binding signatures on a document, for upto 6 signers.

Here’s a quick run through of the APIs—

  1. Upload document—Upload a PDF document to be signed.
  2. Create signature request—Create a signature request with defined signer(s) and a redirect url. You get an id in response, which you can use to track the signature request.
  3. Get status of signature request—Get details against a signature request by passing the signature request id.
  4. Download document—Download a signed document by passing the signature request id.

If using flexible esign, you need to first upload the signing config and then the flow of API calls remains the same as above. Uploading signing config is a one time task, if config does not change.

You can also delete a signature request—if required—by passing the request id.

Additionally, here are the URLs you would need for these APIs—

  • Sandbox—https://dg-sandbox.setu.co
  • Production—https://dg.setu.co
  • Headers—Contact Setu for providing the credentials required to successfully call Setu APIs. This contains:
    • x-client-id
    • x-client-secret
    • x-product-instance-id

Upload document

Call this API to upload the document that has to be signed. The document and the document name would be passed as a multipart/form-data upload of the files and name parameters respectively.

201

SUCCESS Setu has processed your request successfully.

Request
POST /api/documents 
 
payload= { 
    "name": "name_your_file" 
 } 
 
files= [ 
  ("document", ("sample.pdf", open("/Users/path/Sample.pdf", "rb"), "application/pdf")) 
]
Response

You will get a unique id which is the documentId from Setu for usage in signature request creation.

{
  "id": "67e0ca30-49e4-4883-86f9-3762f0e6798c", 
  "name": "name_your_file" 
}

Create signature request

Create a signature request with defined signer(s) and a redirect url. You get an id in response, which you can use to track the signature request.

In case you want to validate a customer’s name and year of birth, pass the values for displayName and birthYear in create signature request. If there is a mismatch in name or birth year (based on data from Aadhaar OTP based verification), we will display an error and the customer will not be able to sign the document.

Request to enable validation of customer name and birth year by writing to us at Setu Support. Also specify threshold of fuzzy match for name.

Here is a quick description of the values required to call this API—

  • documentId the unique id of the document, which you get from the Upload document API response.
  • signers can be used to specify details of up to 25 signers for a document, each with an identifier, displayName and birthYear (optional).
  • Additionally, the signature object can be used to specify page numbers with onPages and position for signatures to be collected on the document’s UI, uniquely for each signer. By default, the height and width of the signature, are set to 60 and 180 pixels respectively. If only height OR width is provided, the other one is automatically calculated with a default height : width ratio of 1 : 3.

We strongly recommend 60 and 180 for height and width values. In case you choose custom values for height and width, we recommend 1:3 ratio to avoid signature distortion.

Usage of the redirect URL

You have to provide a redirectUrl in the request, which has to be a valid publicly hosted URL—the signer gets redirected to this URL after going through Setu’s eSign screens.

It will also be used by Setu to send back relevant information about a signer. By default Setu includes the signature request id, the signer’sidentifier and success flag of the signature attempt.

  • For a failed signature, we will send back—(redirectUrl)?id={signature_request.id}&success={false}&signerIdentifier={signer.id}&errCode={code}&errorMessage={message}
  • For a successful signature—(redirect_url)?id={signature_request.id}&success={true}&signerIdentifier={signer.id}

You can also add custom query params such as session id from your end. You would append this to the provided URL, like so— (redirectUrl)?sessionId=XYZ

Create Signature request with configID

Create signature request can also be created by using configId in case of flexible signature placement. Please refer to the 201 with configId tab below for request and response sample.

201

Normal esign (without configID)

Flexi esign (with configID)

Get signature request status

Call this API to get the details of a signature request by passing its unique signature request id.

The following table lists the possible values of status of the signature request and corresponding possible values of the status of signer(s)—

Signature request statusPossible signer statuses
sign_initiated—No signer has signed the document yetpending
sign_pending—At least one of the signers has signed the documentpending | signed
sign_in_progress—When one of the signers is signing the document. No other signer will be able to sign at this stage.pending | in_progress | signed
sign_complete—All signers have completed signing the documentsigned

200

Type 1

Type 2

404

NOT FOUND When the provided signature id is incorrect or deleted.

Request
GET /api/signature/:id
Response
{ 
                    "error": { 
                        "code": "signature_request_not_found", 
                        "detail": "Signature Request Not Found.", 
                        "traceId": ""  // unique identifier for this error 
                    } 
                }

Download signed document

Call this API to download a signed document.

200

SUCCESS Signature request is in sign_complete state and available for download.

Request

Pass the signature request id as a URL parameter

GET  /api/signature/:id/download/
Response
 { 
                    "downloadUrl": "https://s3.amazonaws.com/downloadfolderpath",  
                    "id": "cb80bfb4-d163-426e-ad57-1fd8889e62d4", //signature request id 
                    "validUpto": "2021-10-28T14:09:14+05:30" //validity of downloadUrl in ISO 8601 timestamp 
                  }

400

BAD REQUEST Signature request is not yet completed.

Request

Pass the signature request id as a URL parameter

GET  /api/signature/:id/download/
Response
{ 
                    "error": { 
                        "code": "document_not_signed", 
                        "detail": "Only signed documents can be downloaded.", 
                        "traceId": ""  // unique identifier for this error 
                    } 
                }

404

NOT FOUND The signed document is either deleted or an incorrect signature request id has been provided.

Request

Pass the signature request id as a URL parameter

GET  /api/signature/:id/download/
Response
{ 
                  "error": { 
                    "code": "document_not_found", 
                    "detail": "Document not found.", 
                    "traceId": "" // unique identifier for this error 
                  } 
                }

Delete a signature request

Call this API to delete a signature request. You can choose to do so once you have downloaded the signed document, or you may even delete it before.

Deleting a signature request also deletes the document associated with it.

204

SUCCESS You will get a success 204 status post deletion.

Request

Pass the signature request id as a URL parameter

POST /api/signature/:id/delete/

404

NOT FOUND When the provided signature request id is incorrect.

Request

Pass the signature request id as a URL parameter

POST /api/signature/:id/delete/
Response
{ 
                    "error": { 
                        "code": "signature_request_not_found", 
                        "detail": "Signature Request Not Found.", 
                        "traceId": ""  // unique identifier for this error 
                    } 
                }

Overview

Aadhaar eSign overview

eStamp overview

Setu eStamp lets you acquire offline eStamps, attach them to documents and collect Aadhaar-based eSignatures with government stamp duty applied.

On this page

Aadhaar eSign integrationUpload document201Create signature requestUsage of the redirect URLCreate Signature request with configID201Get signature request status200404Download signed document200400404Delete a signature request204404