Bulk Merge Sign

Purpose

This API allows the merge and sign documents in bulk.

Quick Reference

Property	Value
Method	POST
Request URL	https://{zohoapis_domain}/writer/api/v1/templates/{{template_id}}/bulkmerge/sign
Scopes	ZohoWriter.documentEditor.ALL, ZohoWriter.merge.ALL and 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
filename	String	Mandatory	Specify a unique name for the signed document. This can be achieved using anyone of the following ways; 1. You can pass it has a normal string value. For example: filename=NDA_Agreement (OR) 2. You can also customise the filename for each recipients by passing the merge field id. For example: filename=NDA_Agreement <> Maximum length allowed: 150
signer_data	[ { "recipient_1":{type:'field',field_id:'email'}, "recipient_name":"Amelia", "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":{type:'email', email_id:'john@zylker.com'}, "recipient_name":"John", "action_type": <approve\|sign\|view\|in_person_sign>, "language": "fr", "delivery_type": [{ "type": "sms", "countrycode" : "+91", "phonenumber": "1234567890" }], “verification_info": { "type": <email\|sms\|offline> } }, ... ]	Mandatory	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. The recipients email id can either be a merge field specified in the 'merge_data' param (eg: recipient_1: { type: field, 'field_id': 'email' ) or an email address (eg: recipient_2: {'type': email, 'email_id':john@zylker.com ). 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.
merge_data	JSONObject	Mandatory	Pass a String value through 'data' key as JSON Array.
merge_data_csv_content	File	Mandatory	Provide the required csv content in your API request body.
merge_data_json_content	File	Mandatory	Provide the required json content in your API request body.
merge_data_csv_url	url	Mandatory	Provide the required csv url in your API request body.
merge_data_json_url	url	Mandatory	Provide the required json url in your API request body.
sign_in_order	Boolean (true / false)	Optional	Specify if we need to maintain the order of signing as mentioned.
message _plaintext (or) message_richtext	String (or) HTML	Optional	Specify any message for the signer either in the form of a plaintext or a HTML. Supported HTML tags are listed here.
set_expire	Number	Optional	Specify when the merged documents which are sent for sign needs to be expired.
reminder_period	Number	Optional	Specify the interval when the remainder email needs to be send to the signers.
common_attachments	String	Optional	Specify the attachments that needs to be sent to all the recipients in common. Maximum files allowed: 20 attachments Maximum file size allowed per attachment: 10 MB Total attachment size: 40 MB Supported file formats: docx / doc / rtf / pdf / zip / html / txt / png / jpeg / gif / jpg
unique_attachments	{ " type ": "field", " field_id ": } (OR) { " type ": "file", " folder_id ":123456789, " filename_filter ": { "type":"startswith/contains/is/endswith", "value": }, }	Optional	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.
sign_org_id	String	Optional	Specify the Zoho Sign organization ID from which the document is sent for signing.
sign_request_type_id	String	Optional	Specify the Zoho Sign document type ID.

signer_data

Parameter	Type	Possible Values	Default Value
recipient_n	JSON	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 .

Notes

Check out the prerequisites needed to make the Bulk 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. For more details, please refer this link.
For possible errors, refer to error codes.

Curl Snippet

Copiedcurl --location --request POST "https://www.zohoapis.com/writer/api/v1/templates/ponazfea04477109f4681a831e7177d96bc40/bulkmerge/sign" \
  --header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
  --form "filename=New Document" \
  --form "signer_data=[{\”recipient_1\”:{type:'field',field_id:'email'},\”recipient_name\”:\”Amelia\",\”action_type\”:\”sign\",\"language\": \"en\",\"private_notes\": \"Hey!Please sign this document\”},{\”recipient_2\”:{type:'email',email_id:’john@zylker.com’},\”recipient_name\”:\”John\",\”action_type\”:\”approve\”,\"language\": \"fr\"}]" \
  --form "merge_data={\"data\":[{\"name\":\"Amelia\",\"email\":\"amelia@zylker.com\"},{\"name\":\"John\",\"email\":\"john@zylker.com\"}]}"

Sample Response

Copied{
    "merge_report_data_url": "https://writer.zoho.com/writer/api/v1/merge/job/0tq5n465132106580437abe99b6f56f2b0c85/data",
    "merge_report_url": "https://writer.zoho.com/writer/v1/mailmerge/job/0tq5n465132106580437abe99b6f56f2b0c85",
    "records": [
        {
            "data": {
                           "name": "Amelia",
                           "email": "amelia@zylker.com"
                         },
            "download_link": "{url}",
            "status": "inprogress"
        },
        {
            "data": {
                           "name": "John",
                           "email": "john@zylker.com"
                         },
            "download_link": "{url}",
            "status": "inprogress"
        }
    ]
}

// When 'merge_report_data_url' is invoked, you will receive the below response;

{
    "records": [
        {
            
            "download_link": “{url}“,
            "data": {
                            “name": "Amelia”,
                            "email": “amelia@zylker.com"
                         },
            "status": "inprogress"
        },
        {
            
            "download_link": “{url}“,
            "data": {
                            “name": “John”,
                            "email": “john@zylker.com"
                         },
            "status": "inprogress"
        }
    ],
    "status": "inprogress"
}

Deluge Snippet

Copied 
documentid = "olce2ef696f1810ee46ed8331f25aaece75dd";
url = "https://www.zohoapis.com/writer/api/v1/templates/" + documentid + "/bulkmerge/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();
recipient = Map();
recipient.put("type","email");
recipient.put("email_id”,”Amelia@zylker.com");
signerObj1.put("recipient_1",recipient);
signerObj1.put("action_type","sign");
signerObj1.put("language","en");
signerList.add(signerObj1);
params.put("filename","bulkSign");
params.put("signer_data",signerList);
params.put("merge_data",data);
documentObj = invokeurl
[
	url :{url}
	type :POST
	parameters:params
	connection:"<connection_name>"
];
info documentObj;

Sample Response

Copied{
  "merge_report_data_url": "https://writer.zoho.com/writer/api/v1/merge/job/<jobId>/data",
  "merge_report_url": "https://writer.zoho.com/writer/v1/mailmerge/job/<jobId>",
  "records": [
    {
      "download_link": “{url}”,
      "data": {
        "InvoiceNo": "12345",
          "InvoiceDate": "27 May 2022",
          "InvoiceAmount": "$100",
          "id": "0e002287-7c45-4188-af9f-65*****”
      }
      "status": "inprogress"
    }
  ],
  "status": "inprogress"
}