One Touch Sign (OTS)

Initiate Contract API

14min

Introduction
Welcome to the Initiate Contract API, your gateway to effortlessly streamline and orchestrate the process of creating and managing contracts within your application. This comprehensive guide will walk you through the seamless integration of this API, empowering you to initiate contracts, define signers, customize contract parameters, and efficiently manage callback URLs. With the power of this API at your fingertips, you can seamlessly orchestrate complex contract workflows while ensuring a smooth and user-friendly experience for all parties involved.
By leveraging the Initiate Contract API, you can easily upload your contract files, specify signer details, define callback URLs, and even customize various aspects of the contract to align with your specific requirements. The API harnesses the capability to dynamically generate signing URLs for each signer, providing a direct and secure path for individuals to engage with and sign the contract digitally.
Whether you're a developer looking to enhance your application's contract management capabilities or a business seeking a sophisticated and streamlined way to engage signers, the Initiate Contract API offers a powerful solution that seamlessly integrates into your existing infrastructure.
Join us as we delve into the details of how to leverage the Initiate Contract API to empower your application with the ability to effortlessly initiate, manage, and facilitate the signing of contracts, ensuring a frictionless and secure contract execution process for all stakeholders involved. Let's embark on this journey to revolutionize the way contracts are managed and executed within your ecosystem.
Authentication
API authentication is a crucial security process that ensures authorized access to an application programming interface (API). It involves validating the identity of users or systems seeking to interact with the API. Please use the access token shared with you by your assigned Signzy's CSM. Please set the value of the key Authorization in the headers to the access token, while making an API call. In this way, Signzy's system will be able to authenticate you and you will be able to make a successful API call. 
API Details
The details of the API can be found here.
Sample cURL
Pre Production
Production
curl --location 'https://api.signzy.app/api/v3/contract/initiate' \
--header 'Authorization: ***************************************' \
--header 'Content-Type: application/json' \
--data '{
    "pdf": "****************",
    "persistAuthKey": "****************",
    "contractName": "Savings Account Opening Form",
    "contractExecuterName": "Signzy",
    "successRedirectUrl": "https://signzy.com",
    "failureRedirectUrl": "https://google.com",
    "contractTtl": 10000,
    "callbackUrl": "",
    "callbackUrlAuthorizationHeader": "Test",
    "eSignProvider": "EMUDHRA",
    "emudhraCustomization": {
        "logoURL": "",
        "headerColour": "#FF0000",
        "buttonColour": "#FF0000"
    },
    "signerdetail": [
        {
            "signerName": "Mohit",
            "signerGender": "male",
            "signatureType": "AADHAARESIGN-OTP",
            "uidLastFourDigits": "",
            "signerYearOfBirth": "",
            "signatures": [
                {
                    "pageNo": [
                        "All"
                    ],
                    "signaturePosition": [
                        "BottomLeft"
                    ]
                }
            ]
        },
        {
            "signerName": "Ashish",
            "signatureType": "AADHAARESIGN-OTP",
            "uidLastFourDigits": "",
            "signerYearOfBirth": "",
            "signatures": [
                {
                    "pageNo": [
                        11,
                        2,
                        5
                    ],
                    "signaturePosition": [
                        "TOPLEFT",
                        "customize"
                    ],
                    "xCoordinate": [
                        300,
                        5
                    ],
                    "yCoordinate": [
                        400,
                        5
                    ]
                },
                {
                    "pageNo": [
                        1,
                        2,
                        5
                    ],
                    "signaturePosition": [
                        "TOPLEFT",
                        "customize"
                    ],
                    "xCoordinate": [
                        300,
                        5
                    ],
                    "yCoordinate": [
                        400,
                        5
                    ]
                }
            ]
        }
    ],
    "estamp": {
        "type": "eChallan",
        "secondPartyName": "Test",
        "firstPartyName": "Signzy",
        "stateCode": "KA",
        "articleCode": "KA001",
        "purposeOfStampDuty": "",
        "userReference": "",
        "amount": 1,
        "location": "middleCenter",
        "custmonDefacement": "true",
        "message": ""
    },
    "signerCallbackUrl": "",
    "signerCallbackUrlAuthorizationHeader": "test"
    "nameMatchThreshold": "0.90",
    "allowSignerYOBMatch": true,
    "allowSignerGenderMatch": true
}'
curl --location 'https://api.signzy.app/api/v3/contract/initiate' \
--header 'Authorization: ***************************************' \
--header 'Content-Type: application/json' \
--data '{
    "pdf": "****************",
    "persistAuthKey": "****************",
    "contractName": "Savings Account Opening Form",
    "contractExecuterName": "Signzy",
    "successRedirectUrl": "https://signzy.com",
    "failureRedirectUrl": "https://google.com",
    "contractTtl": 10000,
    "callbackUrl": "",
    "callbackUrlAuthorizationHeader": "Test",
    "eSignProvider": "EMUDHRA",
    "emudhraCustomization": {
        "logoURL": "",
        "headerColour": "#FF0000",
        "buttonColour": "#FF0000"
    },
    "signerdetail": [
        {
            "signerName": "Mohit",
            "signerGender": "male",
            "signatureType": "AADHAARESIGN-OTP",
            "uidLastFourDigits": "",
            "signerYearOfBirth": "",
            "signatures": [
                {
                    "pageNo": [
                        "All"
                    ],
                    "signaturePosition": [
                        "BottomLeft"
                    ]
                }
            ]
        },
        {
            "signerName": "Ashish",
            "signatureType": "AADHAARESIGN-OTP",
            "uidLastFourDigits": "",
            "signerYearOfBirth": "",
            "signatures": [
                {
                    "pageNo": [
                        11,
                        2,
                        5
                    ],
                    "signaturePosition": [
                        "TOPLEFT",
                        "customize"
                    ],
                    "xCoordinate": [
                        300,
                        5
                    ],
                    "yCoordinate": [
                        400,
                        5
                    ]
                },
                {
                    "pageNo": [
                        1,
                        2,
                        5
                    ],
                    "signaturePosition": [
                        "TOPLEFT",
                        "customize"
                    ],
                    "xCoordinate": [
                        300,
                        5
                    ],
                    "yCoordinate": [
                        400,
                        5
                    ]
                }
            ]
        }
    ],
    "estamp": {
        "type": "eChallan",
        "secondPartyName": "Test",
        "firstPartyName": "Signzy",
        "stateCode": "KA",
        "articleCode": "KA001",
        "purposeOfStampDuty": "",
        "userReference": "",
        "amount": 1,
        "location": "middleCenter",
        "custmonDefacement": "true",
        "message": ""
    },
    "signerCallbackUrl": "",
    "signerCallbackUrlAuthorizationHeader": "test"
    "nameMatchThreshold": "0.90",
    "allowSignerYOBMatch": true,
    "allowSignerGenderMatch": true
}'
﻿
Input Parameters
Key
Type
M/O
Description
pdf
String
Mandatory
The input PDF file which needs to be signed. It can be in PDF or Base64 formats.
persistAuthKey
String
Optional
If the key is applied during contract creation, both the signed contract and the links to the final signed contract will be password protected using that key.
It accepts alpha numeric values.
contractName
String
Optional
Name of the contract
contractExecuterName
String
Optional
Name of the entity who has initiated/created/started the contract signing process
successRedirectUrl
String
Mandatory
The redirect URL - Post the completion of the Journey, in cases of successful completion, it will be redirected to this page
failureRedirectUrl
String
Mandatory
The redirect URL - Post the completion of the Journey, in cases of failures, it will be redirected to this page
contractTtl
String
Optional
The time in milliseconds after which the contract will expire (By default, it's 14 days)
esignProvider
String
Optional
The provider of the Aadhaar eSign. By default, it will be eMudhra. It can be set to either -
nsdl
eMudhra
emudhraCustomization.logoURL
String
Optional
In case of eMudhra as eSign Provider, pass the logo URL to do a brand customization on UI of eMudhra pages
emudhraCustomization.headerColour
String
Optional
In case of eMudhra as eSign Provider, pass the Header Colour to do a brand customization on UI of eMudhra pages
emudhraCustomization.buttonColour
String
Optional
In case of eMudhra as eSign Provider, pass the Button Colour to do a brand customization on UI of eMudhra pages
signerdetail
Array of Objects
Mandatory
Details about all the signers.
signerName
String
Mandatory
Name of the signer.
signatureType
String
Mandatory
The type of signatures. The three possible values are -
aadhaaresign-otp, 
aadhaaresign-fingerprint
aadhaaresign-faceauth
signerGender
String
Optional
Gender of the signer (Male/Female/Transgender).
uidLastFourDigits
String
Optional
Last 4 digits of the Aadhaar Number of the signer.
signerYearOfBirth
String
Optional
Year of birth of the signer.
signatures
Array of Objects
Mandatory
To allow signature to be placed at multiple places on the same page. Following is the signature object:

pageNo : array of page numbers where signautres need to be pasted. 
Pass ALL, if signature is required on all pages.

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
In case of CUSTOMIZE, pas the x,y coordinate and height, width.
height : height of signautre
width : width of signature
xCoordinate : array of coordinates,
yCoordinate : array of coordinates,
NOTE : No. of xCoordinate and yCoordinate must be equal                     
callbackUrl
String
Mandatory
Callback url for posting data of the contract
callbackUrlAuthorizationHeader
String
Optional
If the callback URL uses authentication, pass the authroization header value in this key
signerCallback Url
String
Optional
Signer Callback url for posting data once Aadhaar ESign Process for the particular transaction is completed by the signer.
signerCallbackAuthorizationHeader
String
Optional
If the Signer Callback URL uses authentication, pass the authroization header value in this key
nameMatchThreshold
String
Optional
In case of Aadhaar esigning, the name extracted after signer signs with aadhaar esign must match with signerName mentioned for a particular signer. If the percentage of name match is less than the threshold, it will be retry scenario. The details would be posted on callback URL for the integrator to make a decision.
Possible Values : "0.01", "0.02", "0.03", ...... , "1.00"
allowSignerGenderMatch
String
Optional
In case of Aadhaar esign, if this parameter is set to true, the signer gender extracted from aadhaar must match with signerGender mentioned for a particular signer. If it doesn't match, it wiil be a retry scenario.
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
String
Optional
In case of Aadhaar esign, if this parameter is set to true, the signer YOB extracted from aadhaar must match with YOB mentioned in signerYearOfBirth for a particular signer. If it doesn't match, it will be a retry scenario.
Note : This parameter will be considered only if nameMatchThreshold field is passed. And once this parameter is passed, signerYearOfBirth becomes a mandatory parameter.
eStamp
Object
Optional 
This is a option to get a stamped document to sign
eStamping Details
Keys
Description
Type
M/O
type
you want to use estamp or eChallan. Values are - 
eChallan
eStamp
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
Mandatory in cases when type eStamp
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
Mandatory when custmonDefacement is true 
Sample Response
200
{
    "emudhraCustomization": {
        "buttonColour": "#FF0000",
        "headerColour": "#FF0000",
        "logoURL": "https://media.trustradius.com/vendor-logos/th/Nh/MVDWEP9M89X5-180x180.JPEG"
    },
    "customerId": "bc3024f6-b2de-493f-8b30-e132c3701ce7",
    "username": "adityasahu",
    "contractId": "e6b9bf89-5725-4331-9efd-0ff53b914764",
    "pdf": "https://staging-persist.signzy.tech/api/files/4879875/download/11d297ab903e442784c6a847a2ce10f3970b314ed512437db9f6bdfc55f6b501.pdf",
    "initialContractHash": "51acd08565171da3a2e1f50b600df06b444ff18204e53103d2ef590688a3a39a",
    "contractName": "dd",
    "contractExecuterName": "dd",
    "successRedirectUrl": "https://signzy.com",
    "failureRedirectUrl": "https://google.com",
    "eSignProvider": "EMUDHRA",
    "contractTtl": 10000,
    "signerdetail": [
        {
            "signerId": "3bd160a3-5e52-4ea8-9819-c1fc1e1bd838",
            "signerName": "mohit",
            "signatureType": "AADHAARESIGN-OTP",
            "uidLastFourDigits": "1345",
            "signerYearOfBirth": "0101",
            "signerGender": "male",
            "signatures": [
                {
                    "pageNo": [
                        "All"
                    ],
                    "signaturePosition": [
                        "BottomLeft"
                    ],
                    "xCoordinate": [],
                    "yCoordinate": []
                }
            ],
            "esignUrl": "https://api-preproduction.signzy.app/api/v3/contract/esign/3bd160a3-5e52-4ea8-9819-c1fc1e1bd838"
        },
        {
            "signerId": "523af19d-762f-40e1-ae00-dbc46f7ed8b1",
            "signerName": "cdcdc",
            "signatureType": "AADHAARESIGN-OTP",
            "uidLastFourDigits": "1345",
            "signerYearOfBirth": "0101",
            "signatures": [
                {
                    "pageNo": [
                        11,
                        2,
                        5
                    ],
                    "signaturePosition": [
                        "TOPLEFT",
                        "customize"
                    ],
                    "xCoordinate": [
                        300,
                        5
                    ],
                    "yCoordinate": [
                        400,
                        5
                    ]
                },
                {
                    "pageNo": [
                        1,
                        2,
                        5
                    ],
                    "signaturePosition": [
                        "TOPLEFT",
                        "customize"
                    ],
                    "xCoordinate": [
                        300,
                        5
                    ],
                    "yCoordinate": [
                        400,
                        5
                    ]
                }
            ],
            "esignUrl": "https://api-preproduction.signzy.app/api/v3/contract/esign/523af19d-762f-40e1-ae00-dbc46f7ed8b1"
        }
    ],
    "callbackUrl": "https://qa.signzy.xyz/callback/mohitposts",
    "callbackUrlAuthorizationHeader": "test",
    "signerCallbackUrl": "https://qa.signzy.xyz/callback/mohitposts",
    "callbackExtraParameter": [],
    "fileTtl": "2 days",
    "estamp": {
        "type": "eChallan",
        "secondPartyName": "Test",
        "firstPartyName": "VMWARE",
        "stateCode": "NL",
        "articleCode": "NL001",
        "purposeOfStampDuty": "sjs",
        "amount": 1,
        "location": "middleCenter",
        "custmonDefacement": "true",
        "message": "Stamp duty of Rs. 1 paid via Stamp Paper Certificate No. xdxdxcd dated 121212"
    }
}
{
    "emudhraCustomization": {
        "buttonColour": "#FF0000",
        "headerColour": "#FF0000",
        "logoURL": "https://media.trustradius.com/vendor-logos/th/Nh/MVDWEP9M89X5-180x180.JPEG"
    },
    "customerId": "bc3024f6-b2de-493f-8b30-e132c3701ce7",
    "username": "adityasahu",
    "contractId": "e6b9bf89-5725-4331-9efd-0ff53b914764",
    "pdf": "https://staging-persist.signzy.tech/api/files/4879875/download/11d297ab903e442784c6a847a2ce10f3970b314ed512437db9f6bdfc55f6b501.pdf",
    "initialContractHash": "51acd08565171da3a2e1f50b600df06b444ff18204e53103d2ef590688a3a39a",
    "contractName": "dd",
    "contractExecuterName": "dd",
    "successRedirectUrl": "https://signzy.com",
    "failureRedirectUrl": "https://google.com",
    "eSignProvider": "EMUDHRA",
    "contractTtl": 10000,
    "signerdetail": [
        {
            "signerId": "3bd160a3-5e52-4ea8-9819-c1fc1e1bd838",
            "signerName": "mohit",
            "signatureType": "AADHAARESIGN-OTP",
            "uidLastFourDigits": "1345",
            "signerYearOfBirth": "0101",
            "signerGender": "male",
            "signatures": [
                {
                    "pageNo": [
                        "All"
                    ],
                    "signaturePosition": [
                        "BottomLeft"
                    ],
                    "xCoordinate": [],
                    "yCoordinate": []
                }
            ],
            "esignUrl": "https://api-preproduction.signzy.app/api/v3/contract/esign/3bd160a3-5e52-4ea8-9819-c1fc1e1bd838"
        },
        {
            "signerId": "523af19d-762f-40e1-ae00-dbc46f7ed8b1",
            "signerName": "cdcdc",
            "signatureType": "AADHAARESIGN-OTP",
            "uidLastFourDigits": "1345",
            "signerYearOfBirth": "0101",
            "signatures": [
                {
                    "pageNo": [
                        11,
                        2,
                        5
                    ],
                    "signaturePosition": [
                        "TOPLEFT",
                        "customize"
                    ],
                    "xCoordinate": [
                        300,
                        5
                    ],
                    "yCoordinate": [
                        400,
                        5
                    ]
                },
                {
                    "pageNo": [
                        1,
                        2,
                        5
                    ],
                    "signaturePosition": [
                        "TOPLEFT",
                        "customize"
                    ],
                    "xCoordinate": [
                        300,
                        5
                    ],
                    "yCoordinate": [
                        400,
                        5
                    ]
                }
            ],
            "esignUrl": "https://api-preproduction.signzy.app/api/v3/contract/esign/523af19d-762f-40e1-ae00-dbc46f7ed8b1"
        }
    ],
    "callbackUrl": "https://qa.signzy.xyz/callback/mohitposts",
    "callbackUrlAuthorizationHeader": "test",
    "signerCallbackUrl": "https://qa.signzy.xyz/callback/mohitposts",
    "callbackExtraParameter": [],
    "fileTtl": "2 days",
    "estamp": {
        "type": "eChallan",
        "secondPartyName": "Test",
        "firstPartyName": "VMWARE",
        "stateCode": "NL",
        "articleCode": "NL001",
        "purposeOfStampDuty": "sjs",
        "amount": 1,
        "location": "middleCenter",
        "custmonDefacement": "true",
        "message": "Stamp duty of Rs. 1 paid via Stamp Paper Certificate No. xdxdxcd dated 121212"
    }
}
﻿
Output Parameters
Field Name
Description
Mandatory/Optional
Type
emudhraCustomization
Customization options for Emudhra ESP including button color, header color, and logo URL.
Optional
Object
customerId
Unique identifier for the customer.
Mandatory
String
username
Username of the customer.
Mandatory
String
contractId
Unique identifier for the contract.
Mandatory
String
pdf
URL to the PDF document.
Mandatory
String
initialContractHash
Initial hash of the contract.
Mandatory
String
contractName
Name of the contract.
Mandatory
String
contractExecuterName
Name of the contract executor.
Mandatory
String
successRedirectUrl
URL to redirect after successful contract execution.
Mandatory
String
failureRedirectUrl
URL to redirect in case of contract execution failure.
Mandatory
String
eSignProvider
Name of the e-sign provider (e.g., EMUDHRA).
Mandatory
String
contractTtl
Time to live (in milliseconds) for the contract.
Mandatory
Number
signerdetail
Details of signers for the contract.
Mandatory
Array of Objects
callbackUrl
URL for callback upon contract completion.
Mandatory
String
callbackUrlAuthorizationHeader
Authorization header for the callback URL.
Optional
String
signerCallbackUrl
URL for individual signer callbacks.
Optional
String
callbackExtraParameter
Extra parameters for the callback.
Optional
Array of Strings
fileTtl
Time to live for the uploaded files (e.g., "2 days").
Mandatory
String
estamp
Electronic stamp details for the contract.
Optional
Object
SignerDetail:
Field Name
Description
Mandatory/Optional
Type
signerId
Unique identifier for the signer.
Mandatory
String
signerName
Name of the signer.
Mandatory
String
signatureType
Type of signature for the signer.
Mandatory
String
uidLastFourDigits
Last four digits of signer's UID.
Mandatory
String
signerYearOfBirth
Year of birth of the signer.
Mandatory
String
signerGender
Gender of the signer.
Mandatory
String
signatures
Signature details for the signer.
Mandatory
Array of Objects
esignUrl
URL for the e-sign process of the signer.
Mandatory
String
Signature (within SignerDetail):
Field Name
Description
Mandatory/Optional
Type
pageNo
Page number(s) for the signature.
Mandatory
Array
signaturePosition
Position(s) of the signature on the page.
Mandatory
Array of Strings
xCoordinate
X-coordinate(s) of the signature.
Optional
Array of Numbers
yCoordinate
Y-coordinate(s) of the signature.
Optional
Array of Numbers
eStamp:
Field Name
Description
Mandatory/Optional
Type
type
Type of electronic stamp (e.g., eChallan).
Mandatory
String
secondPartyName
Name of the second party in the stamp.
Mandatory
String
firstPartyName
Name of the first party in the stamp.
Mandatory
String
stateCode
State code for the stamp.
Mandatory
String
articleCode
Article code for the stamp.
Mandatory
String
purposeOfStampDuty
Purpose of the stamp duty.
Mandatory
String
amount
Amount of stamp duty.
Mandatory
Number
location
Location of the stamp on the document.
Mandatory
String
custmonDefacement
Customization option for defacement.
Mandatory
String
message
Message for the stamp.
Mandatory
String
Sample Errors
400
400
400
400
401
500
{
    "name": "error",
    "message": "Invalid URL extension",
    "reason": "VALIDATION_ERROR",
    "type": "Bad Request",
    "statusCode": 400
}
{
    "name": "error",
    "message": "Invalid URL extension",
    "reason": "VALIDATION_ERROR",
    "type": "Bad Request",
    "statusCode": 400
}
﻿
Error Parameters
Parameter
Type
Description
name
String
In case of errors, it will have the value "error". It represents an error.
message
String
Message for the error
reason
String
Reasons for the error
type
String
Type of error
statusCode
String
Status code of the error
Error Codes
Error Code
Error Message
Explanation
400
Bad Request
Input parameter has a missing required parameter or invalid inputs
401
Authorization Failed
Authorization token is invalid
500
Internal Server Error
Internal error at Signzy, Please reach out to [email protected]
﻿

Key	Type	M/O	Description
pdf	String	Mandatory	The input PDF file which needs to be signed. It can be in PDF or Base64 formats.
persistAuthKey	String	Optional	If the key is applied during contract creation, both the signed contract and the links to the final signed contract will be password protected using that key. It accepts alpha numeric values.
contractName	String	Optional	Name of the contract
contractExecuterName	String	Optional	Name of the entity who has initiated/created/started the contract signing process
successRedirectUrl	String	Mandatory	The redirect URL - Post the completion of the Journey, in cases of successful completion, it will be redirected to this page
failureRedirectUrl	String	Mandatory	The redirect URL - Post the completion of the Journey, in cases of failures, it will be redirected to this page
contractTtl	String	Optional	The time in milliseconds after which the contract will expire (By default, it's 14 days)
esignProvider	String	Optional	The provider of the Aadhaar eSign. By default, it will be eMudhra. It can be set to either - nsdl eMudhra
emudhraCustomization.logoURL	String	Optional	In case of eMudhra as eSign Provider, pass the logo URL to do a brand customization on UI of eMudhra pages
emudhraCustomization.headerColour	String	Optional	In case of eMudhra as eSign Provider, pass the Header Colour to do a brand customization on UI of eMudhra pages
emudhraCustomization.buttonColour	String	Optional	In case of eMudhra as eSign Provider, pass the Button Colour to do a brand customization on UI of eMudhra pages
signerdetail	Array of Objects	Mandatory	Details about all the signers.
signerName	String	Mandatory	Name of the signer.
signatureType	String	Mandatory	The type of signatures. The three possible values are - aadhaaresign-otp, aadhaaresign-fingerprint aadhaaresign-faceauth
signerGender	String	Optional	Gender of the signer (Male/Female/Transgender).
uidLastFourDigits	String	Optional	Last 4 digits of the Aadhaar Number of the signer.
signerYearOfBirth	String	Optional	Year of birth of the signer.
signatures	Array of Objects	Mandatory	To allow signature to be placed at multiple places on the same page. Following is the signature object: pageNo : array of page numbers where signautres need to be pasted. Pass ALL, if signature is required on all pages. 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 In case of CUSTOMIZE, pas the x,y coordinate and height, width. height : height of signautre width : width of signature xCoordinate : array of coordinates, yCoordinate : array of coordinates, NOTE : No. of xCoordinate and yCoordinate must be equal
callbackUrl	String	Mandatory	Callback url for posting data of the contract
callbackUrlAuthorizationHeader	String	Optional	If the callback URL uses authentication, pass the authroization header value in this key
signerCallback Url	String	Optional	Signer Callback url for posting data once Aadhaar ESign Process for the particular transaction is completed by the signer.
signerCallbackAuthorizationHeader	String	Optional	If the Signer Callback URL uses authentication, pass the authroization header value in this key
nameMatchThreshold	String	Optional	In case of Aadhaar esigning, the name extracted after signer signs with aadhaar esign must match with signerName mentioned for a particular signer. If the percentage of name match is less than the threshold, it will be retry scenario. The details would be posted on callback URL for the integrator to make a decision. Possible Values : "0.01", "0.02", "0.03", ...... , "1.00"
allowSignerGenderMatch	String	Optional	In case of Aadhaar esign, if this parameter is set to true, the signer gender extracted from aadhaar must match with signerGender mentioned for a particular signer. If it doesn't match, it wiil be a retry scenario. 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	String	Optional	In case of Aadhaar esign, if this parameter is set to true, the signer YOB extracted from aadhaar must match with YOB mentioned in signerYearOfBirth for a particular signer. If it doesn't match, it will be a retry scenario. Note : This parameter will be considered only if nameMatchThreshold field is passed. And once this parameter is passed, signerYearOfBirth becomes a mandatory parameter.
eStamp	Object	Optional	This is a option to get a stamped document to sign

Keys	Description	Type	M/O
type	you want to use estamp or eChallan. Values are - eChallan eStamp	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	Mandatory in cases when type eStamp
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	Mandatory when custmonDefacement is true

Field Name	Description	Mandatory/Optional	Type
emudhraCustomization	Customization options for Emudhra ESP including button color, header color, and logo URL.	Optional	Object
customerId	Unique identifier for the customer.	Mandatory	String
username	Username of the customer.	Mandatory	String
contractId	Unique identifier for the contract.	Mandatory	String
pdf	URL to the PDF document.	Mandatory	String
initialContractHash	Initial hash of the contract.	Mandatory	String
contractName	Name of the contract.	Mandatory	String
contractExecuterName	Name of the contract executor.	Mandatory	String
successRedirectUrl	URL to redirect after successful contract execution.	Mandatory	String
failureRedirectUrl	URL to redirect in case of contract execution failure.	Mandatory	String
eSignProvider	Name of the e-sign provider (e.g., EMUDHRA).	Mandatory	String
contractTtl	Time to live (in milliseconds) for the contract.	Mandatory	Number
signerdetail	Details of signers for the contract.	Mandatory	Array of Objects
callbackUrl	URL for callback upon contract completion.	Mandatory	String
callbackUrlAuthorizationHeader	Authorization header for the callback URL.	Optional	String
signerCallbackUrl	URL for individual signer callbacks.	Optional	String
callbackExtraParameter	Extra parameters for the callback.	Optional	Array of Strings
fileTtl	Time to live for the uploaded files (e.g., "2 days").	Mandatory	String
estamp	Electronic stamp details for the contract.	Optional	Object

Field Name	Description	Mandatory/Optional	Type
signerId	Unique identifier for the signer.	Mandatory	String
signerName	Name of the signer.	Mandatory	String
signatureType	Type of signature for the signer.	Mandatory	String
uidLastFourDigits	Last four digits of signer's UID.	Mandatory	String
signerYearOfBirth	Year of birth of the signer.	Mandatory	String
signerGender	Gender of the signer.	Mandatory	String
signatures	Signature details for the signer.	Mandatory	Array of Objects
esignUrl	URL for the e-sign process of the signer.	Mandatory	String

Field Name	Description	Mandatory/Optional	Type
pageNo	Page number(s) for the signature.	Mandatory	Array
signaturePosition	Position(s) of the signature on the page.	Mandatory	Array of Strings
xCoordinate	X-coordinate(s) of the signature.	Optional	Array of Numbers
yCoordinate	Y-coordinate(s) of the signature.	Optional	Array of Numbers

Field Name	Description	Mandatory/Optional	Type
type	Type of electronic stamp (e.g., eChallan).	Mandatory	String
secondPartyName	Name of the second party in the stamp.	Mandatory	String
firstPartyName	Name of the first party in the stamp.	Mandatory	String
stateCode	State code for the stamp.	Mandatory	String
articleCode	Article code for the stamp.	Mandatory	String
purposeOfStampDuty	Purpose of the stamp duty.	Mandatory	String
amount	Amount of stamp duty.	Mandatory	Number
location	Location of the stamp on the document.	Mandatory	String
custmonDefacement	Customization option for defacement.	Mandatory	String
message	Message for the stamp.	Mandatory	String

Parameter	Type	Description
name	String	In case of errors, it will have the value "error". It represents an error.
message	String	Message for the error
reason	String	Reasons for the error
type	String	Type of error
statusCode	String	Status code of the error

Error Code	Error Message	Explanation
400	Bad Request	Input parameter has a missing required parameter or invalid inputs
401	Authorization Failed	Authorization token is invalid
500	Internal Server Error	Internal error at Signzy, Please reach out to [email protected]

Updated 12 Apr 2024

Did this page help you?

Generate Contract API

Pull Contract API