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	[ { "recipient_1": "john@zylker.com", "recipient_name": "John", "action_type": <approve\|sign\|view\|in_person_sign>, "language": "en”, "delivery_type": [{ "type": "sms", "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", "countrycode" : "+91", "phonenumber": "1234567890" }], “verification_info": { "type": <email\|sms\|offline> } }, ... ]	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.
sign_org_id	String	Specify the Zoho Sign organization ID from which the document is sent for signing.
sign_request_type_id	String	Specify the Zoho Sign document type ID.

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

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

CRM

Voice

Sign

Forms

Bigin

SalesIQ

Bookings

RouteIQ

Thrive

CRM Plus

Zakya

Campaigns

Voice

Sign

Forms

Social

Survey

SalesIQ

Sites

Backstage

PageSense

Marketing Automation

LandingPage

Webinar

LeadChain

Domains

CommunitySpaces

Thrive

Publish

Marketing Plus

Commerce

Zakya

Desk

Assist

Voice

SalesIQ

Bookings

FSM

Lens

Solo

Service Plus

Books

Expense

Sign

Inventory

Invoice

Billing

Payroll

Commerce

Checkout

Practice

Solo

Payments

Finance Plus

Mail

Voice

Sign

WorkDrive

Bookings

Cliq

Notebook

Meeting

Connect

Learn

Office Integrator

Writer

TeamInbox

ZeptoMail

Show

Tables

Sheet

Office Suite

Calendar

ToDo

PDF Editor

Workplace

Vani

Expense

Recruit

People