Initiate Contract Query API

Introduction

Welcome to the Initiate Contract Query API. This API serves as a powerful tool for conducting efficient database searches based on unique reference IDs generated by the Initiate Contract API. The goal is to streamline the retrieval of contract-related information, utilizing a special UUID code (uniquereferenceId) given by clients for each request. It has to be 36 characters long unique reference ID (uniquereferenceId) passed by end clients to uniquely identify each request.

Key Features:

Efficient Searches: Conduct targeted searches within the database based on uniquereferenceId, ensuring rapid access to relevant data.
Universal Integration: Seamlessly integrate with existing systems, utilizing the uniquereferenceId as a consistent identifier across all transactions.
Scalability and Flexibility: Accommodate various contract management needs, from individual inquiries to bulk data retrieval, with scalability to support evolving requirements.
Secure Retrieval: Prioritize data security through robust authentication measures, ensuring authorized access to sensitive information.

Harness the capabilities of the Initiate Contract Query API to streamline contract management processes, enhance operational efficiency, and make informed decisions with confidence across finance, legal, and enterprise management domains.

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/initiateQuery' \
--header 'Authorization: ********************************' \
--header 'Content-Type: application/json' \
--data '{
    "x-uniqueReferenceId": ""
}'

Input Parameters

Key	Description	Type	Mandatory/Optional
x-uniqueReferenceId	Unique Reference Id of the Initiate Contract API 36 characters long, UUID number which has to be unique For example, 82541a35-d494-4fbb-97f3-e2323208986e	String	Mandatory

Sample Response

{
    "contractId": "3c54deeb-b91d-4893-8ec9-46573e85f45b",
    "initialSignerCount": 2,
    "signedSignerCount": 0,
    "deletedSignerCount": 0,
    "contractName": "dd",
    "contractExecuterName": "dd",
    "successRedirectUrl": "https://signzy.com",
    "failureRedirectUrl": "https://google.com",
    "callbackUrl": "https://qa.signzy.xyz/callback/mohitposts",
    "signerCallbackUrl": "https://qa.signzy.xyz/callback/mohitposts",
    "contractTtl": 10000,
    "initialContract": "https://staging-persist.signzy.tech/api/files/4879805/download/1a3018421e5b411687718238f8d045df60031ccea6404341a63c23d81aa29279.pdf",
    "initialContractHash": "51acd08565171da3a2e1f50b600df06b444ff18204e53103d2ef590688a3a39a",
    "finalSignedContract": "",
    "finalSignedContractHash": "",
    "isCompleted": false,
    "contractCompletionTime": "",
    "estamp": {
        "transactionId": "64d9c218374c36670d994286",
        "estampStatus": "PENDING",
        "transactionResult": {
            "challanNo": "NL0013",
            "challanSubNo": "NL0013-00001",
            "eStampedFile": "https://staging-persist.signzy.tech/api/files/4879805/download/1a3018421e5b411687718238f8d045df60031ccea6404341a63c23d81aa29279.pdf"
        }
    },
    "signerdetail": [
        {
            "signerName": "mohit",
            "signerEmail": "",
            "signerMobile": "",
            "signerGender": "male",
            "signerYearOfBirth": "0101",
            "signerId": "0ee176c4-39a1-4b9d-9923-85be82730ac4",
            "workflowUrl": "",
            "signatureType": "AADHAARESIGN-OTP",
            "additionalSignatureTypes": [],
            "contractLastSignTime": "",
            "status": "DRAFT",
            "errorMessage": "",
            "contractSendTime": "Wed May 29 2024 12:04:21 GMT+0530 (India Standard Time)",
            "aadhaarStatus": "",
            "aadhaarErrorMessage": "",
            "matchScoreResult": {},
            "signerIP": "",
            "noOfSuccessfulAttempts": 0,
            "noOfFailureAttempts": 0,
            "signerSignedContract": "",
            "signerSignedContractHash": "",
            "esignAttempts": []
        },
        {
            "signerName": "cdcdc",
            "signerEmail": "",
            "signerMobile": "",
            "signerGender": "NA",
            "signerYearOfBirth": "0101",
            "signerId": "93b6308c-0adc-4c8a-85ff-7b307439d74b",
            "workflowUrl": "",
            "signatureType": "AADHAARESIGN-OTP",
            "additionalSignatureTypes": [],
            "contractLastSignTime": "",
            "status": "PENDING",
            "contractSendTime": "Wed May 29 2024 12:04:21 GMT+0530 (India Standard Time)",
            "aadhaarStatus": "",
            "errorMessage": "",
            "aadhaarStatus": "",
            "aadhaarErrorMessage": "",
            "matchScoreResult": {},
            "signerIP": "",
            "noOfSuccessfulAttempts": 0,
            "noOfFailureAttempts": 0,
            "signerSignedContract": "",
            "signerSignedContractHash": "",
            "esignAttempts": [
                {
                    "errorMessage": "NA",
                    "aadhaarStatus": "1",
                    "aadhaarErrorMessage": "",
                    "signerDscData": {
                        "state": "KARNATAKA",
                        "pincode": "",
                        "dnQualifier": "",
                        "yob": "",
                        "gender": "Male",
                        "uidLastFourDigits": "",
                        "x500UniqueIdentifier": "",
                        "aadhaarToken": "",
                        "pseudonym": "",
                        "aadhaarType": "PERSONAL",
                        "country": "IN",
                        "name": ""
                    }
                }
            ]
        }
    ],
    "deletedsignerdetail": [],
    "x-uniqueReferenceId": ""
}

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
deletedsignerdetail	Details of deleted signers from the contract.	Array of Objects
x-uniqueReferenceId	Unique Reference Id of the Initiate Contract API 36 characters long, UUID number which has to be unique For example, 82541a35-d494-4fbb-97f3-e2323208986e	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
signerEmail	Email ID of the signer	String
signerMobile	Mobile number 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
workflowUrl	Signing URL Link	String
contractLastSignTime	Timestamp of the signer's last sign attempt.	String
additionalSignatureTypes	Additional Signature Type Methods	String
status	Status of the signer (e.g., DRAFT, PENDING).	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

{
    "name": "error",
    "message": "x-uniqueReferenceId length must be 12-32 characters long",
    "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
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]