Initiate Contract API

12 min

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

curl --location 'https://api-preproduction.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": "",
    "signerCallbackUrl": "",
    "signerCallbackUrlAuthorizationHeader": "",
    "signerdetail": [
        {
            "signerName": "Mayank",
            "signerEmail": "",
            "signerGender": "Male",
            "signatureType": "SMARTESIGN",
            "signatures": [
                {
                    "pageNo": [
                        "All"
                    ],
                    "signaturePosition": [
                        "BottomLeft"
                    ]
                }
            ]
        },
        {
            "signerName": "Ashish",
            "signerEmail": "",
            "signerGender": "Female",
            "signatureType": "SMARTESIGN",
            "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
                    ]
                }
            ]
        }
    ],
    "workflow": true,
    "isParallel": false,
    "redirectTime": 5,
    "locationCaptureMethod": "ip",
    "signOnStamp": true,
    "initiationEmailSubject": "Please sign the document received on your email",
    "customerMailList": [
        ""
    ],
    "emailPdfCustomNameFormat": "SIGNERNAME",
    "logoUrl": ""
}'

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)
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
signerCallbackUrl	String	Optional	Signer Callback url for posting data once Aadhaar ESign Process for the particular transaction is completed by the signer.
signerCallbackUrlAuthorizationHeader	String	Optional	If the Signer Callback URL uses authentication, pass the authroization header value in this key
signerdetail	Array of Objects	Mandatory	Details about all the signers.
signerName	String	Mandatory	Name of the signer.
signerEmail	String	Optional	If this value is passed, email will be used to communicate with the end customers
signerGender	String	Optional	Gender of the signer (Male/Female/Transgender).
signatureType	String	Mandatory	The type of signatures. The possible values are smartesign
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
workflow	Boolean	Optional	Pass value as true, if you want the workflow
isParallel	Boolean	Optional	Pass value as true, if you want the parallel signing By default, it will be a sequential signing
redirectTime	Number	Optional	The time after which it redirects. The time is in seconds. Deafult value - 5 seconds
locationCaptureMethod	String	Optional	It can take two value - ip, browser
signOnStamp	Boolean	Optional	Pass value as true, if you want signature to also appear on affixed stamp papers By default, it will be false.
initiationEmailSubject	String	Optional	It subject line of the email that will be sent to customers
customerMailList	Array of Strings	Optional	List of email IDs which will receive the details
emailPdfCustomNameFormat	String	Optional	Custom Name format of the PDF sent in email
logoUrl	String	Optional	Logo of the customer which will be used to whitelablel

Sample Response

{
    "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": "SMARTESIGN",
            "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": "SMARTESIGN",
            "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",
}

Output Parameters

Field Name	Description	Mandatory/Optional	Type
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
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
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

Sample Errors

{
    "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]