Aadhaar Esign

14 min

Introduction

Aadhaar Esign is to send a file for signing through Aadhaar .For that you need to upload file to Signzy file system persist.signzy.tech. Persist allows you to get unique urls for each file which you can use for further processing. Find more information on the file exchange documentation. Please keep below details as prerequisite

Create URL

Once customer get logged in, he/she can create the url for Signzy ESIGN platform.

How to call the API

You will need to log in before sending the request. You are required to pass the access token received from the login call, as the authorization header in the request. You also need to include customerid in the URL.

API Input Guidelines

Need to pass follow information

Sample Curl

Preproduction

Production

curl --location --request POST 'https://esign-preproduction.signzy.tech/api/customers/..customerid../aadhaaresigns' \
--header 'Authorization: <Auth Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
          "task": "url",
          "dob": "...dob...",
  	       "callbackUrl": "...callbackUrl...",
  	       "callbackUrlHeaders":{
  	         "key1":"value1",
  	         "key2":"value2"
  	       },
           "redirectUrl": "...redirectUrl...",
           "eventCallbackUrl": "...eventCallbackUrl...",
           "eventCallbackHeaders": "...eventCallbackHeaders...",  
  	       "redirectTime":"...Time in which it will redirect to the redirectUrl...",
  	       "inputFile": "...inputFile...",
  	       "name": "..name..",
  	       "multiPages": "true/false",
  	       "signatureType": "aadhaaresign",
  	       "pageNo": "...page no to sign (if multiPages is false)...",
  	       "signaturePosition": "...signature position...", // must be CUSTOMIZE to use x-coordinate, y-coordinate, height and width.
  	       "xCoordinate": "10",
  	       "yCoordinate": "10",
  	       "height": "250",
  	       "width": "150",
           "esignTtl": "...esignTtl(in secs)..." ,
           "signatures" : [ //if the signatures array is pass in the parameters then it will overwrite the previous coordinates.
            {
                "pageNo": [1,6],
                "signaturePosition": ["CUSTOMIZE"],
                "height": 30,
                "width": 180,
                "x-coordinate": [20,5],
                "y-coordinate": [20,9]
            }
           ],
           "logoUrl":"...custom logo for expired url...",
           "authMode":"...mode of authentication (otp/fingerprint) while aadhaar based signing of document..",
           "provider":"...nsdl or emudhra for verifying aadhaar number while signing of document..."
        }'

curl --location --request POST 'https://esign.signzy.tech/api/customers/..customerid../aadhaaresigns' \
--header 'Authorization: <Auth Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
          "task": "url",
          "dob": "...dob...",
  	       "callbackUrl": "...callbackUrl...",
           "redirectUrl": "...redirectUrl...",
           "eventCallbackUrl": "...eventCallbackUrl...",
           "eventCallbackHeaders": "...eventCallbackHeaders...",  
  	       "redirectTime":"...Time in which it will redirect to the redirectUrl...",
  	       "inputFile": "...inputFile...",
  	       "name": "..name..",
  	       "multiPages": "true/false",
  	       "signatureType": "aadhaaresign",
  	       "pageNo": "...page no to sign (if multiPages is false)...",
  	       "signaturePosition": "...signature position...", // must be CUSTOMIZE to use x-coordinate, y-coordinate, height and width.
  	       "xCoordinate": "10",
  	       "yCoordinate": "10",
  	       "height": "250",
  	       "width": "150",
           "esignTtl": "...esignTtl(in secs)..." ,
           "signatures" : [ //if the signatures array is pass in the parameters then it will overwrite the previous coordinates.
            {
                "pageNo": [1,6],
                "signaturePosition": ["CUSTOMIZE"],
                "height": 30,
                "width": 180,
                "x-coordinate": [20,5],
                "y-coordinate": [20,9]
            }
           ],
           "logoUrl":"...custom logo for expired url...",
           "authMode":"...mode of authentication (otp/fingerprint) while aadhaar based signing of document..",
           "provider":"...nsdl or emudhra for verifying aadhaar number while signing of document..."
        }'

Input Parameters

