Signing

Smart-ID signing service allows your customers to fill in the blanks in document template and sign the document right after that.

Example form signing: Demo Contract

To get started go HERE and create your first contract template. Then just copy-paste piece of code (iFrame) to your webpage and that’s it.

Enhanced contract templates

It is also possible to personalize the contract before showing it to the customer and asking him to sign it. It is useful if you want to pre-fill the contract with products or services that customer wants to buy. Pre-filling fields can be done over API query https://id.smartid.ee/api/v2/prepare_external_contract

This call must have client_id and secret values that you got when you registered your website with Smart ID. In addition there is GET parameter tag_values that is url encoded JSONobject that contains values of the tags defined in the original contract. Field values are remembered up to 24h, after this time passes the API call must be done again to get new code.

Example call is 
https://id.smartid.ee/api/v2/prepare_external_contract?client_id=j9..oE&secret=Wh..Ix&tag_values=%7B%22Firstname%22%3A%22Toomas%22%2C%22Lastname%22%3A%22Ilves%22%7D

Returned value is also JSON object with status either “OK” or “error”. If status is “OK” then there is another field “code” which value is needed in next step where you redirect the customer to sign the contract page. If the status is “error” then it includes “message” which contains details of what exactly went wrong.

Final step is to customize the signing page iframe url parameters and add the code value from the first step. Example sign page url with some blanks prefilled by the API call is https://id.smartid.ee/sign_contract?client_id=j9FXBpH0SMfipcDoArwxbq8ipF7xqiex&contract_id=5&code=K3kCchQxer97IGX8W1NcCQ2OITHc0XCtcPP4wccy

Custom document signing

In some cases the document template still does not give you enough flexibility. In this case it is possible to sign your own prepared PDF. Process contains 2 steps like enhanced contract templates.

Firstly document will be sent via HTTP POST with 3 mandatory URL parameters: client_id, secret and filename. client_id and secret are taken from Smart ID admin and filename can be whatever you like it to be in the signed doc. Call is sent to https://id.smartid.ee/api/v2/prepare_external_doc?client_id=j9FXBpH0SMfipcDoArwxbq8ipF7xqiex&secret=j9FXBpH0SMfipcDoArwxbq8ipF7xqiex&filename=my_doc_to_be_signed.pdf . Document content will be POST call body in base64 encoded format.

Response to above call is JSON. If successful then the status will be OK and doc_id value is string like {“status”:”OK”,”doc_id”:”rawaQxqrlYrsaGvslt7JFFCcMYztXHHwedFMPbze”} . If there is error then status is error with message like {“status”:”error”,”message”:”Missing filename for the document”} .

Second step is redirecting the customer to the signing page. Page can also be embedded in the iFrame for smoother experience. URL for the signing page needs to have 2 GET parameters: client_id and doc_id. Example of the signing page URL is this https://id.smartid.ee/sign_contract_external?client_id=j9FXBpH0SMfipcDoArwxbq8ipF7xqiex&doc_id=rawaQxqrlYrsaGvslt7JFFCcMYztXHHwedFMPbze

Adding signature to existing signed file

If you need to sign file by multiple people and you have the signed bdoc or asice container and need to add signature there then follow these steps

Prepare the bdoc or asice file for adding the signature. Send HTTP POST with 3 params client_id, secret and filename. POST body will be json with base64 encoded container value. {“container”:”UEsDBBQAAAgAAHI6z06KIflFHwAA…”}. Call is sent to https://id.smartid.ee/api/v2/prepare-add-signature?client_id=j9FXBpH0SMfipcDoArwxbq8ipF7xqiex&secret=j9FXBpH0SMfipcDoArwxbq8ipF7xqiex&filename=my_doc_to_be_signed.asice

Response to above call is JSON. If successful then the status will be OK and doc_id value is string like {“status”:”OK”,”doc_id”:”rawaQxqrlYrsaGvslt7JFFCcMYztXHHwedFMPbze”} . If there is error then status is error with message like {“status”:”error”,”message”:”Missing filename for the document”} .

Second step is redirecting the customer to the signing page. Page can also be embedded in the iFrame for smoother experience. URL for the signing page needs to have 2 GET parameters: client_id and doc_id. Example of the signing page URL is this https://id.smartid.ee/add-signature?client_id=j9FXBpH0SMfipcDoArwxbq8ipF7xqiex&doc_id=rawaQxqrlYrsaGvslt7JFFCcMYztXHHwedFMPbze

Optional url parameters

  • signature_redirect – tells where to redirect the user after signature is completed. You can customize it to your own needs and set the state needed after signing is finished, add items to add to shopping cart etc. signature_redirect=https://shop.com/add_to_cart.php?item=123
  • nodownload – By default after the signing the signed container will be downloaded to user computer. If this is not needed and you want to display signed file only in your own systems then set &nodownload=true
  • noemails – By default the notification e-mail is sent after every signature. If you are dealing with automated system and do not need to get e-mail every time then turn the e-mails off with &noemails=true
  • email_extra – If you prefer to get e-mail notifications and know who or what is the signature about then send any values here that you wish to add to the e-mail subject. Example &email_extra=Kersti+Kaljulaud+drone+flight+permission+application+drooniluba