Pull Contract API

14min

Introduction
The Pull Contract API offers a streamlined way to retrieve comprehensive details about a contract using its unique Contract ID. This API provides real-time updates on signer statuses, including completion, pending signatures, and deletions. With this information, you can efficiently track the signing progress, manage signed and deleted signers, and gauge the overall contract completion status.
Key Features:
Retrieve contract details using Contract ID.
Track real-time signer statuses.
Monitor completed, pending, and deleted signers.
Get an overview of contract completion status.
Seamlessly integrate with existing systems.
The Pull Contract API simplifies contract management by providing actionable insights into signer activities and overall contract progress.
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/pullData' \
--header 'Authorization: ***************************' \
--header 'Content-Type: application/json' \
--data '{
    "contractId": "********************************",
    "filesInBase64": {
        "finalSignedContract": true,
        "auditCertificateUrl": false,
        "signerData": [
            {
                "signerId": "",
                "preVerification": {
                    "capturedImage": false
                },
                "postVerification": {
                    "capturedImage": false
                }
            }
        ]
    }
}'
curl --location 'https://api.signzy.app/api/v3/contract/pullData' \
--header 'Authorization: ***************************' \
--header 'Content-Type: application/json' \
--data '{
    "contractId": "********************************",
    "filesInBase64": {
        "finalSignedContract": true,
        "auditCertificateUrl": false,
        "signerData": [
            {
                "signerId": "",
                "preVerification": {
                    "capturedImage": false
                },
                "postVerification": {
                    "capturedImage": false
                }
            }
        ]
    }
}'
﻿
Input Parameters
Here's a table explaining the structure and meaning of each key in the JSON object you provided:
Key
Description
Type
M/O
contractId
Unique identifier for the contract.
String
M
filesInBase64
Object containing details about files which is required in Base64
Object
O
finalSignedContract
Indicates whether the final signed contract is required in base64 format.
Pass true if it is requied in Base64
Boolean
O
auditCertificateUrl
Indicates whether the audit certificate URL is requieed in base64 format.
Pass true if it is requied in Base64
Boolean
O
signerData
Array containing details about the signer files which is requied in Base64
Array of Objects
O
signerId
Identifier for the signer.
The Id of the Signer for which the details is required
String
O
preVerification
Contains the details of the file in PreVerfication which is required in Base64
Object
O
capturedImage
Boolean indicating if the captured image of liveliness verification which happened in PreVerification step is required in Base64 
Pass it as true if Base64 is required
Boolean
O
postVerification
Contains the details of the file in PostVerfication which is required in Base64
Object
O
capturedImage
Boolean indicating if the captured image of liveliness verification which happened in PostVerification step is required in Base64 
Pass it as true if Base64 is required
Boolean
O
Only one file can be pulled in Base64 at one time. Multiple files can't be pulled by passing the values as true.
Sample Response
200
Base64 Output Format
{
    "contractId": "",
    "files": {
        "finalSignedContract": "",
        "auditCertificateUrl": "",
        "signerData": [
            {
                "signerId": "",
                "preVerification": {
                    "capturedImage": ""
                },
                "postVerification": {
                    "capturedImage": ""
                }
            }
        ]
    }
}
{
    "contractId": "",
    "files": {
        "finalSignedContract": "",
        "auditCertificateUrl": "",
        "signerData": [
            {
                "signerId": "",
                "preVerification": {
                    "capturedImage": ""
                },
                "postVerification": {
                    "capturedImage": ""
                }
            }
        ]
    }
}
﻿
Output Parameters
Field Name
Description
Type
contractId
Unique identifier for the contract.
String
initialSignerCount
Number of initial signers for the contract.
Number
signedSignerCount
Number of signers who have already signed the contract.
Number
deletedSignerCount
Number of signers who have been deleted from the contract.
Number
contractName
Name of the contract.
String
contractExecuterName
Name of the contract executor.
String
successRedirectUrl
URL to redirect after successful contract execution.
String
failureRedirectUrl
URL to redirect in case of contract execution failure.
String
callbackUrl
URL for callback upon contract completion.
String
signerCallbackUrl
URL for individual signer callbacks.
String
contractTtl
Time to live (in milliseconds) for the contract.
Number
initialContract
URL to the initial contract document.
String
initialContractHash
Initial hash of the contract.
String
finalSignedContract
URL to the final signed contract document.
String
finalSignedContractHash
Hash of the final signed contract.
String
isCompleted
Status indicating whether the contract is completed (true) or not (false).
Boolean
contractCompletionTime
Timestamp indicating when the contract was completed.
String
estamp
Electronic stamp details for the contract.
Object
signerdetail
Details of signers for the contract.
Array of Objects
esignAttempts
Entire session history and details of the signer signing attempts
Array of objects
notificationDetails
History of all the notifications for all different evemts sent to the particular signer/reviewer along with their delivery status, timestamp.
Notification events for signer:
SENDSIGNINGLINK - Signing link notification
SENDCONFIRMATION - Signer's signing confirmation
SENDAUDIT - Contract completion confirmation
SENDOTP - OTP carrying notification
SENDREMINDER - Reminder with signing link
Notification events for reviewer:
SENDREVIEWER - Contract Review link notification