PARAMETERS	DESCRIPTION	REQUIRED/OPTIONAL
task	Type of Transaction performed in Signzy System	Required
dob	Date Of Birth	Optional
callbackUrl	Callback url for posting data if it is required to post the post data to some other url for the particular request	Optional
callbackUrlHeaders	The Headers of the event POST request (callbackUrl). The parameter accepts an object (JSON) with key-value pairs for Headers. By default it is an empty object (JSON). For Example, { "Content-Type": "application/json", "Key": "Value", ... }	Optional
redirectUrl	Redirection URL is for redirecting the application to the provided URL once the ESIGN transaction is over.	Optional
eventCallbackUrl	The URL where the application POST the event information after completion of the ESIGN transaction (Success/Failure).	Optional
eventCallbackHeaders	The Headers of the event POST request (eventCallbackUrl). The parameter accepts an object (JSON) with key-value pairs for Headers. By default it is an empty object (JSON). For Example, { "Content-Type": "application/json", "Key": "Value", ... }	Optional
redirectTime	Time (in seconds) in which it will redirect to the redirectUrl. (Default: 10s)	Optional
inputFile	File which has to be signed.File size should be less than 5mb.	Required(either while creating the URL) or upload the file on the portal.
name	Name of person signing the document	Required(either while creating the URL) or upload the file on the portal
multiPages	If False signature while appear on a single page if pageNo parameter is not set if True then signature on all Pages	Optional(Default True)
signaturePosition	Position where signature is required TOP-LEFT TOP-CENTER TOP-RIGHT MIDDLE-LEFT MIDDLE-CENTER MIDDLE-RIGHT BOTTOM-LEFT BOTTOM-CENTER BOTTOM-RIGHT CUSTOMIZE	Optional(Default BOTTOM-RIGHT)
signatureType	aadhaaresign for adhaar esignature Esign for normal esign where you can either draw ot upload or select font for esignature aadhaaresign esign	Optional(esign default)
pageNo	PageNo where signature only valid when multipages is false	Optional(last page)
xCoordinate	xCoordinate where signature block should start	Optional
yCoordinate	yCoordinate where signature block should start	Optional
height	Height of signature block	Optional (For signatureType as aadhaaresign, default 28)
width	Width of signature block	Optional (For signatureType as aadhaaresign, default 170)
esignTtl	E-sign ttl (by default 14 days)	Optional
signatures	To allow signature to be placed at multiple places on the same page. It accepts array of objects. Following is the signature object: pageNo : array of page numbers where signautre to be pasted. signaturePosition : Position where signature is required TOP-LEFT TOP-CENTER TOP-RIGHT MIDDLE-LEFT MIDDLE-CENTER MIDDLE-RIGHT BOTTOM-LEFT BOTTOM-CENTER BOTTOM-RIGHT CUSTOMIZE height : height of signautre width : width of signature x-coordinate : array of coordinates, NOTE : to be used only in case of CUSTOMIZE position y-coordinate : array of coordinates, NOTE : to be used only in case of CUSTOMIZE position NOTE : No. of x-coordinates and y-coordinates must be equal	Optional If signatures array is not passed, it will take the default signautre position as mentioned above
logoUrl	custom logo for expired url	Optional
authMode	Mode of authentication for verification of aadhaar number while signing of document Possible Values : "otp", "fingerprint" Default is OTP based authentication.	Optional
provider	Authentication Service Agency (ASA) to provide Aadhaar authentication Possible values : "nsdl", "emudhra" Default is nsdl	Optional

Sample Response

{
           "id":"..unique id..",
           "customerId":"..customerId..",
           "result": 
           {
            "token": "...token...",
            "dob": "...dob...",
            "isUsed": 0,
            "url": "...url...",
            "inputFile": "...input file...",
            "redirectUrl": "...redirectUrl...",
            "callbackUrl": "...callbackUrl...",
            "eventCallbackUrl": "...eventCallbackUrl...",
            "eventCallbackHeaders": "...eventCallbackHeaders...",  
            "redirectTime":"...Time in which it will redirect to the redirectUrl..."
            "signatureType": "aadhaaresign",
            "name": "..name..",
            "selectPage": "ALL",
            "pageNo": "...pageNo...",
            "signaturePosition": "...signature position...", 
            "xCoordinate": "...xCoordinate...",
            "yCoordinate": "...yCoordinate...",
            "width": "...width...",
            "height": "...height...",
            "expiryTimestamp": "...expiryTimestamp...",
            "signatures" : [ 
                "pageNo": [1,6],
                "signaturePosition": ["CUSTOMIZE"],
                "height": 30,
                "width": 180,
                "x-coordinate": [20,5],
                "y-coordinate": [20,9]
            ],
            "logoUrl":"...custom logo for expired url...",
            "authMode":"...mode of authentication (otp/fingerprint) while aadhaar based signing of document..",
            "provider":"...Authentication Service Agency (ASA) to provide Aadhaar authentication..."
          }
    }

Response Parameter

PARAMETERS	DESCRIPTION
id	Unique Id
customerId	Unique Customer Id
token	Unique token generated
url	url which redirects the signer to the page to sign
expiryTimestamp	Timestamp at which the url expires. (current time + esignTtl)

