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.

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

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 multi-part form upload of the files and name parameters respectively.


Setu has processed your request successfully.


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

Response#

You will get a unique id from Setu to track this document.

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

Create signature request#

Call this API to create a new signature request for a document.

You have to provide the following details—

  • documentId the unique id of the document, which you get from the Upload document API response.
  • name, the name of the document.
  • signers can be used to specify details of up to 6 signers for a document, each with an identifier and name. Additionally, the signature object can be used to specify labels or positions for signatures to be collected on the document’s UI, uniquely for each signer.

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}&signerId={signer.id}&errorCode={code}&success={false}&errorMsg={message}
  • For a successful signature—<redirect_url>?id={signature_request.id}&success={true}&signerId={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



Setu has processed your request successfully.


Request#
POST /api/signature
{
"documentId": "67e0ca30-49e4-4883-86f9-3762f0e6798c",
"name": "Loan agreement",
"signers": [
{
"identifier": "9876543210",
"name": "John Doe",
"signature": {
"appearance": {
"label": "To be signed by John"
},
"height": 60,
"onPages": [
"1"
],
"position": "bottom-left", // ENUM values—bottom-right | top-right | top-left
"width": 180
}
}
],
"redirectUrl": "your-redirect-url.com?other_keys=youcandefinehere"
}

Response#

You will get a unique id from Setu—to track this signature request. Additionally, you will get an array of signers, each with their own status.

{
"documentId": "67e0ca30-49e4-4883-86f9-3762f0e6798c",
"id": "cb80bfb4-d163-426e-ad57-1fd8889e62d4",
"name": "Loan agreement",
"redirectURL": "your-redirect-url.com?other_keys=youcandefinehere",
"signers": [
{
"identifier": "9876543210",
"name": "John Doe",
"status": "pending",
"url": "https://dg-sandbox.setu.co/signature/sign?requestId=cb80bfb4-d163-426e-ad57-1fd8889e62d4&signerId=b3510273-015a-4b8e-b9a5-36550cba0692"
}
],
"status": "SIGN_PENDING"
}

The url from this response should be used to redirect your customer to complete a signature. The session of the url is activated once the user is redirected to it, and remains active for 30 minutes by default. Note that only one session can exist across all signers at any given time.

You can use the returned url to test the eSign process on Sandbox. On this link, enter Aadhaar number as 123456789012 and OTP as 123456 to successfully complete a signature. Any other value will be considered invalid.

When the session of a url is active, the status of the signature request is SIGN_IN_PROGRESS and no other signer will be able to sign the document at that point of time.


Get signature request status#

Call this API to get the details of a signature request by passing its unique 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 statusesSIGN_INITIATED—No signer has signed the document yetpendingSIGN_PENDING—At least one of the signers has signed the documentpending | completedSIGN_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 | completedSIGN_COMPLETE—All signers have completed signing the documentcompleted


Setu has processed your request successfully.


Request#
GET /api/signature/:requestId

Response#

You will get the details associated with the provided signature request id like—

  • documentId , points to the document to be signed.
  • redirectURL is publicly hosted URL, provided by you while creating a signature request. You will get the following query params by default—signature request id, a particular signer’sid and status
  • signers is an array of upto 6 signers, each with an independent status
  • status, the overall status for the signature request. It will change to SIGN_COMPLETE, once all signers have completed signatures.
{
"documentId": "67e0ca30-49e4-4883-86f9-3762f0e6798c",
"id": "cb80bfb4-d163-426e-ad57-1fd8889e62d4",
"name": "sign my aadhaar",
"redirectURL": "setu.co/careers",
"signers": [
{
"identifier": "9876543210",
"name": "John",
"status": "pending", // ENUM values—completed | in_progress
"url": "sign.setu.co"
}
],
"status": "SIGN_INITIATED" // ENUM values—SIGN_PENDING | SIGN_COMPLETE
}

Download signed document#

Call this API to download a signed document.


Document is in SIGN_COMPLETE state and available for download.


Request#
GET /api/signature/:requestId/download/

Response#
{
"downloadUrl": "https://s3.amazonaws.com/downloadfolderpath",
"id": "cb80bfb4-d163-426e-ad57-1fd8889e62d4", //signature request id
"validUntil": "600" //validity of downloadUrl in seconds
}

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.


You will get a success 204 status post deletion.


Request#
POST /api/signature/:id/delete/

Was this page helpful?