Pull Contract API

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 curl location 'https //api preproduction 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 } } ] } }' 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 } } ] } }' 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 { "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" "", "contractstatus" "pending", "customermaillist" \[], "customermaillistvisibility" "bcc", "callbackstatus" "", "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", "signergender" "male", "signeryearofbirth" "0101", "signerid" "0ee176c4 39a1 4b9d 9923 85be82730ac4", "signaturetype" "aadhaaresign otp", "contractlastsigntime" "", "status" "pending", "errormessage" "", "aadhaarstatus" "", "aadhaarerrormessage" "", "matchscoreresult" {}, "signerip" "", "noofsuccessfulattempts" 0, "nooffailureattempts" 0, "signersignedcontract" "", "signersignedcontracthash" "", "esignattempts" \[] }, { "signername" "cdcdc", "signergender" "na", "signeryearofbirth" "0101", "signerid" "93b6308c 0adc 4c8a 85ff 7b307439d74b", "signaturetype" "aadhaaresign otp", "contractlastsigntime" "", "status" "pending", "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" "" } } ], "notificationdetails" \[ { "event" "sendsigninglink", "transactiondetails" \[ { "channel" "email", "attempts" \[ { "timestamp" "wed dec 11 2024 12 45 40 gmt+0530 (india standard time)", "id" "xxxxxxxxxxxxxxxxxxxx", "status" "success", "description" "message has been successfully delivered to the user", "vendorid" "xxxxxxxxxxxxxxxxxx" } ] }, { "channel" "sms", "attempts" \[ { "timestamp" "wed dec 11 2024 12 45 41 gmt+0530 (india standard time)", "id" "xxxxxxxxxxxxxxxxxxxx", "status" "success", "description" "message successfully delivered to the user", "vendorid" "xxxxxxxxxxxxxxxxxxxx" } ] }, { "channel" "whatsapp", "attempts" \[ { "timestamp" "wed dec 11 2024 12 45 41 gmt+0530 (india standard time)", "id" "xxxxxxxxxxxxxxxxxxxx", "status" "success", "description" "message has been successfully delivered to the user", "vendorid" "xxxxxxxxxxxxxxxxxxxx" } ] } ] }, { "event" "sendconfirmation", "transactiondetails" \[ { "channel" "email", "attempts" \[ { "timestamp" "wed dec 11 2024 12 45 54 gmt+0530 (india standard time)", "id" "xxxxxxxxxxxxxxxxxxxx", "status" "success", "description" "message has been successfully delivered to the user", "vendorid" "xxxxxxxxxxxxxxxxxxxx" } ] }, { "channel" "sms", "attempts" \[ { "timestamp" "wed dec 11 2024 12 45 55 gmt+0530 (india standard time)", "id" "xxxxxxxxxxxxxxxxxxxx", "status" "success", "description" "message successfully delivered to the user", "vendorid" "xxxxxxxxxxxxxxxxxxxx" } ] }, { "channel" "whatsapp", "attempts" \[ { "timestamp" "wed dec 11 2024 12 45 55 gmt+0530 (india standard time)", "id" "xxxxxxxxxxxxxxxxxxxx", "status" "success", "description" "message has been successfully delivered to the user", "vendorid" "xxxxxxxxxxxxxxxxxxxx" } ] } ] }, { "event" "sendaudit", "transactiondetails" \[ { "channel" "email", "attempts" \[ { "timestamp" "wed dec 11 2024 12 45 56 gmt+0530 (india standard time)", "id" "xxxxxxxxxxxxxxxxxxxx", "status" "success", "description" "message has been successfully delivered to the user", "vendorid" "xxxxxxxxxxxxxxxxxxxx" } ] }, { "channel" "sms", "attempts" \[ { "timestamp" "wed dec 11 2024 12 45 57 gmt+0530 (india standard time)", "id" "xxxxxxxxxxxxxxxxxxxx", "status" "success", "description" "message successfully delivered to the user", "vendorid" "xxxxxxxxxxxxxxxxxxxx" } ] } ] } ] } ], "deletedsignerdetail" \[], "reviewerdetail" \[] } base64 output format { "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 { "name" "error", "message" "contractid length must be 36 characters long", "reason" "validation error", "type" "bad request", "statuscode" 400 } 400 { "name" "error", "message" "contractid is not allowed to be empty", "reason" "validation error", "type" "bad request", "statuscode" 400 } 401 { "message" "invalid authentication credentials" } 404 { "name" "error", "message" "contract not found", "reason" "not found", "type" "not found", "statuscode" 404 } 500 { "error" { "name" "error", "message" "internal server error", "reason" "internal server error", "type" "internal server error", "statuscode" 500 } } 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 help\@signzy com