Our eSign APIs enable easy collection of Aadhaar based electronic signatures
that are legally enforceable. This is built on top of NSDL and emudra
infrastructure and is fully privacy compliant.
We also provide ready-to-use screens built on top of NSDL/emudra. These can
be easily themed as per your brand colours and logo, and can be loaded
inside your app as a webview or redirected to via your website.
Offer your customers a seamless experience of Aadhaar based electronic
signatures. eSign APIs can be used to collect legally binding signatures on
a document, for upto 6 signers.
Whichever industry you belong to—banking, insurance, finance, law and
more—you can provide smooth onboarding experiences for your customers and
enable contracts to be closed digitally.
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—
Upload document—Upload a PDF document to be signed.
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.
Get status of signature request—Get details against a
signature request by passing the signature request id.
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.(website name).co
Production—https://dg.(website name).co
Headers—Contact (website name) for providing the credentials required to
successfully call (website name) APIs. This contains:
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.
(website name) has processed your request successfully.
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 (website name) 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 (website name)’s eSign screens.
It will also be used by (website name) to send back relevant information about a
signer. By default (website name) 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 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)
(website name) has processed your request successfully.
Request
Response
You will get a unique signature request id from
(website name)—to track this signature request. Additionally, you will
get an array of signers, each with their own
signer id, status and
url.
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)
(website name) 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
Response
You will get a unique signature request id from
(website name)—to track this signature request. Additionally, you will
get an array of signers, each with their own
signer id, status and
url.
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.
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 status
Possible signer statuses
sign_initiated—No signer has signed the document
yet
pending
sign_pending—At least one of the signers has signed
the document
pending | 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 document
signed
Type 1
(website name) 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.
(website name) 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.
The signers array specifies the config for each signer. Each signer
config has information about what pages and coordinates the specific
signer has to sign.
The above example indicates there is one signer. Who should sign at
(x1:402, y1:53, x2:542, y2:93) on pages 0 and 1. Assuming
starting index as 0. On coordinate (x1:358, y1:232, x2:498.53,
y2:272) on page 2.
The coordinates are the lower left and upper right of the diagonal of
the sign rectangle.
The config can be used to get flexible configurations like one signer
signs on multiple places on the same page with multiple signers in the
overall configuration.
The optional field indicates whether the sign by that
signer is required for completion of document.
(website name) has processed your request successfully.
Upload the signing config to get the config id in response.
The request body should be a continuos string. To
achieve that, remove line breaks from the JSON before
uploading. (remove line break)
Request
POST /api/signature/config
{
"signers":[
{
"optional":false,
"signRectangles":[
{
"coordinate":{
"lowerLeftX":402,
"lowerLeftY":53,
"upperRightX":542,
"upperRightY":93
},
"pages":[0,1]
},
{
"coordinate":{
"lowerLeftX":358,
"lowerLeftY":232,
"upperRightX":498.53009106595096,
"upperRightY":272.52901734104046
},
"pages":[2]
}
]
}
]
}
Response
You will get the following details—
Unique configId id which can be used to
create signature request.
The same configId can be used across multiple signature
request using doc of one type.
If you require the capability to match the name and year of birth of the
signer with the Aadhaar data received from UIDAI, we can offer that feature
during your onboarding process.
No changes will be required on your end. Raise a ticket at (website name) Support to
enable this feature.
This name match feature is performed by means of fuzzy matching, so you can
set a percentage threshold for name matching. Any name match that falls
below this threshold will be automatically rejected during the signing
process.
The error reason will be displayed to the end user on the final eSign page
prior to redirection.
You can refer to the
error codes listed to see the specific error code and message that
will be displayed.
Below are some sample accept and reject scenarios:
If both names have a match percentage below the set threshold
If the number of words in each name do not match (i.e, first/middle/last
name missing in one of the names) (name1 = Rakesh Kumar Singh, name2 =
Rakesh Singh)
If one name contains only initials (name1 = Rakesh Kumar Singh, name2 =
R K S)
If in the case of initials, the non-initial parts of the name do not
match (name1 = Rakesh Kumar Singh, name2 = R K Sngh)
Please note that this feature is independent, and should you not opt for it,
there will be no changes to the normal eSign flow.
Below is the summary of the notifications which need to be processed on your
server by exposing an endpoint for (website name) to send an HTTP POST request.
These notifications are sent by (website name) when the end user completes the eSign
flow and we receive a callback from our ESP regarding the status of the
signature request.
Please send back an HTTP 200 status code if
the request sent was processed correctly to avoid receiving multiple
notifications for the same eSign event. Response body is ignored.
The base_url is the server URL you share with us to receive
notifications.
To get started quickly, you can setup a mock API endpoint using Beeceptor. Once
configured, (website name) will send notifications to that URL.
This will help you understand the notification flow before you start to
implement it on your server.
Here’s a sample of a successful document signing by a signer, with the
corresponding signature request id as well as the signing
status for all signers associated with a signature request.
