SetuBot
—
–
/

to search

Introducing Setu API playground Check it out ↗

Reading time — 12 minutes

Edit this page ↗

#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 requestid.


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.

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 6 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.

Normal esign (without configID)

Setu has processed your request successfully.

Request
POST /api/signature 
                
                { 
                  "documentId": "67e0ca30-49e4-4883-86f9-3762f0e6798c", 
                  "redirectUrl": "your-redirect-url.com?other_keys=youcandefinehere", 
                  "signers": [{ 
                      "identifier": "9876543210", 
                      "displayName": "John Doe", 
                      "birthYear": "1988",
                      "signature": { 
                          "onPages": [ 
                              "1" 
                          ], 
                          "position": "bottom-left", 
                          "height": 60, 
                          "width": 180 
                      } 
                  }] 
                }
Response

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

{ 
                    "documentId": "67e0ca30-49e4-4883-86f9-3762f0e6798c", 
                    "id": "cb80bfb4-d163-426e-ad57-1fd8889e62d4", 
                    "redirectUrl": "your-redirect-url.com?other_keys=youcandefinehere", 
                    "signers": [{ 
                            "displayName": "John Doe", 
                            "birthYear": "1988", //included if specified in Create signature request API
                            "id": "34f94af1-a8b9-4797-b287-c5ef7bff99a1", 
                            "identifier": "9876543210", 
                            "signatureDetails": null, 
                            "status": "pending", 
                            "url": "https://dg-uat.setu.co/signature/preview?requestId=6bae9d1f-0fa6-44e5-a801-3ad4a5f10a12&signerId=34f94af1-a8b9-4797-b287-c5ef7bff99a1" 
                    }], 
                    "status": "sign_initiated" 
                }

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 15 minutes by default. Note that if one of the signers is signing the document, other signers have to wait until the active signer has finished signing.

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.

Flexi esign (with configID)

Setu has processed your request successfully.

When passiing a configID, width, height, position and on pages field are not required as they are picked from the config associated with the id.

Request with configId
POST /api/signature 
                
                {
                  "documentId": "{{document_id}}",
                  "redirectUrl": "http://setu.co",
                  "configId": "e66e4d4b-165b-49db-bef2-3f11f9f2384",
                  "signers": [
                    {
                      "identifier": "7002484002",
                      "displayName": "Rahul R",
                      "birthYear": "1988",
                      "signerConfigNumber": 1
                    },
                    {
                      "identifier": "9811412438",
                      "displayName": "chetri R",
                      "birthYear": "1987",
                      "signerConfigNumber": 2
                    }
                  ]
                }
Response

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

{ 
"documentId": "67e0ca30-49e4-4883-86f9-3762f0e6798c", 
"id": "cb80bfb4-d163-426e-ad57-1fd8889e62d4", 
"redirectUrl": "your-redirect-url.com?other_keys=youcandefinehere", 
"signers": [{ 
        "displayName": "Rahul R", 
        "birthYear": "1988", //included if specified in Create signature request API
        "id": "34f94af1-a8b9-4797-b287-c5ef7bff99a1", 
        "identifier": "7002484002", 
        "signatureDetails": null, 
        "status": "pending", 
        "url": "https://dg-uat.setu.co/signature/preview?requestId=6bae9d1f-0fa6-44e5-a801-3ad4a5f10a12&signerId=34f94af1-a8b9-4797-b287-c5ef7bff99a1" 
},
{ 
        "displayName": "chetri R", 
        "birthYear": "1988", //included if specified in Create signature request API
        "id": "34f94af1-a8b9-4797-b287-c5ef7bff99a1", 
        "identifier": "9811412438", 
        "signatureDetails": null, 
        "status": "pending", 
        "url": "https://dg-uat.setu.co/signature/preview?requestId=6bae9d1f-0fa6-44e5-a801-3ad4a5f10a12&signerId=34f94af1-a8b9-4797-b287-c5ef7bff90a2" 
}
], 
"status": "sign_initiated" 
                }

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 15 minutes by default. Note that if one of the signers is signing the document, other signers have to wait until the active signer has finished signing.

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 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

Type 1

Setu has processed your request successfully and no signer has signed the document yet.

Request

Pass the signature request id as a URL parameter

GET  /api/signature/:id
Response

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

  • documentId , points to the document to be signed.
  • id is the signature request id associated with this signature.
  • 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’s id and status
  • signers is an array of upto 6 signers, each with an independent signer id and 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", 
                    "redirectUrl": "setu.co/careers", 
                    "signers": [ 
                      { 
                        "displayName": "John Doe", 
                        "birthYear": "1988", //included if specified in Create signature request API
                        "id": "9d9e47f7-9c24-4587-8775-f01b17e6fc4d" 
                        "identifier": "9876543210", 
                        "signatureDetails":null, 
                        "status": "pending", // ENUM values—pending | in_progress | signed 
                        "url": "sign.setu.co" 
                      } 
                    ], 
                    "status": "sign_initiated" // ENUM values—sign_initiated | sign_pending | sign_in_progress | sign_complete 
                }

Type 2

Setu has processed your request successfully and at least one of the signers has signed the document.

Request

Pass the signature request id as a URL parameter

GET  /api/signature/:id
Response

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

  • documentId , points to the document to be signed.
  • id is the signature request id associated with this signature.
  • 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’s id and status
  • signers is an array of upto 6 signers, each with an independent signer id and status
  • signatureDetails is a JSON object, which has details of the signer as per Aadhaar—aadhaarName, aadhaarSuffix, birthYear, gender and postalCode.
  • 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", 
                    "redirectUrl": "setu.co/careers", 
                    "signers": [ 
                      { 
                        "displayName": "John Doe", 
                        "birthYear": "1988", //included if specified in Create signature request API
                        "id": "9d9e47f7-9c24-4587-8775-f01b17e6fc4d" 
                        "identifier": "9876543210", 
                        "signatureDetails": { 
                            "aadhaarName": "John Doe", 
                            "aadhaarSuffix": "XXXX", 
                            "birthYear": "1988", 
                            "gender": "M", 
                            "postalCode": "560001" 
                        }, 
                        "status": "signed", // ENUM values—pending | in_progress | signed 
                        "url": "sign.setu.co" 
                      } 
                    ], 
                    "status": "sign_complete" // ENUM values—sign_initiated | sign_pending | sign_in_progress | sign_complete 
                }

#Download signed document

Call this API to download a signed document.

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 
                  }

#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

Pass the signature request id as a URL parameter

POST /api/signature/:id/delete/

Was this page helpful?