Sign API

Purpose  

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

Prerequisites

Before using this API, you need to access the document once from Zoho Writer's UI.

Steps to access the template in Zoho Writer

  1. Open Zoho Writer dashboard and select the document you wish to send for signature collection.

  2. Click the hamburger menu -> Automate tab.

Note: 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

Request Parameters

ParameterValueDescription
Mandatory Parameter
recipients

JSON Array:

[
{
"recipient_1": "john@zylker.com",
"recipient_name": "John",
"action_type": <approve|sign|view|in_person_sign>,
"language": "en”,
 "delivery_type": [{
   "type": "<sms|whatsapp>",
   "countrycode" : "+91",
   "phonenumber": "1234567890" 
  }], 
private_notes”: “Hey!Please sign this document”
},

{
  "recipient_2": "amelia@zylker.com",
  "recipient_name": "Amelia",
 "action_type": <approve|sign|view|in_person_sign>,
"language": "fr",
 "delivery_type": [{
   "type": "<sms|whatsapp>",
   "countrycode" : "+91",
   "phonenumber": "1234567890" 
  }], 
verification_info": {
"type": <email|sms|offline|whatsapp>
  }
},
...
]

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.

 

Note: You can configure multiple delivery type for a recipient via 'delivery_type' key.

subjectStringSpecify the subject for the email.
messageStringProvide a content for the mail.
signed_document_nameStringSpecify a name for the signed document.
Optional Parameters
attachmentsFile Object To send or provide any attachments in the mail (Maximum of 3 files can be attached).
is_sequentialtrue / falseSpecify the order in which the document singing or approving needs to take place.
reminder_periodIntegerTo send reminder for signing or approving the document every 'n' days.
expire_inInteger

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_urlStringSpecify the location where you would like to receive the notification once the document has been signed.
sign_org_idStringSpecify the Zoho Sign organization ID from which the document is sent for signing.
sign_request_type_idString

Specify the Zoho Sign document type ID.

recipients

KeysTypePossible ValuesDefault Value
Mandatory Parameters
recipient_nstring

recipient_1, recipient_2, ... , recipient_10

Note: Upto 10 recipients are supported as of now.

Atleast 1 recipient email address
Optional Parameters
action_typestringapprove/sign/view/in_person_signsign
languagestringzh / 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)stringsms / whatsapp

If this key is not passed, notifications will be sent to signers via email by default.

 

If the key is passed, notifications will be sent via email as well as the specified delivery type.

delivery_type

Possible valuesTypeExample
smsJSON Array{
"type": "sms",
"countrycode": "+91",
"phonenumber": "1234567890"
}
whatsappJSON Array{
"type": "whatsapp",
"countrycode": "+91",
"phonenumber": "1234567890"
}

verfication_info (optional)

Possible valuesTypeExample
emailJSON Object{
"type":"email"
}
smsJSON Object{
"type": "sms",
"countrycode": "+91",
"phonenumber": "1234567890"
}
offlineJSON Object
{
"type": "offline",
"code": "123456" //6-digit code mandatory
}
whatsappJSON Object{
"type": "whatsapp",
"countrycode": "+91",
"phonenumber": "1234567890"
}

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 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.

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>
}