Create Contract API
Introduction
For creating a new contract, customer can pass either contract url(pdf url) or contract base64 and the list of signers. For each signer customer has to pass signer email address, signerName, their signing order (who will sign first,second and so on).
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.
API Input Guidelines
Make sure you replace customerId in the URL with the customerid that you receive from the login call. Also make sure to pass in all necessary input parameters by seeing the Input parameters table below.
Sample Curl
curl --location --request POST 'https://contracting.signzy.tech/api/customers/..customerId../contractdetails' \
--header 'Authorization: <Auth Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"pdfurl": "..url.." OR "pdfbase64": "..pdfbase64.." OR "templateDetails" : {},
"multiPages": "true/false", //In cases of false please provide pageNo in which the signature is needed.
"pageNo": [],
"authMode":"...authMode...",
"provider":"...provider...",
"signerdetail": [{
"signerName": "..signerName..",
"signerEmail": "..signerEmail..",
"signerUid": "..signerUid..",
"signerPincode": "..signerPincode..",
"signerGender": "..signerGender..",
"signerDateOfBirth": "..signerDateOfBirth..",
"signerUidLastFourDigits": "..signerUidLastFourDigits..",
"signatureOptions" :[...signatureOptions...],
"additionalVerification" : [..additionalVerification...],
"showId" : "..showId...",
"idImage" : "...idImage...",
"preVerification":"idVideo",
"faceMatchThreshold": "0.70"
"signerMobile" : "...signerMobile...",
"signerOtpMobile" : "...signerOtpMobile...",
"isOptional" : "...< true/ false >...",
"signaturePosition": "..signaturePosition.." // must be CUSTOMIZE to use x-coordinate, y-coordinate, height and width.
"xCoordinate": "10",
"yCoordinate": "10",
"height": "70",
"width": "130",
"tnc" : "...tnc...",
"location" : "...location to be included in the signature...",
"reason" : "...reason to be included in the signature...",
"signatures":[ { //if the signatures array is pass in the parameters then it will overwrite the previous coordinates.
"pageNo": [2,4],
"signaturePosition": ["TOP-LEFT", "TOP-CENTER"],
}]
}
{
"signerName": "..signerName..",
"signerEmail": "..signerEmail..",
"signerUid": "..signerUid..",
"signerPincode": "..signerPincode..",
"signerGender": "..signerGender..",
"signerDateOfBirth": "..signerDateOfBirth..",
"signerUidLastFourDigits": "..signerUidLastFourDigits..",
"signatureOptions" :[...signatureOptions...],
"additionalVerification" : [..additionalVerification...],
"showId" : "..showId...",
"idImage" : "...idImage...",
"preVerification":"idVideo",
"faceMatchThreshold": "0.70"
"signerMobile" : "...signerMobile...",
"signerOtpMobile" : "...signerOtpMobile...",
"isOptional" : "...< true/false >...",
"signaturePosition": "..signaturePosition.." // must be CUSTOMIZE to use x-coordinate, y-coordinate, height and width.
"xCoordinate": "10",
"yCoordinate": "10",
"yCoordinate": "10",
"height": "70",
"width": "130",
"tnc" : "...tnc...",
"location" : "...location to be included in the signature...",
"reason" : "...reason to be included in the signature...",
"signatures": [ //if the signatures array is pass in the parameters then it will overwrite the previous coordinates.
{
"pageNo": [1,6],
"signaturePosition": ["CUSTOMIZE"],
"height": 70,
"width": 130,
"x-coordinate": [20,5],
"y-coordinate": [20,9]
}
]
}],
"customerMailList": [ //List of the admin email ids of customers who will receive the emails.
"..emailId..",
"..emailId.."
],
"fileFormat": "..fileFormat..",
"logoUrl" : "...logoUrl...",
"contractName" : "...contractName...",
"contractExecuterName": "...contractExecuterName...",
"initiationEmailSubject": "...initiationEmailSubject...",
"callbackUrl": "..callbackUrl..",
"callbackUrlAuthPresent": "true/false",
"callbackUrlAuthType": "....callbackUrlAuthType...",
"callbackUrlAuthCredentials": {
"username": "...username...",
"password": "...password..."
},
"customerCallbackExtraParameters" : ["...customerCallbackExtraParameters..."],
"signerCallbackUrl": "..signer callbackUrl..",
"signerCallbackUrlAuthPresent": "true/false",
"signerCallbackUrlAuthType": "....signerCallbackUrlAuthType...",
"signerCallbackUrlAuthCredentials": {
"username": "...username...",
"password": "...password..."
}
"iacceptSubject" : "..iacceptSubject..",
"iacceptMessage" : "..iacceptMessage..",
"iacceptCCEmailIds" : [..iacceptCCEmailIds..],
"iacceptNegativeTexts" : [..iacceptNegativeTexts..],
"userReminderTime" : "...userReminderTime(in mins)...",
"redirectUrl" : "..redirectUrl..",
"redirectTime" : "..redirectTime..",
"contractTtl" : "...contractTtl(in secs)...",
"emailPdfCustomNameFormat" : "<<desired format>>",
"isParallel" : "...<true / false>...",
"nameMatchThreshold" : "...nameMatchThreshold...",
"allowSignerGenderMatch" : "...<true / false>...",
"allowSignerYOBMatch" : "...<true / false>...",
"showTextBelowNormalEsign" : "true",
"estamp": {
"type": "<<eStamp/eChallan>>",
"stateCode": "<stateCode>>",
"articleCode": "<<articleCode>>",
"firstPartyName": "<<firstpartyname>>",
"secondPartyName": "<<secondpartyname>>",
"stampDutyPaidBy": "<<stampDutyPaidBy>>",
"purposeOfStampDuty": "<<purpose>>",
"stampDutyValue": "<<value>>,
"considerationPrice": "<<considerationPrice>>",
"amount": <<amount>>,
"pageNo": <<pageNo>>,
"location": <<location>>,
"custmonDefacement":"true/false",
"message":"message"
}
"estamp": { // This eStamp payload is applicable only in cases of using multiple estamps.
"stampDetails": [
{
"stateCode": "KA",
"articleCode": "KA1008",
"stampDutyValue": 600,
"purposeOfStampDuty": "test",
"count": "2"
}
],
"type": "eStamp",
"firstPartyName": "signzy technolgy",
"secondPartyName": "cognizant",
"stampDutyPaidBy": "cognizant",
"considerationPrice": ""
},
"docSignerClass3": {
"signingStep": "LAST/FIRST",
"docSignerClass3CertificateValues": {
"clientId": "",
"keyId": "",
"accessKey": ""
},
"signatures": [
{
"pageNo": [
3
],
"signaturePosition": [
"BottomRight"
]
"height": 70,
"width": 130,
"x-coordinate": [20],
"y-coordinate": [20]
}
]
},
"globalesignature": {
"previewRequired" : "true",
"enableUploadSignature" : "true",
"enableFontSignature" : "true",
"enableDrawSignature" : "true",
"enableSignaturePad" : "false",
"enableViewDocumentLink" : "false",
"isCustomized" : "false",
"ValidateAllPlaceholders" : "false"
}
}'Input Parameters
PARAMETER NAME | REQUIRED/OPTIONAL | DESCRIPTION |
|---|---|---|
pdfbase64/pdfurl/templateDetails | Required | Pdf file converted into base64 format/Pdf file uploaded to a file format directURL, OR, template details to create a pdf from html template and json data(explained below). |
contractName | Optional | Name of the contract. |
contractExecuterName | Optional | Name of the entity who has initiated/created/started the contract signing process. |
initiationEmailSubject | Optional | Subject of the Email send to the signer for starting the contract signing process. |
multiPages | Optional(true/false in string) | Attribute value defines whether you have to sign on all pages of the PDF or some specific page. If multiPages is "true", then signature will appear on all the pages of the pdf. If multiPages is "true" and pageNo attribute is given, then signature will appear on all the pages of the pdf. If multiPages is "false" and pageNo attribute is not given then the signature will appear on all the pages of the pdf. If multiPages is "false" and pageNo attribute is given, only then the signature will appear on the pages specified in the pageNo attribute. Default Value : true |
pageNo | Optional | Attribute value specifies the page number on which the signature must appear. multiPages attribute must be "false" for this parameter to work. Refer multiPages for more info. Note: If pageNo is specified in signatures array of signerdetail, then there is no need to specify pageNo and multiPages outside the signerdetail. |
logoUrl | Optional | Url of the logo of the customer. If present, the logo of the customer will be used to displayed in the preview page, contract expired page and the contract failed page. If not present, then Signzy logo will be displayed by default. |
signerdetail | Required | Details about the signer. |
signerName | Required | Name of the signer. |
signerEmail | Required | Email-ID of the signer. |
signerMobile | Optional | Mobile number of the signer. |
signerUid | Optional | Unique ID of the signer. |
signerPincode | Optional | Pincode of the address of the signer. |
signerGender | Optional | Gender of the signer (Male/Female/Transgender). |
signerDateOfBirth | Optional | Date of the signer (ie DD/MM/YYYY). |
signerUidLastFourDigits | Optional | Last 4 digits of the Aadhaar Number of the signer. |
idImage | Optional (String) | This field is taken for each signer which is the image of the idcard of the particular signer which has to matched with the face in the video. |
preVerification | Optional (String) The value is "idVideo" | In case wher you need the video verification step to be done before the signing. In such cases, "idImage" needs to be passed which will contain the ID card and the face match will happen based on this ID card. |
faceMatchThreshold | Optional (String) | The value can range from 0.00 to 1.00. Default value is 0.70 This is the threshold set for face match. If the face match score from video verification is less than the threshold, it will not move to the step of Signing. If the face match score is more than the set threshold, it will move to Signing step. |
showId | Optional (String) | This field is taken for each signer which denotes whether the particular idCard uploaded by the initiator has to been shown to the signer. Default Value: "true" Possible Values : "true/false" |
signatureOptions | Optional (Array) | All the options of signature given by the initiator using one of which the the signer can choose to sign the contract.
Default Value : ['aadhaaresign'] Possible Values : ["aadhaaresign", "aadhaaresign-otp", "aadhaaresign-fingerprint","esign", "iaccept","iacceptwithemail","globalesignature"] Note - "aadhaaresign" cannot be present with "aadhaaresign-otp", or "aadhaaresign-fingerprint". |
additionalVerification | Optional (Array) | All the additional type of verification available.
Default Value : [] No additional verification Possible Values : [ "idvideo", "mobileotp", "emailotp"], |
signerOtpMobile | Optional (String) | This field is taken for each signer where initiator gives the mobile number of signer where otp has to be sent in the case where initiator has chosen mobileotp in additionalVerification. |
isOptional | Optional(true/false in a string) | by default false i.e every signer will be a mandatory signer. It can set to true if a particular signer has to be optional. |
xCoordinate | Optional | xCoordinate where signature block should start |
yCoordinate | Optional | yCoordinate where signature block should start |
height | Optional (default 70) | Height of signature block. The minimum value is 70(pixels). If no value is provided or a value less than 70 is passed, it will be set to the default height of 70. |
width | Optional (default 130) | Width of signature block. The minimum value is 130(pixels). If no value is provided or a value less than 130 is passed, it will be set to the default width of 130. |
location | Optional (applicable for normal esign only) | If provided, location will also be included in the signature block below the normal esign signature. If specified, it's value must not be empty and should not exceed 100 characters. |
reason | Optional (applicable for normal esign only) | If provided, reason will also be included in the signature block below the normal esign signature. If specified, it's value must not be empty and should not exceed 100 characters. |
signatures | Optional If signatures array is not passed, it will take the default signautre position as mentioned above | 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. NOTE: If pageNo is specified in signatures array of signerdetail, then there is no need to specify pageNo and multiPages outside the signerdetail. signaturePosition : Position where signature is required
height : height of signautre width : width of signature x-coordinate : array of coordinates,
y-coordinate : array of coordinates,
NOTE : No. of x-coordinates and y-coordinates must be equal |
authMode | Optional | Mode of authentication for verification of aadhaar number while signing of document Possible Values : "otp", "fingerprint" It works with "signatureoptions", "aadhaaresign". Once you set the value of the key "signatureoptions" as "aadhaaresign", you can decide the authentication mode as "otp" or "fingerprint". Default is OTP based authentication. |
provider | Optional | Authentication Service Agency (ASA) to provide Aadhaar authentication Possible values : "nsdl", "emudhra" Default Value : nsdl |
customerMailList | Optional | List of the admin mail ids of customers. |
fileFormat | Required | Format of the PDF passed in the contract whether it is in base64 format or directURL uploaded to file system. |
Callback URL | Required | Callback url for posting data if it is required to post the post data to some other url for the particular request. |
Callback Auth Present | Optional (true/false in string) | Whether a authentication is required to post to callbackUrl. Default Value : false |
Callback Auth Type | Optional | If authentication is required to post to callbackUrl,then what is authentication type. Default Value : basic-auth |
Callback Auth Credentials | Optional | If authentication is required to post to callbackUrl and authentication type is basic-auth,then this takes the auth username and auth password. |
Customer Callback Extra Parameters | Optional (Array) | All the additional parameters that you want to push to callbackUrl apart from standard parameters.
Default Value : [] No additional parameters Possible Values : ["initialContract", "initialPdfHash", "contractName", "contractExecuterName", "contractPageCount", "finalSignedContractHash", "finalDscSignedContract", "finalDscSignedContractHash", "auditCertificate", "auditCertificateHash", "signerdetail"], |
Signer Callback URL | Optional | Signer Callback url for posting data once Aadhaar ESign Process for the particular transaction is completed by the signer. |
Signer Callback Auth Present | Optional (true/false in string) | Whether a authentication is required to post to Signer Callback url . Default Value : false |
Signer Callback Auth Type | Optional | If authentication is required to post to Signer callbackUrl,then what is authentication type. Default Value : basic-auth |
Signer Callback Auth Credentials | Optional | Credentials If authentication is required to post to Signer callbackUrl and authentication type is basic-auth,then this takes the auth username and auth password. |
iacceptSubject | Optional | The Subject the signer needs to send in the consent email |
iacceptMessage | Optional | The Message body the signer needs to send in the consent email |
iacceptCCEmailIds | Optional | The Email IDs the signer needs to add in cc while sending the consent email |
iacceptNegativeTexts | Optional | The Negative words that the contract initiator wants to check if it is there in the consent email,then the consent email is rejected |
contractTtl | Optional | Contract ttl (By default 14days) |
userReminderTime | Optional | This parameter will be used to notify signers who are yet to sign the contract. You must specify a time interval during which the system will remind the signers to sign the contract. Eg. userReminderTime is set to 30 minutes then the reminder email will be sent to the signer every 30 minutes until all the signers have signed the contract or the contract expires (refer contractTtl parameter). There might be a delay of upto 10 minutes to send the reminder email. |
redirectUrl | Optional | Redirection URL is for redirecting the application to the provided URL once the signing and addition verification (if any) is completed. |
redirectTime | Optional | Time (in seconds) in which it will redirect to the redirectUrl. Default Value : 5 seconds |
tnc | Optional | Terms and Conditions of the contract while signing through iaccept and iacceptwithemail method. If field is empty or not passed then signzy default text will come. |
emailPdfCustomNameFormat | Optional | Name of the signer's signed contract pdf which signer receives in zip file after succesfully signing on his email. Possible values are ["contractName_signerName", "contractId_signerId", "signerName"]. by passing this value, final email received will have meaningful name- auditcert file name = contractId_AuditCertificate.pdf DSCsignedpdf file name = contractId_DSCSignedContract.pdf |
isParallel | Optional(true/false in a string) | By default false if not passed. If set to true, the signing flow would be parallel i.e all the signers mentioned in the signerdetail array will be receiving the signing link on their respective emails at same time instead of sequentially triggering the email for the next signer only if current signer signs it succesfully. |
nameMatchThreshold | Optional(Possible values : "0.01", "0.02", "0.03", ...... , "1.00" in a string) | In case of Aadhaar esigning, the name extracted after signer signs with aadhaar esign must match with signerName mentioned in signerdetail array for a particular signer. If the percentage of name match is less than the threshold, it will throw an error popup and ask the signer to sign again. |
allowSignerGenderMatch | Optional(true/false in a string, in lowercase only) | In case of Aadhaar esign, if this parameter is set to true, the signer gender extracted from aadhaar must match with signerGender mentioned in signerdetail array for a particular signer. If it doesn't match, it will throw an error popup and ask the signer to sign again. Note : This parameter will be considered only if nameMatchThreshold field is passed. And once this parameter is passed, signerGender becomes a mandatory parameter with values ["Male","Female","Transgender"] |
allowSignerYOBMatch | Optional(true/false in a string, in lowercase only) | In case of Aadhaar esign, if this parameter is set to true, the signer YOB extracted from aadhaar must match with YOB mentioned in signerDateOfBirth parameter of signerdetail array for a particular signer. If it doesn't match, it will throw an error popup and ask the signer to sign again. Note : This parameter will be considered only if nameMatchThreshold field is passed. And once this parameter is passed, signerDateOfBirth becomes a mandatory parameter |
showTextBelowNormalEsign | Optional (true/false in a string, in lowercase only) | In case of "true", the name of signer and date of signing will also appear in case of Normal eSign. In case of "false", the name of signer and date of signing will not appear in case of Normal eSign. |
eStamp | optional(object will contain estamping details). This is a option to get a stamped document to sign instead of stamping a doc and than using it in signing | Will contain a object given despcription in below table . |
estamp.stampDetails | Optional | An object contating the details of multiple stamps that needs to be clubbed together |
estamp.stampDetails.stateCode | Mandatory | state code of the states where estamps are valid. Possible values : ["KA", "MH", "GJ", "AP", "AN", "AS", "BR", "CT", "CH", "DN", "DD", "DL", "HP", "JK", "JH", "LA", "OR", "PY", "RJ", "TN", "TR", "UP", "UT", "PB", "WB", "GA", "HR", "KL", "MN", "ML", "MZ", "NL", "LD", "SK", "AR", "TG", "MP"] |
estamp.stampDetails.articleCode | Mandatory | article Code for E-stamping |
estamp.stampDetails.stampDutyValue | Mandatory | amount of the stamp duty |
estamp.stampDetails.purposeOfStampDuty | Mandatory | purpose of stamp duty |
estamp.stampDetails.count | Mandatory | Number of stamp papers |
estamp.type | Mandatory | It is going to be "eStamp" as "eStamp" is supported for multiple stamp papers. |
estamp.firstPartyName | Mandatory | name of first party involved in the transaction |
estamp.secondPartyName | Mandatory | name of second party involved in the transaction |
estamp.stampDutyPaidBy | Mandatory | name of the party who paid the stamp duty(first party or second party) |
estamp.considerationPrice | Optional | amount of fund involved in the transaction |
templateDetails options explained (if user want to create a pdf from the template)
PARAMETERS | DESCRIPTION | TYPE | VALUE (COMPULSORY OR OPTIONAL) |
|---|---|---|---|
templateUrl | url of the template to create pdf. types of templates allowed are
| string | Mandatory |
jsonData | json data to be filled in template. | object | Mandatory |
Configuring html and docx template.
Below are sample html template, docx template and json data to create pdf. Make sure to pass the correct extensions of urls (.html and .docx) in template url for html and docx template. These are just examples on how to add variables in the template.
{
"templateUrl":"...<url of html template>...",
"jsonData":{
"name":"data1",
"checkBoxValue":"...<checked>...", // if user wants to fill a checkbox, make sure to pass value as checked
"imageValue":"...<url of the image to be filled in source block of html tag>..."
}
}
Configuring editable pdf template.
{
"templateUrl":"...<url of editable pdf template>...",
"jsonData":{
"image1":{
"type":"IMAGE",
"value":"url/base64",
"dimensions":{
"xCoordinate":10,
"yCoordinate":10,
"width":20,
"height":20
},
"pageNo":3
},
"checkbox1":{
"type":"CHECKBOX",
"isChecked":"true"
},
"textField1":{
"type":"TEXTFIELD",
"value":"data for text field 1"
},
"textField2":{
"type":"TEXTFIELD",
"value":"data for text field 2"
}
}
}Sample Editable PDF @https://persist.signzy.tech/api/files/570712949/download/1348caafc56444acba86a65b3ac73533540ce5bc95d3479cb9a66fd4831c7e2a.pdf
Parameter with description needed in case of estamping only
PARAMETERS | DESCRIPTION | TYPE | VALUE (COMPULSORY OR OPTIONAL) |
|---|---|---|---|
type | you want to use estamp or eChallan | string | Mandatory |
stateCode | state code of the states where estamps are valid. Possible values : ["KA", "MH", "GJ", "AP", "AN", "AS", "BR", "CT", "CH", "DN", "DD", "DL", "HP", "JK", "JH", "LA", "OR", "PY", "RJ", "TN", "TR", "UP", "UT", "PB", "WB", "GA", "HR", "KL", "MN", "ML", "MZ", "NL", "LD", "SK", "AR", "TG", "MP"] | string | Mandatory |
firstPartyName | name of first party involved in the transaction | string | Mandatory |
secondPartyName | name of second party involved in the transactiton | string | Mandatory |
stampDutyValue | amount of the stamp duty | string | Mandatory in cases when type eStamp |
purposeOfStampDuty | purpose of stamp duty | string | Mandatory |
considerationPrice | amount of fund involved in the transaction | string | Optional |
articleCode | article Code for E-stamping | string | Mandatory |
stampDutyPaidBy | name of the party who paid the stamp duty(first party or second party) | string | Mandatory |
location | location of defacement. available option : topLeft, topCenter, middleLeft, middleCenter, bottomLeft, bottomCenter Right not included as there can be space issue. | String | optional (By default bottomLeft) |
amount | amount of the eChallan duty | String | Mandatory in cases when type is eChallan, not needed when type is estamp |
pageNo | Page no on which defacement is needed. | Array | optional(By default first page) |
custmonDefacement | custmDefacement is required or not | boolean | optional(By default false) when type is eChallan |
message | message text for custom defacement, It can contain variables. the variable should be enclosed in {{}} and can be one from the given {{challanNo}},{{challanDate}},{{stateCode}},{{firstParty}},{{articleCode}},{{amount}},{{secondPartyName}},{{purposeOfStampDuty}},{{stampDutyPaidBy}} String | string | mandatory when custmonDefacement is true |
Parameters with description needed in case of docsignerclass3 only.
Parameter | Description | Mandatory/Optional | Data Type |
|---|---|---|---|
docSignerClass3 | Object containing signing information | Mandatory | Object |
signingStep | Specifies the signing step It can take 2 values FIRST - if you want the signing to happen first LAST - If you wan the signing to happen at last | Mandatory | String |
docSignerClass3CertificateValues | Object containing certificate-related values | Mandatory | Object |
clientId | Client ID for certificate | Mandatory | String |
keyId | Key ID for certificate | Mandatory | String |
accessKey | Access key for certificate | Mandatory | String |
signatures | Array of signature objects | Mandatory | Array of Objects |
pageNo | Array specifying page numbers to sign | Mandatory | Array of Strings |
signaturePosition | Array specifying signature position on the page Position where signature is required
| Mandatory | Array of Strings |
height | Height of the signature NOTE : to be used only in case of CUSTOMIZE position | Optional | String |
width | Width of the signature NOTE : to be used only in case of CUSTOMIZE position | Optional | String |
x-coordinate | Array specifying X-coordinates of the signature NOTE : to be used only in case of CUSTOMIZE position No. of x-coordinates and y-coordinates must be equal | Optional | Array of Strings |
y-coordinate | Array specifying Y-coordinates of the signature NOTE : to be used only in case of CUSTOMIZE position No. of x-coordinates and y-coordinates must be equal | Optional | Array of Strings |
Parameter with description needed in case of globalesignature only
Parameters | Description | Type | Mandatory/Optional |
|---|---|---|---|
previewRequired | By default, this will be TRUE. It will give the user the option to preiew the document before signing. Pass FLASE if the preview is not required before signing the document. | Boolean | Optional |
enableViewDocumentLink | By default, this value will be FALSE. Pass TRUE if document view link is required. Note: Document link will be displayed only when preview is not enabled. If Preview required is FALSE, then set "enableViewDocumentLink" as TRUE.
| Boolean | Optional |
isCustomized | This parameter indicates whether the user can customize the signature placeholder at the time of signing. Allowed values are true and false | String | Mandatory |
validateAllPlaceholders | This parameter indicates the mandatory check for all the Signatures. If the value is TRUE, then the signatory is asked mandatorly to review all the signatures in the document. Default value is FALSE | Boolean | Optional |
enableUploadSignature | By default, this will be TRUE, the user will have the option to upload handwritten signature in emSigner Signer Gateway page and the same will be affixed on the signed PDF document. If you want to disable Upload Signature option, pass this value as FALSE | Boolean | Optional |
enableFontSignature | By default, this will be TRUE, the user will have the option to choose or generte some font based signature in emSigner Signer Gateway page and the same will be affixed on the signed PDF document. If you want to disable Font Signature option, pass this value as FALSE | Boolean | Optional |
enableDrawSignature | By default, this will be TRUE, the user will have the option to draw signature in emSigner Signer Gateway page and the same will be affixed on the signed PDF document. If you want to disable Draw Signature option, pass this value as FALSE | Boolean | Optional |
enableSignaturePad | By default, this will be FALSE, if enabled then the user will have the option to connect to third-party signature pads. Currently, we support Topaz Signature Pad. Pass TRUE if you want to enable eSignature pad option. | Boolean | Optional |
Sample Response
{
"pdfurl": "..url..", OR "pdfbase64": "..pdfbase64..", //depends on your input
"signerdetail": [
{
"signerName": "..signerName..",
"signerEmail": "..signerEmail..",
"signerUid": "..signerUid..",
"signerPincode": "..signerPincode..",
"signerGender": "..signerGender..",
"signerDateOfBirth": "..signerDateOfBirth..",
"signerUidLastFourDigits": "..signerUidLastFourDigits..",
"signatureOptions" :["...signatureOptions..."],
"additionalVerification" : ["..additionalVerification..."],
"showId" : "..showId...",
"idImage" : "...idImage...",
"signerMobile" : "...signerMobile...",
"signerOtpMobile" : "...signerOtpMobile...",
"signaturePosition":"..signaturePosition..",
"xCoordinate": "10",
"yCoordinate": "10",
"height": "28",
"width": "170",
"tnc" : "...tnc...",
"signatures": [ {
"pageNo": [2,4],
"signaturePosition": ["TOP-LEFT", "TOP-CENTER"],
"height": 28,
"width": 170
},
"location" : "...location to be included in the signature...",
"reason" : "...reason to be included in the signature...",
"authMode":"...authMode...",
"provider":"...provider...",
"signerId":"..signerId.."
},
{
"signerName": "..signerName..",
"signerEmail": "..signerEmail..",
"signerUid": "..signerUid..",
"signerPincode": "..signerPincode..",
"signerGender": "..signerGender..",
"signerDateOfBirth": "..signerDateOfBirth..",
"signerUidLastFourDigits": "..signerUidLastFourDigits..",
"signatureOptions" :["...signatureOptions..."],
"additionalVerification" : ["..additionalVerification..."],
"showId" : "..showId...",
"idImage" : "...idImage...",
"signerMobile" : "...signerMobile...",
"signerOtpMobile" : "...signerOtpMobile...",
"signaturePosition":"..signaturePosition..",
"xCoordinate": "10",
"yCoordinate": "10",
"height": "28",
"width": "170",
"tnc" : "...tnc...",
"signatures": [
{
"pageNo": [1,6],
"signaturePosition": ["CUSTOMIZE"],
"height": 30,
"width": 180,
"x-coordinate": [20,5],
"y-coordinate": [20,9]
}
],
"location" : "...location to be included in the signature...",
"reason" : "...reason to be included in the signature...",
"authMode":"...authMode...",
"provider":"...provider...",
"signerId":"..signerId.."
}
],
"customerMailList": [ //List of the admin mail ids of customers who will receive the emails.
"..customerMailList..",
"..customerMailList.."
],
"id": "..The Unique Contract Id created for each request which will be used for pulling the data of each contract..",
"customerId": "..customerId..",
"logoUrl" : "...logoUrl...",
"multiPages":"true/false",
"pageNo": "..pageNo",
"contractName": "..contractName..",
"contractExecuterName": "..contractExecuterName..",
"initiationEmailSubject": "..initiationEmailSubject..",
"callbackUrl": "..callbackUrl..",
"callbackUrlAuthType": "..callbackUrlAuthType..",
"callbackUrlAuthCredentials":"{..callbackUrlAuthCredentials..}",
"customerCallbackExtraParameters":"[..customerCallbackExtraParameters..]",
"fileFormat": "directURL",
"iacceptSubject" : "..iacceptSubject..",
"iacceptMessage" : "..iacceptMessage..",
"iacceptCCEmailIds" : ["..iacceptCCEmailIds.."],
"iacceptNegativeTexts" : ["..iacceptNegativeTexts.."],
"userReminderTime" : "...userReminderTime...",
"redirectUrl" : "..redirectUrl..",
"redirectTime" : "..redirectTime..",
"pageCount":"..pageCount.."
}
Response Parameter
PARAMETER NAME | DESCRIPTION |
|---|---|
signerdetail | Details about the signer. |
signerName | Name of the signer. |
signerEmail | Email-ID of the signer. |
customerMailList | List of the admin mail ids of customers. |
id | The Unique ContractId created for each request which will be used for pulling the data of each contract. |
customerId | The Unique CustomerId for each customer. |
callbackUrl | Callback url for posting data if it is required to post the post data to some other url for the particular request. |
fileFormat | Format of the PDF passed in the contract whether it is in base64 format or directURL uploaded to file system. |
pageCount | Number of pages in the input file |
Sample Error
{
"error": {
"name": "Error",
"message": "Internal Server Error",
"statusCode": 500
}
}Error Parameter
PARAMETER NAME | DESCRIPTION |
|---|---|
error | This parameter contains the error. |
error.statusCode | Request Status code from Signzy |
error.name | the name of the error |
error.message | the error message |
Error Codes
CODE | DESCRIPTION | INTERPRETATION |
|---|---|---|
400 | Bad Request | Input Parameter has a missing required parameter |
401 | Authorization Failed | Authorization token is invalid. |
500 | Internal Server Error | Internal error at Signzy, please contact support. |
Posting data to signer callback system
For every signer involved in the contracting signing procedure, data for the success or failure scenarios of the signing procedure is posted back to the signer callback system.Please find undermentioned the data to be posted in the signer callback URL.
Sample Response
{
"contractId": "..contractId...",
"customerId": "..customerId..",
"signerEmail": "..signerEmail..",
"signerName": "..signerName..",
"signerId": "..signerId..",
"signerUid": "signerUid",
"status": "..status..",
"aadhaarErrorCode": "..aadhaarErrorCode..",
"aadhaarErrorMessage": "..aadhaarErrorMessage..",
"aadhaarStatus": "..aadhaarStatus..",
"signerSignedContract": "..signerSignedContract..",
"signerMatchData": {
"nameMatch": "No Match/PARTIAL Match/DIRECT MATCH",
"pincodeMatch": "No Match/Match",
"genderMatch": "No Match/Match",
"dobMatch": "No Match/Match",
"uidLastFourDigitsMatch": "No Match/Match"
},
"signerEventTimestamp" : "...signerEventTimestamp..",
"signerConsentDscSignedPdf": "...signerConsentDscSignedPdf...",
"forensics": {
"userBrowserData": {
"browserName": "...browserName...",
"browserCodeName": "...browserCodeName...",
"cookieEnabled": "true/false",
"browserLanguage": "...browserLanguage...",
"os": "...os...",
"userAgent": "...userAgent...",
"pluginsInstalled": [""],
"browserVersion": "...browserVersion...",
"screenWidth": "...screenWidth...",
"screenHeight": "...screenHeight...",
"screenPixelDepth": "...screenPixelDepth...",
"screenColorDepth": "...screenColorDepth...",
"deviceInfo": {
"complete_device_name": "...complete_device_name...",
"form_factor": "...form_factor...",
"is_mobile": false/true
}
},
"geoLocationData": {
"ip": "...ip...",
"version": "...version...",
"city": "...city...",
"region": "...region...",
"region_code": "...region_code...",
"country": "...country...",
"country_name": "...country_name...",
"country_code": "...country_code...",
"country_code_iso3": "...country_code_iso3...",
"country_capital": "...country_capital...",
"country_tld": "...country_tld...",
"continent_code": "...continent_code...",
"in_eu": false/true,
"postal": "...postal...",
"latitude": "...latitude..".,
"longitude": "...longitude...",
"timezone": "...timezone...",
"utc_offset": "...utc_offset...",
"country_calling_code": "...country_calling_code...",
"currency": "...currency...",
"currency_name": "...currency_name...",
"languages": "...languages...",
"country_area": "...country_area...",
"country_population": "...country_population...",
"asn": "...asn...",
"org": "...org..."
}
},
"matchScoreResult": {
"nameMatchScore": "",
"yobMatchScore": ""
}
}Response Parameter
PARAMETERS | DESCRIPTION |
|---|---|
customerId | The Unique CustomerId for each customer. |
contractId | The Unique ContractId generated for each contract. |
signerName | Name of the signer. |
signerEmail | Email-ID of the signer. |
signerEventTimestamp | EPOCH Timestamp of the time at which Aadhaar ESign Process for the particular transaction is completed by the signer (Integer). |
status | Signzy status says whether user has successfully signed contract or not.(Possible Values:200 for success/500 for failure). |
aadhaarErrorCode | Received Error code of Aadhaar ESign Process for the particular transaction from upstream(UIDAI). |
aadhaarErrorMessage | Received Error Message of Aadhaar ESign Process for the particular transaction from upstream(UIDAI). |
aadhaarStatus | Received Status of Aadhaar ESign Process for the particular transaction from upstream(UIDAI). |
signerSignedContract | Esigned Contract signed by the signer(Possible Values:pdf url/base64 data in case of successful signing or empty string in case Esign Process fails). |
signerMatchData Block | These block returns the match results of the data given in the signer block and data returned by Aadhaar in the Digital Signature Certificate(Possible Values:All individual match data in case of successful signing or empty object in case Esign Process fails). |
matchScoreResult Block | These block returns the match results of the data given in the signer block and data returned by Aadhaar in the Digital Signature Certificate. (Only applicable in case signature type is aadhaaresign) |
nameMatch | Name Match Result matches the name given in the signer block with name returned by Aadhaar in Digital Signature Certificate (Possible values Direct Match/Partial Match/No Match). |
pincodeMatch | Pincode Match Result matches the pincode given in the signer block with pincode returned by Aadhaar in Digital Signature Certificate (Possible values Match/No Match). |
genderMatch | Gender Match Result matches the gender given in the signer block with gender returned by Aadhaar in Digital Signature Certificate (Possible values Match/No Match). |
dobMatch | Date of Birth Match Result matches the year of date of birth given in the signer block with year of birth returned by Aadhaar in Digital Signature Certificate (Possible values Match/No Match). |
uidLastFourDigitsMatch | uidLastFourDigitsMatch matches the gender last signerUidLastFourDigits given in the signer block with the last 4 digits of the aadhaar Number returned by Aadhaar in Digital Signature Certificate (Possible values Match/No Match). |
Posting Data to customer callback after completion of Signing procedure
Once the contract signing procedure is completed i.e; when all the signers(mandatory) mentioned in the signerdetail block have signed the contract, callback data is posted to the callback URL.Please find undermentioned the data to be posted in the customer callback URL.
Sample Response
{
"customerId":"..customerId...",
"contractId":"...contractId..",
"finalSignedContract": "...finalSignedContract...",
"contractCompletionTime": "...time at which the contract is completed(time is in EPOCH format)...",
"initialSignerCount": "..initialSignerCount..",
"signerCount": "..signerCount..",
"deletedSignerCount": "..deletedSignerCount..",
"initialContract": "...initialContract...",
"initialPdfHash": "...initialPdfHash...",
"contractName": "...contractName...",
"contractExecuterName": "...contractExecuterName...",
"contractPageCount": "...contractPageCount...",
"finalSignedContractHash": "...finalSignedContractHash...",
"finalDscSignedContract": "...finalDscSignedContract...",
"finalDscSignedContractHash": "...finalDscSignedContractHash...",
"auditCertificate": "...auditCertificate...",
"auditCertificateHash": "...auditCertificateHash...",
"signerdetail": ["...signerdetail..."],
"mergedUserConsentFileDscSignedBase64": "..Base64String.."
}
Response Parameters
Mandatory Parameters
PARAMETERS | DESCRIPTION |
|---|---|
customerId | The Unique CustomerId for each customer (String). |
contractId | The Unique ContractId generated for each contract (String). |
finalSignedContract | Final Signed Contract signed by all the designated signers.File Format is either DIRECTURL or BASE64 based on fileFormat specified in Create Contract request (String). |
contractCompletionTime | EPOCH Timestamp of the time at which Final Signed Contract was signed by all the designated signers (Integer). |
initialSignerCount | Initial Number of Signers when the contract was created(Integer). |
signerCount | Actual Number of signers who signed the contract(Integer). |
deletedSignerCount | Number of signers who were deleted once the contract was created(Integer). |
Optional Parameters
This values are passed based on values passed in array in customerCallbackExtraParameters in create contract request
PARAMETERS | DESCRIPTION |
|---|---|
initialContract | Initial Contract file used for initiating the contracting process.File Format is either DIRECTURL or BASE64 based on fileFormat specified in Create Contract request (String). |
initialPdfHash | Hash of the initial Contract file used for initiating the contracting process (String). |
contractName | Name of the contract (String). |
contractExecuterName | Name of the executer of the contract(String). |
contractPageCount | Number of pages in the contract file(String). |
finalSignedContractHash | Hash of the final Signed Contract signed by all the designated signers.File Format is either DIRECTURL or BASE64 based on fileFormat specified in Create Contract request (String). |
finalDscSignedContract | Signzy DSC signed Contract once the contract is signed by all the designated signers.File Format is either DIRECTURL or BASE64 based on fileFormat specified in Create Contract request (String). |
finalDscSignedContractHash | Hash of the Signzy DSC signed Contract once the contract is signed by all the designated signers.File Format is either DIRECTURL or BASE64 based on fileFormat specified in Create Contract request (String). |
auditCertificate | Audit Certificate is a certificate generated and digitally signed by signzy which contains contract details,signer Details and auditTrail of the Contract.File Format is either DIRECTURL or BASE64 based on fileFormat specified in Create Contract request (String). |
auditCertificateHash | Hash Audit Certificate is a certificate generated and digitally signed by signzy which contains contract details,signer Details and auditTrail of the Contract.File Format is either DIRECTURL or BASE64 based on fileFormat specified in Create Contract request (String). |
mergedUserConsentFileDscSignedBase64 | The DSC signed merged PDf Base64 generated from the details of the user consent emails sent by signers in iacceptwithemail flow. |
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].