Sign API

Purpose

Using this API, you can send a document to get signed and track its status.

Prerequisites

You need to access the sign template once before sending an API request using this template.

Quick Reference

Property	Value
Method	POST
Request URL	https://{zohoapis_domain}/writer/api/v1/documents/{document_id}/sign
Scopes	ZohoWriter.documentEditor.ALL, ZohoSign.documents.ALL
Rate Limit	See Writer API throttle limits

Parameters

Path Parameters

Parameter	Data Type	Mandatory/Optional	Description
document_id	String	Mandatory	Specify a unique id for the writer document.

Body Parameters

Parameter	Data Type	Mandatory/Optional	Description
recipients	JSONArray	Mandatory	List of recipients with recipient_n (email), recipient_name, action_type (approve/sign/view/in_person_sign), language, delivery_type (sms/whatsapp), private_notes, verification_info (email/sms/offline/whatsapp). Up to 10 recipients.
subject	String	Mandatory	Specify the subject for the email.
message	String	Mandatory	Provide a content for the mail.
signed_document_name	String	Mandatory	Specify a name for the signed document.
attachments	File Object	Optional	Attachments to send with the mail. Max 20 files, 10MB each, total 40MB.
is_sequential	Boolean	Optional	Specify the order of signing or approving.
reminder_period	Integer	Optional	Send reminders every 'n' days.
expire_in	Integer	Optional	Document expiry in days. Max 99 days.
prefill_data	JSONObject	Optional	Data to pre-fill in the document, e.g., {"name":"Amelia"}. Supports text, checkbox, radio, dropdown fields.
callback_url	String	Optional	URL to receive notification when document is signed.
sign_org_id	String	Optional	Zoho Sign organization ID.
sign_request_type_id	String	Optional	Zoho Sign document type ID.
allowed_cloud_provider_ids	JSONArray	Optional	IDs of allowed digital signature providers, e.g., [10, 25].

Notes

You need to access the template once before sending an API request. You need not access the template every time before you send an API request. HTTP Request URL https:// {zohoapis_domain} /writer/api/v1/documents/ {{document_id}} /sign
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 is subject to throttle limits. For details on the applicable rate limits, please refer to this help link.
This API will be charged from 1st February 2023. For more details, check here.
Possible errors of Sign API are listed here.
To know how to send the documents for signing via Whatsapp, checkout this help link.
To learn how to retrieve the signer group id, refer this help link.
For possible errors, refer to error codes.

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" \

Sample Response

Copied{
	"status": success, //or failed
	"sign_status_url": <URL>
}

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
];
commonAttachmentFile2 = invokeurl
[
	url :"http://homepages.inf.ed.ac.uk/neilb/TestWordDoc.doc"
	type :GET
];
commonAttachmentFile3 = invokeurl
[
	url :"https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
	type :GET
];
commonAttachmentFile2.setParamName("attachments");
commonAttachmentFile3.setParamName("attachments");
paramList = list();
paramMap1 = {"paramName":"attachments","content":commonAttachmentFile1};
paramMap2 = {"paramName":"attachments","content":commonAttachmentFile2};
paramMap3 = {"paramName":"attachments","content":commonAttachmentFile3};
paramMap4 = {"paramName":"subject","content":"Reg Document Sign","stringPart":"true"};
paramMap5 = {"paramName":"recipients","content":singerlistStr,"Content-Type":"application/json","stringPart":"true"};
paramMap6 = {"paramName":"message","content":"Please find the document to be signed here","stringPart":"true"};
paramMap7 = {"paramName":"signed_document_name","content":"signCommonAttach","stringPart":"true"};
paramList.add(paramMap1);
paramList.add(paramMap2);
paramList.add(paramMap3);
paramList.add(paramMap4);
paramList.add(paramMap5);
paramList.add(paramMap6);
paramList.add(paramMap7);
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>");

Sample Response

Copied{
	"status": success, //or failed
	"sign_status_url": <URL>
}