Notification status can be:
SUCCESS
FAILED
PENDING 
Possible status descriptions  - Link﻿
Array of objects
deletedsignerdetail
Details of deleted signers from the contract.
Array of Objects
contractStatus
Current status of the contract.
The contract status can be:
INITIATED
PENDING
COMPLETED
REJECTED
DELETED
CANCELLED
EXPIRED
﻿Know more about contract status﻿
String
customerMailList
List of email IDs which will receive the details.
Array of Strings
customerMailListVisibility
Consist customer mail list in cc or bcc that was passed.
String
eStamp:
Field Name
Description
Type
transactionId
Unique identifier for the eStamp transaction.
String
estampStatus
Status of the eStamp transaction.
String
transactionResult
Result details of the eStamp transaction.
Object
Transaction Result (within eStamp):
Field Name
Description
Type
challanNo
Challan number for the eStamp transaction.
String
challanSubNo
Sub-challan number for the eStamp transaction.
String
eStampedFile
URL to the eStamped contract document.
String
SignerDetail:
Field Name
Description
Type
signerName
Name of the signer.
String
signerGender
Gender of the signer.
String
signerYearOfBirth
Year of birth of the signer.
String
signerId
Unique identifier for the signer.
String
signatureType
Type of signature for the signer.
String
contractLastSignTime
Timestamp of the signer's last sign attempt.
String
status
Status of the signer (e.g. FAIL, PENDING, SUCCESS).
String
errorMessage
Error message related to the signer.
String
aadhaarStatus
Aadhaar status of the signer.
String
aadhaarErrorMessage
Error message related to Aadhaar verification.
String
matchScoreResult
Result of match score for the signer.
Object
signerIP
IP address of the signer.
String
noOfSuccessfulAttempts
Number of successful sign attempts by the signer.
Number
noOfFailureAttempts
Number of failed sign attempts by the signer.
Number
signerSignedContract
URL to the signer's signed contract document.
String
signerSignedContractHash
Hash of the signer's signed contract.
String
esignAttempts
Details of e-sign attempts by the signer.
Array of Objects
eSign Attempts:
Field Name
Description
Type
errorMessage
Error message, if any
String
aadhaarStatus
Aadhaar status
String
aadhaarErrorMessage
Error message related to Aadhaar
String
signerDscData
Object containing signer DSC data
Object
signerDscData.state
State information
String
signerDscData.pincode
Pincode information
String
signerDscData.dnQualifier
Distinguished Name qualifier
String
signerDscData.yob
Year of birth
String
signerDscData.gender
Gender
String
signerDscData.uidLastFourDigits
Last four digits of UID
String
signerDscData.x500UniqueIdentifier
X.500 unique identifier
String
signerDscData.aadhaarToken
Aadhaar token
String
signerDscData.pseudonym
Pseudonym
String
signerDscData.aadhaarType
Type of Aadhaar
String
signerDscData.country
Country
String
signerDscData.name
Name
String
Sample Errors
400
400
401
404
500
404
{
    "name": "error",
    "message": "contract not completed",
    "reason": "Not Found",
    "type": "Not Found",
    "statusCode": 404
}

{
    "name": "error",
    "message": "contract not completed",
    "reason": "Not Found",
    "type": "Not Found",
    "statusCode": 404
}
﻿
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
404
Not Found
Contract ID eneterd is not found in the database
500
Internal Server Error
Internal error at Signzy, Please reach out to [email protected]
﻿

Key	Description	Type	M/O
contractId	Unique identifier for the contract.	String	M
filesInBase64	Object containing details about files which is required in Base64	Object	O
finalSignedContract	Indicates whether the final signed contract is required in base64 format. Pass true if it is requied in Base64	Boolean	O
auditCertificateUrl	Indicates whether the audit certificate URL is requieed in base64 format. Pass true if it is requied in Base64	Boolean	O
signerData	Array containing details about the signer files which is requied in Base64	Array of Objects	O
signerId	Identifier for the signer. The Id of the Signer for which the details is required	String	O
preVerification	Contains the details of the file in PreVerfication which is required in Base64	Object	O
capturedImage	Boolean indicating if the captured image of liveliness verification which happened in PreVerification step is required in Base64 Pass it as true if Base64 is required	Boolean	O
postVerification	Contains the details of the file in PostVerfication which is required in Base64	Object	O
capturedImage	Boolean indicating if the captured image of liveliness verification which happened in PostVerification step is required in Base64 Pass it as true if Base64 is required	Boolean	O

