Sign API
Purpose
Using this API, you can send a document to get signed and track its status.
HTTP Request URL
https://{zohoapis_domain}/writer/api/v1/documents/{{document_id}}/sign
Request Parameters
| Parameter | Value | Description |
| Mandatory Parameter | ||
| recipients | [ { | Specify the recipients to whom the document needs to be sent to get signed, in person signed, approved or viewed in the form of a JSON Array.
You can also specify the notification type and the language in which the notification email needs to be sent to the signers. It is also possible verify and provide private notes to the recipients.
Supported languages are: Chinese(zh), Dutch(nl), English(en), French(fr), German(de), Italian(it), Japanese(ja), Polish(pl), Portuguese(pt), Russian(ru), Spanish(es), Swedish(sv).
You can refer the sample JSON Array here. |
| subject | String | Specify the subject for the email. |
| message | String | Provide a content for the mail. |
| signed_document_name | String | Specify a name for the signed document. |
| Optional Parameters | ||
| attachments | File Object | To send or provide any attachments in the mail (Maximum of 3 files can be attached). |
| is_sequential | true / false | Specify the order in which the document singing or approving needs to take place. |
| reminder_period | Integer | To send reminder for signing or approving the document every 'n' days. |
| expire_in | Integer | Specify the document expiry date. Maximum limit: 99 days |
| prefill_data | { “name”:”Amelia”, // text field “gender”:”Female” //radio field “course”:”Computer Science”, //dropdown field “bus”:”true” //checkbox field } | Define the data that needs to be pre-filled in the document.
For Example: {"name":"Amelia"} - The value 'Amelia' will be pre-filled in the signer field with label 'name'.
Note:
1. As of now, prefill value support is provided only for text, checkbox, radio and dropdown fileds.
2. Only signer fields with labels can be pre-filled. |
| callback_url | String | Specify the location where you would like to receive the notification once the document has been signed. |
recipients
| Parameter | Type | Possible Values | Default Value |
| recipient_n | string | recipient_1, recipient_2, ... , recipient_10 Note: Upto 10 recipients are supported as of now. | john@zylker.com |
| action_type | string | approve/sign/view/in_person_sign | sign |
| language | string | zh / nl / en / fr / de / it / ja / pl / pt / ru / es / sv | This option is available only for Zoho Sign Premium Plan users.
For Free Plan users, the notification email will be sent in their account language by default. |
| delivery_type (type) | string | sms | If this key is not passed, the notification will be sent to the signers as email by default. |
Note:
- To use this API, an OAuth token should be generated with the scopes ZohoWriter.documentEditor.ALL and ZohoSign.documents.ALL.
- Check out the prerequisites needed to make the Sign API work, here.
- In Writer, we achieve the 'Digital Signature' by using our Zoho Sign API internally. The credits will be consumed based on the Zoho Sign API subscription plan. To know more about the Zoho Sign Credits Add-on, check here.
- Optional parameters are not supported in signDocument deluge task. To make use of them, you need to use the invokeURL task with this API.
- This API will be charged from 1st February 2023. For more details, check here.
- Possible errors of Sign API are listed here.
Curl
Sample Request
Copiedcurl --location --request POST "https://www.zohoapis.com/writer/api/v1/documents/ponazfea04477109f4681a831e7177d96bc40/sign" \
--header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
--form "recipients=[{\"recipient_1\": \"john@zylker.com\", \"recipient_name\": \"John\", \"action_type\": \"sign\",\"language\": \"en\",\"private_notes\": \"Hey!Please sign this document\"}, {\“recipient_2\":\"amelia@zylker.com\", \"action_type\": \"approve\",\"language\": \"fr\"}]" \
--form "subject=Document has been signed" \
--form "message=Please sign the document" \
--form "signed_document_name=Signed Copy" \
--form "attachments=" \
--form "is_sequential=true" \
--form "reminder_period=15" \
--form "expire_in=5" \
--form "prefill_data={\"name\": \"Amelia\", \"gender\": \"Female\", \"course\": \"CSE\",\"bus\"} \
--form "callback_url=https://example.com" \
Deluge
Snippet 1 - Sign document without common attachments
Copiedrecipient1 = Map();
recipient1.put("recipient_1","amelia@zylker.com");
recipient1.put("recipient_name","Amelia");
recipient1.put("action_type","sign");
recipient2 = Map();
recipient2.put("recipient_2","john@zylker.com");
recipient2.put("recipient_name","John");
recipient2.put("action_type","approve");
recipient3 = Map();
recipient3.put("recipient_3","kim@zylker.com");
recipient3.put("recipient_name","Kim");
recipient3.put("action_type","view");
recipients.add(recipient1);
recipients.add(recipient2);
recipients.add(recipient3);
param = map();
param.put("recipients",recipients);
param.put("subject","Reg Document Sign");
param.put("message","Please find the document to be signed here");
param.put("signed_document_name", "Signed document");
param.put("is_sequential", "true"); //optional
param.put("reminder_period", "15"); //optional
param.put("expire_in", "30"); //optional
param.put("language", "nl"); //optional
url = "https://www.zohoapis.com/writer/api/v1/documents/" + documentid + "/sign";
documentObj = invokeurl
[
url :url
type :POST
params:param
connection:"<connection_name>"
];Snippet 2 - Sign document with common attachments
CopiedsignerList = {};
signerObj1 = Map();
signerObj1.put("recipient_1”,”amelia@zylker.com");
signerObj1.put("recipient_name”,”Amelia”);
signerObj1.put("action_type","sign");
signerObj1.put("language","en");
signerList = {signerObj1};
singerlistStr = "[" + signerList.toString() + "]";
commonAttachmentFile1 = invokeurl
[
url :"https://calibre-ebook.com/downloads/demos/demo.docx"
type :GET
];
info commonAttachmentFile1;
paramList = list();
paramMap1 = {"paramName":"attachments","content":commonAttachmentFile1};
paramMap2 = {"paramName":"subject","content":"Reg Document Sign","stringPart":"true"};
paramMap3 = {"paramName":"recipients","content":singerlistStr,"Content-Type":"application/json","stringPart":"true"};
paramMap4 = {"paramName":"message","content":"Please find the document to be signed here","stringPart":"true"};
paramMap5 = {"paramName":"signed_document_name","content":"signCommonAttach","stringPart":"true"};
paramList.add(paramMap1);
paramList.add(paramMap2);
paramList.add(paramMap3);
paramList.add(paramMap4);
paramList.add(paramMap5);
documentObj = invokeurl
[
url :"https://www.zohoapis.com/writer/api/v1/documents/olce2ef696f1810ee46ed8331f25aaece75dd/sign"
type :POST
files:paramList
connection:"<connection_name>"
];
info documentObj;
Snippet 3 - Sign Document Task
Copiedrecipient1 = Map();
recipient1.put("recipient_1", "amelia@zylker.com");
recipient1.put("recipient_name", "Amelia");
recipient1.put("action_type", "sign");
recipient2 = Map();
recipient2.put("recipient_2","john@zylker.com");
recipient2.put("recipient_name", "John");
recipient2.put("action_type", "approve");
recipient3 = Map();
recipient3.put("recipient_3","kim@zylker.com");
recipient3.put("recipient_name", "Kim");
recipient3.put("action_type", "view");
email = List();
email.put(recipient1);
email.put(recipient2);
email.put(recipient3);
inputMap = Map();
inputMap.put("subject", "Document to sign");
inputMap.put("message", "Please verify and sign the document");
response=zoho.writer.signDocument("3z7frc3fda95142ef45fbb9aadf220632b1d6", "zohosign", email, "Signed Document", inputMap, "<connection_name>");