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

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

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_inIntegerSpecify the document expiry date.
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.

recipients

ParameterTypePossible ValuesDefault Value
recipient_nstring

recipient_1, recipient_2, ... , recipient_10

Note: Upto 10 recipients are supported as of now.

john@zylker.com
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)stringsmsIf 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" \

Sample Response

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

Deluge

Snippet 1

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>");

Sample Response

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