Field Name	Description	Type
contractId	Unique identifier for the contract.	String
initialSignerCount	Number of initial signers for the contract.	Number
signedSignerCount	Number of signers who have already signed the contract.	Number
deletedSignerCount	Number of signers who have been deleted from the contract.	Number
contractName	Name of the contract.	String
contractExecuterName	Name of the contract executor.	String
successRedirectUrl	URL to redirect after successful contract execution.	String
failureRedirectUrl	URL to redirect in case of contract execution failure.	String
callbackUrl	URL for callback upon contract completion.	String
signerCallbackUrl	URL for individual signer callbacks.	String
contractTtl	Time to live (in milliseconds) for the contract.	Number
initialContract	URL to the initial contract document.	String
initialContractHash	Initial hash of the contract.	String
finalSignedContract	URL to the final signed contract document.	String
finalSignedContractHash	Hash of the final signed contract.	String
isCompleted	Status indicating whether the contract is completed (true) or not (false).	Boolean
contractCompletionTime	Timestamp indicating when the contract was completed.	String
estamp	Electronic stamp details for the contract.	Object
signerdetail	Details of signers for the contract.	Array of Objects
esignAttempts	Entire session history and details of the signer signing attempts	Array of objects
notificationDetails	History of all the notifications for all different evemts sent to the particular signer/reviewer along with their delivery status, timestamp. Notification events for signer: SENDSIGNINGLINK - Signing link notification SENDCONFIRMATION - Signer's signing confirmation SENDAUDIT - Contract completion confirmation SENDOTP - OTP carrying notification SENDREMINDER - Reminder with signing link Notification events for reviewer: SENDREVIEWER - Contract Review link notification Notification status can be: SUCCESS FAILED PENDING Possible status descriptions - Link	Array of objects
deletedsignerdetail	Details of deleted signers from the contract.	Array of Objects
contractStatus	Current status of the contract. The contract status can be: INITIATED PENDING COMPLETED REJECTED DELETED CANCELLED EXPIRED Know more about contract status	String
customerMailList	List of email IDs which will receive the details.	Array of Strings
customerMailListVisibility	Consist customer mail list in cc or bcc that was passed.	String

Field Name	Description	Type
transactionId	Unique identifier for the eStamp transaction.	String
estampStatus	Status of the eStamp transaction.	String
transactionResult	Result details of the eStamp transaction.	Object

Field Name	Description	Type
challanNo	Challan number for the eStamp transaction.	String
challanSubNo	Sub-challan number for the eStamp transaction.	String
eStampedFile	URL to the eStamped contract document.	String

Field Name	Description	Type
signerName	Name of the signer.	String
signerGender	Gender of the signer.	String
signerYearOfBirth	Year of birth of the signer.	String
signerId	Unique identifier for the signer.	String
signatureType	Type of signature for the signer.	String
contractLastSignTime	Timestamp of the signer's last sign attempt.	String
status	Status of the signer (e.g. FAIL, PENDING, SUCCESS).	String
errorMessage	Error message related to the signer.	String
aadhaarStatus	Aadhaar status of the signer.	String
aadhaarErrorMessage	Error message related to Aadhaar verification.	String
matchScoreResult	Result of match score for the signer.	Object
signerIP	IP address of the signer.	String
noOfSuccessfulAttempts	Number of successful sign attempts by the signer.	Number
noOfFailureAttempts	Number of failed sign attempts by the signer.	Number
signerSignedContract	URL to the signer's signed contract document.	String
signerSignedContractHash	Hash of the signer's signed contract.	String
esignAttempts	Details of e-sign attempts by the signer.	Array of Objects

Field Name	Description	Type
errorMessage	Error message, if any	String
aadhaarStatus	Aadhaar status	String
aadhaarErrorMessage	Error message related to Aadhaar	String
signerDscData	Object containing signer DSC data	Object
signerDscData.state	State information	String
signerDscData.pincode	Pincode information	String
signerDscData.dnQualifier	Distinguished Name qualifier	String
signerDscData.yob	Year of birth	String
signerDscData.gender	Gender	String
signerDscData.uidLastFourDigits	Last four digits of UID	String
signerDscData.x500UniqueIdentifier	X.500 unique identifier	String
signerDscData.aadhaarToken	Aadhaar token	String
signerDscData.pseudonym	Pseudonym	String
signerDscData.aadhaarType	Type of Aadhaar	String
signerDscData.country	Country	String
signerDscData.name	Name	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
404	Not Found	Contract ID eneterd is not found in the database
500	Internal Server Error	Internal error at Signzy, Please reach out to [email protected]

Updated 09 Jan 2025

Did this page help you?

Initiate Contract API

Delete Signer API