After getting the verification url, put the url in web browser tab and enter. It will navigate to the signzy page where below page will display.
Now enter the UID for the customer(only required for aadhaaresign) if it not prefilled
While creating the URL if document to be signed URL is not passed and signer name is not passed then enter the details in the window.
After this clicking on the Confirm button it will navigate to the ESP page. Displayed as below. Here we have generate the OTP(for Aadhaar based Esign).
After getting the otp, we need to enter it and then click on the submit button.
Once the verification is successful then the signzy API will confirm that your ESIGN Transaction is successful.
If the Callback URL is provided then whole response in JSON format will be posted(POST REQUEST) is posted to that URL.
If Redirect URL is provided then once response is posted in Callback URL the iframe redirects itself it to the Redirect URL provided.
If eventCallbackUrl is provided then event data is posted to this URL using a POST request after compeletion of transaction (Success/Failure)
If you are doing testing of this API and trying to do E-Sign with same UID for multiple times, then keep a time gap of 30 minutes for consecutive requests

Getting Data

Sample Curl

Preproduction

Production

curl --location --request POST 'https://esign-preproduction.signzy.tech/api/callbacks' \
--header 'Authorization: <Auth Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerId": "...customer ID...",
    "token": "...token received in create URL..."
    }'

curl --location --request POST 'https://esign.signzy.tech/api/callbacks' \
--header 'Authorization: <Auth Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerId": "...customer ID...",
    "token": "...token received in create URL..."
    }'

Input Parameters

PARAMETERS	DESCRIPTION	REQUIRED/OPTIONAL
customerId	Unique ID for each Customer	Required
token	Unique ID for each ESIGN Transaction	Required

Sample Response

{
        "customerId": ".customerId...",
        "token": ".token..",
        "id": 4,
        "result": {
            "token": "..token..",
            "dob": "...dob...",
            "isUsed": 1,
            "url": "...url for esign...",
            "inputFile": "...input file...",
            "signatureType": "aadhaaresign",
            "name": "...name...",
            "selectPage": "..selectPage..",
            "createSignatureOptions": [...Options of create signature...],
            "signaturePosition": "...signature position...",
            "matchScoreResult": {
                "nameMatchScore": "...nameMatchScore (Value lies between [0,1])...",
                "yobMatchScore": "...yobMatchScore(Either 0 or 1)..."
            },
            "pageNo": "...page no to sign (if multiPages is false)...",
            "esignedFile": "...e-signed file...",
            "redirectTime": "...Time in which it will redirect to the redirectUrl...",
            "expiryTimestamp": "...expiryTimestamp..."
        },
        dscData: {
            "state": "..state..",
            "pincode": "..pincode..",
            "dnQualifier": "..dnQualifier..",
            "yob": "..yob..",
            "gender": "..gender..",
            "uidLastFourDigits": "..uidLastFourDigits..",
            "x500UniqueIdentifier": "..x500UniqueIdentifier..",
            "aadhaarToken": "..aadhaarToken..",
            "pseudonym": "..pseudonym..",
            "aadhaarType": "..aadhaarType..",
            "country": "..country..",
            "name": "..name.."
        }
    }

Response Parameters

PARAMETERS	DESCRIPTION
result	Object containing all the parameters from the create url task
matchScoreResult	Object containing the nameMatchScore and yobMatchScore of input vs aadhaar data.
timestamp	Timestamp when the document was signed
esignedFile	url of the signed file
dscData	Object containing aadhaar related data

Event Callback Posted Data Format

{
        "message": "..message..",
        "token": "..token..",
        "esignData": {
          "esignedFile": "..esignedFile..",
          "transactionId": "..transactionId..",
          "success": true/false,
          "errorCode": "..errorCode..",
          "errorMessage": "..errorMessage..",
          "signatureType": "..signatureType.."
        }
}

Below table briefs the data submitted to the eventCallbackUrl

PARAMETERS	DESCRIPTION	TYPE
message	Message regarding the transaction	String
token	Unique token associated with this transaction	String
esignData	Object Containing data regarding the esign transaction	JSON Object
esignData.esignedFile	Url to esigned file generated in case of successful completion of transaction.	String
esignData.transactionId	Transaction Id generated for this transaction	String
esignData.success	If the transaction was successful or not	Boolean
esignData.errorCode	Error Code in case the transaction fails	String
esignData.errorMessage	Error Message in case the transaction fails	String
esignData.signatureType	Signature Type	String

Getting help

Please feel free to contact us if you have any questions, require clarification, or have ideas for how to make the documents or any of our services better.

You can reach out to us at [email protected].