Merge and Sign

Purpose

This API allows to send the merged documents for sign.

HTTP Request URL

https://{zohoapis_domain}/writer/api/v1/documents/{{document_id}}/merge/sign

Path Parameters

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

Body Parameters

Parameter	Data Type	Description
Mandatory Parameters
service_name	String	Specify the sign service name (zohosign).
filename	String	Specify a unique name for the signed document.
signer_data	[ { "recipient_1": "john@zylker.com", "action_type": <approve\|sign\|view\|in_person_sign>, "language": "en”, “private_notes”: “Hey!Please sign this document” }, { "recipient_2": "amelia@zylker.com", "action_type": <approve\|sign\|view\|in_person_sign>, "language": "fr", “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 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.
You can provide the data in any one of the below formats
merge_data	JSONObject	Pass a String value through 'data' key as JSON Array.
merge_data_csv_content	File	Provide the required csv content in your API request body.
merge_data_json_content	File	Provide the required json content in your API request body.
merge_data_csv_url	url	Provide the required csv url in your API request body.
merge_data_json_url	url	Provide the required json url in your API request body.
Optional Parameters
sign_in_order	Boolean (true / false)	Specify if we need to maintain the order of signing as mentioned.
message	String	Specify any message for the signer.
set_expire	Number	Specify when the merged documents which are sent for sign needs to be expired.
reminder_period	Number	Specify the interval when the remainder email needs to be send to the signers.
common_attachments	File	Specify the attachments that needs to be sent to all the recipients in common. Maximum files allowed: 3 Maximum file size allowed: 3MB Supported file formats: docx / doc / rtf / pdf / zip / html / txt / png / jpeg / gif / jpg
unique_attachments	{ "type": "field", "field_id": <field_id> } (OR) { "type": "file", "folder_id":123456789, "filename_filter": { "type":"startswith/contains/is/endswith", "value": <field_id> }, }	Using this param, you can send a different or unique attachment to each recipient. It can be sent in either one of the following ways; 1. Field Containing Attachment URLs - If you want to map the attachment file paths to a spreadsheet/CSV file. (OR) 2. Folder Containing Attachments - If you want to map the attachment file paths to a particular folder.
test_mode	Boolean (true/false)	Using this param, you can test the Merge APIs without consuming any credit points. The output file will contain a watermark as it is used only for testing purpose. Test mode limit: 50 merges/day for an org.

signer_data

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.

Note:

To use this API, an OAuth token should be generated with the following scopes ZohoWriter.documentEditor.ALL, ZohoWriter.merge.ALL and ZohoSign.documents.ALL
Check out the prerequisites needed to make the Merge and Sign API work, here.
To use this API with CRM templates, record id needs to be passed for each record inside the key 'id' for each data.
We have also provided an option to configure the values for all the above parameters while creating the document itself.
If you have saved the merge settings earlier by configuring the parameter values, then we will get those values (by default) if you miss to pass the parameters while sending the API request.
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.
To merge and sign documents with more than one record, you can use our Bulk Sign API.

Curl Deluge

Sample Request


				curl --location --request POST "https://zohoapis.com/writer/api/v1/documents/ponazfea04477109f4681a831e7177d96bc40/merge/sign" \
  --header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
  --form "service_name=zohosign" \
  --form "filename=New Document" \
  --form "signer_data=[{\"recipient_1\":\"john@zylker.com\”, \"action_type\": \"sign\",\"language\": \"en\",\"private_notes\": \"Hey!Please sign this document\"},{\“recipient_2\":\"amelia@zylker.com\", \"action_type\": \"approve\",\"language\": \"fr\"}]" \
  --form "merge_data={\"data\":[{\"name\":\"Amelia\",\"email\":\"amelia@zylker.com\"}]}"

Sample Response


				{
    "merge_report_data_url": "http://writer.zoho.com/writer/api/v1/merge/job/0tq5n465132106580437abe99b6f56f2b0c85/data",
    "merge_report_url": "http://writer.zoho.com/writer/v1/mailmerge/job/0tq5n465132106580437abe99b6f56f2b0c85",
    "records": [
        {
            “name”:“Amelia”,
            "email": "amelia@zylker.com",
            "download_link": "{url}",
            "sign_request_id":12345****",
            "status": "inprogress"
        }
    ]
}

Snippet 1


				documentid = "po5uobda049e029d44b13a9956f6d2cedc67b"; 
url = "https://zohoapis.com/writer/api/v1/documents/" + documentid + "/merge/sign"; 
fields = Map(); 
fields.put("InvoiceNo","12345"); 
fields.put("InvoiceDate","27 May 2022"); 
fields.put("InvoiceAmount","$100");
data = Map(); 
data.put("data",fields); 
params = Map(); 
signerList = List(); 
signerObj1 = Map(); 
signerObj1.put("recipient_1","john@zylker.com"); 
signerObj1.put("action_type","approve");  //approve|sign|view  
signerObj1.put("language","en"); 
signerObj2 = Map(); 
signerObj2.put("recipient_2","amelia@zylker.com"); 
signerObj2.put("action_type","sign");  //approve|sign|view  
signerObj2.put("language","fr"); 
signerList.add(signerObj1); 
signerList.add(signerObj2); 
params.put("merge_data",data); 
params.put("service_name","zohosign"); 
params.put("filename","Invoice data"); 
params.put("signer_data",signerList); 
params.put("sign_in_order","true");  //optional
params.put("message", "Please find the document to be signed here");   //optional
params.put("reminder_period", "15");   //optional
params.put("set_expire", "30");   //optional

documentObj = invokeurl 
[ 
url :url 
type :POST 
parameters:params 
connection:"<connection_name>" 
]; 
info documentObj;

Sample Response


				{
    "merge_report_data_url": "http://writer.zoho.com/writer/api/v1/merge/job/po5uobda049e029d44b13a9956f6d2cedc67b/data",
    "merge_report_url": "http://writer.zoho.com/writer/v1/mailmerge/job/po5uobda049e029d44b13a9956f6d2cedc67b",
    "records": [
        {
            "InvoiceNo": "12345",
            "InvoiceDate": "27 May 2022",
            "InvoiceAmount": "$100",
            "download_link": "{url}",
            "sign_request_id":12345****",
            "status": "inprogress"
        }     
    ]
}

Snippet 2 - Merge and Sign with common attachments


				documentid = "po5uobda049e029d44b13a9956f6d2cedc67b"; 
url = "https://zohoapis.com/writer/api/v1/documents/" + documentid + "/merge/sign"; 
fields = Map(); 
fields.put("InvoiceNo","12345"); 
fields.put("InvoiceDate","27 May 2022"); 
fields.put("InvoiceAmount","$100");
data = Map(); 
data.put("data",fields); 
params = Map(); 
signerList =[]; 
signerObj1 = Map(); 
signerObj1.put("recipient_1","john@zylker.com"); 
signerObj1.put("action_type","approve");  //approve|sign|view  
signerObj1.put("language","en"); 
signerObj2 = Map(); 
signerObj2.put("recipient_2","amelia@zylker.com"); 
signerObj2.put("action_type","sign");  //approve|sign|view  
signerObj2.put("language","fr"); 
signerList = [signerObj1,signerObj2]; 
singerlistStr = "["+signerList.toString()+"]"; 
commonAttachmentFile1 = invokeurl 
[ 
url :"<https://example.com/download/publicdocument>" 
type :GET 
]; 
commonAttachmentFile2 = invokeurl 
[ 
url :"<https://example.com/download/publicdocument>" 
type :GET 
]; 
downloadFile1.setParamName("common_attachments"); 
paramList = list(); 
paramMap1 = {"paramName":"common_attachments","content":commonAttachmentFile1}; 
paramMap2 = {"paramName":"common_attachments1","content":commonAttachmentFile2};
paramMap3 = {"paramName":"merge_data","content":data.toString(),"Content-Type":"application/json","stringPart":true"};
paramMap4 = {"paramName":"filename","content":"Invoice data","stringPart":"true"};
paramMap5 = {"paramName":"signer_data","content":singerlistStr,"Content-Type":"application/json","stringPart":"true"};

paramList.add(paramMap1); 
paramList.add(paramMap2); 
paramList.add(paramMap3); 
paramList.add(paramMap4); 
paramList.add(paramMap5); 
documentObj = invokeurl 
[ 
url :url 
type :POST 
files:paramList 
connection:"<connection_name>" 
]; 
info documentObj;

Sample Response


				{
    "merge_report_data_url": "http://writer.zoho.com/writer/api/v1/merge/job/po5uobda049e029d44b13a9956f6d2cedc67b/data",
    "merge_report_url": "http://writer.zoho.com/writer/v1/mailmerge/job/po5uobda049e029d44b13a9956f6d2cedc67b",
    "records": [
        {
            "InvoiceNo": "12345",
            "InvoiceDate": "27 May 2022",
            "InvoiceAmount": "$100",
            "download_link": "{url}",
            "sign_request_id":12345****",
            "status": "inprogress"
        }
    ]
}