Initiate Contract API

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 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" "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", "stampdutyvalue" "" "purposeofstampduty" "", "considerationprice" "", "stampdutypaidby" "", "amount" 1, "location" "middlecenter", "pageno" \[], "custmondefacement" "true", "message" "" }, "signercallbackurl" "", "signercallbackurlauthorizationheader" "test" "namematchthreshold" "0 90", "allowsigneryobmatch" true, "allowsignergendermatch" true }' 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 }' 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" } } 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 { "name" "error", "message" "invalid url extension", "reason" "validation error", "type" "bad request", "statuscode" 400 } 400 { "name" "error", "message" "successredirecturl is not allowed to be empty", "reason" "validation error", "type" "bad request", "statuscode" 400 } 400 { "name" "error", "message" "failureredirecturl is not allowed to be empty", "reason" "validation error", "type" "bad request", "statuscode" 400 } 400 { "name" "error", "message" "esignprovider must be one of \[nsdl, emudhra]", "reason" "validation error", "type" "bad request", "statuscode" 400 } 401 { "message" "invalid authentication credentials" } 500 { "error" { "name" "error", "message" "internal server error", "reason" "internal server error", "type" "internal server error", "statuscode" 500 } } 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 help\@signzy com