Merge and Invoke

Purpose

Using this API, you will be able to execute/invoke the custom function configured in the template and merge it.

Quick Reference

Property	Value
Method	POST
Request URL	https://{zohoapis_domain}/writer/api/v1/documents/{document_id}/merge/execute
Scopes	ZohoWriter.documentEditor.ALL, ZohoWriter.merge.ALL, ZohoPC.files.ALL, WorkDrive.files.ALL
Rate Limit	See Writer API throttle limits

Parameters

Path Parameters

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

Body Parameters

Parameter	Data Type	Description
Mandatory Parameters
Merge Data — pass data using 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.
record_id	String	Instead of using merge_data, you can pass the record_id and we will fetch the data internally. Note: This is applicable only for Zoho CRM, Creator and Bigin templates. Maximum length allowed: 25
Optional Parameters
output_settings	{ "format": "<pdf/docx/pdfform>", "password": "<*>", "merge_to": "<separatedoc/singledoc>, "filename": "<new document name>", "restricted_access": { "password": "", "permissions**": ["document.copy", "document.print", "document.edit", "document.fill"] } }	Using this param, you will be able to specify the following; format -> Specify a format in which you would like to store the merged document. Supported formats are pdf, pdfform and docx. If this key is not passed, the merged documents will get stored in Writer format (pdf) by default. password -> Specify a password if you would like to protect the merged document. Supported formats are pdf, pdfform and docx. merge_to -> Supported merge types are separatedoc and singledoc. Specify in which type you would like to merge the document. separatedoc - If you would like to merge each record as a separate document. singledoc - If you would like to merge all the records as a single document. filename -> Specify a unique name for the merged 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 by passing the merge field id. For example: filename=NDA_Agreement <<ClientName>> Maximum length allowed: 150 restricted_access - password: Specify the password to enable or override the restricted permissions. Maximum characters allowed: Upto 100 characters - permissions: Specify the actions that needs to be restricted in merged document. Note: If this param is passed, then both password and permissions fields are mandatory.
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.

permissions

Permission Key Name	Description
document.copy	Copy content from the merged document
document.print	Print the merged document
document.edit	Edit the merged document
document.fill	To fill form fields in the merged document

Notes

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.
You can also merge the document and invoke a custom function to perform further operations using this deluge task.
For possible errors, refer to error codes.

Sample Request

Curl Deluge

Copiedcurl -X POST "https://www.zohoapis.com/writer/api/v1/documents/{document_id}/merge/execute" \
  -H "Authorization: Zoho-oauthtoken <ACCESS_TOKEN>" \
  -F "merge_data={\"data\":[{\"name\":\"Amelia\",\"email\":\"amelia@zylker.com\"},{\"name\":\"Johnson\",\"email\":\"johnson@zylker.com\"}]}" \
  -F "output_settings={
    \"format\": \"pdf\",
    \"password\": \"****\",
    \"merge_to\": \"separatedoc\",
    \"filename\": \"NDA_Agreement_<<name>>\",
    \"restricted_access\": {
      \"password\": \"****\",
      \"permissions\": [\"document.copy\", \"document.print\", \"document.edit\", \"document.fill\"]
    }
  }"

Copieddocument_id = "fbsa6360a78f53f564dfa9b4a1e79febed567";
fieldInfo =  invokeurl
[
url: "https://www.zohoapis.com/writer/api/v1/documents/fbsa6360a78f53f564dfa9b4a1e79febed567/fields"
type: GET
connection:"<connection_name>"
];
fieldsList =  fieldInfo.get("fields");
datamap = map();
for each field in fieldsList
{
 info field;
}	
datamap.put("Name", "Ms.Amelia");
datamap.put("Tamil", "S");
datamap.put("English", "A");
datamap.put("Maths", "A");
datamap.put("Remark", "Good");
output_settings = Map();
output_settings.put("filename","Student Grade");
output_settings.put("format","pdf");     //<docx/pdfform/pdf>  //optional
output_settings.put("password","*****");    	//optional
output_settings.put("merge_to","separatedoc");     //<separatedoc/singledoc>  //optional
param = map();
param.put("merge_data",{"data":datamap});
param.put("output_settings",output_settings);
response = invokeurl
[
url: "https://www.zohoapis.com/writer/api/v1/documents/fbsa6360a78f53f564dfa9b4a1e79febed567/merge/execute"
type: POST
parameters: param
connection:"<connection_name>"
];

Sample Response

Copied{
    "merge_report_data_url": "https://writer.zoho.com/writer/api/v1/merge/job/ba9cb8b6d826e05e26fd03c391dc4baa674281f9895988caf8420630887b5902/data",
    "merge_report_url": "https://writer.zoho.com/writer/v1/mailmerge/job/ba9cb8b6d826e05e26fd03c391dc4baa674281f9895988caf8420630887b5902",
    "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"
        }
   ],
    "status": "inprogress"
}

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

1. If 'merge_to' = "separatedoc"

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

2. If 'merge_to' = "singledoc"

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