Merge and Store V2

Purpose

Using this API, you will be able to store the merged document inside Zoho Workdrive.

In Merge and Store V1 API, the response will be returned along with the RID only after the merge is completed. In Deluge Script, the maximum timeout will be 40 secs. In some cases, the merge operation will exceed 40 secs which fails the DRE workflow.

To overcome this problem, we have introduced Merge and Store V2 API . In which, the response will be returned immediately along with a virtual RID and merge operation will be scheduled in the backend to store the merged document in the virtual RID. User can use this virtual RID and proceed with their workflow. Until the scheduled merge operation is completed, the virtual RID will be provided with the temporary content.

To track the merge status, you can either make use of the ‘merge_report_data_url’ or ‘merge_report_url’ generated in the response.

Quick Reference

Property	Value
Property	Value
Method	POST
Request URL	https://{zohoapis_domain}/writer/api/v2/documents/{document_id}/merge/store
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
output_settings	{ "doc_name": "<new document name>", "folder_id": "<folder_id>", "format":"<pdf/docx/pdfform>", "password": "<***>", "overwrite_existing_file": "<true/false>", "merge_to":"<separatedoc/singledoc>, "sign_service_name":"<adobesign/docusign>", "restricted_access": { " password ": "", " permissions** ": ["document.copy", "document.print", "document.edit", "document.fill"] } }	Pass the values fvia this parameter as JSON. doc_name -> Specify the name for the merged document. folder_id -> Specify the id of the folder in which you would like to store the merged document. format (optional) -> 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 ( zdoc ) by default. password (optional) -> Specify a password if you would like to protect the merged document. This param is applicable only for pdf and docx documents. Maximum characters allowed: Upto 100 characters overwrite_existing_file (optional) -> Use this param, if you wish to replace an existing file stored in Zoho WorkDrive with the merged document. merge_to (optional) -> 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. Note: By default, we will consider separatedoc merge type. sign_service_name (optional) -> This param needs to be configured when you would like to upload the merged document with signer fields to a third party sign service. Note: This param can be used only when the 'output_format' key value is configured as pdf. restricted_access(optional) - 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.
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
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.
webhook_info	{ "url": <URL>, "retry": <Integer>, "timeout": <Integer>, "expiry_date": <timestamp>, "context": <String> }	Using this param, you will be able to specify the following; url -> Provide the location to which the merge status along with the document information needs to be sent once the 'Merge' operation is completed. retry -> Specify the number of retries required to send the merge status to the provided url. timeout -> Specify the timeout for the given url. expiry_date -> Set the expiry date for the given url. context -> Any data passed inside this key will be sent back to the given url.

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

webhook info

Parameter	Type	Possible Values	Default Value
url	string	URL - Maximum length -> 255	URL
retry	integer	0 to 4	0
timeout	integer	1 to 120000 milliseconds	120000 milliseconds
context	string	Maximum characters allowed = 1000

url

Once the merge operation is completed, the merge status along with the document information will be sent back to the given url with the following key names:

Key Name	Type	Description
merge_info	JSONObject	It contains the user details who initiated the merge along with the response of the output action configured in the template settings.
context	String	Data that is passed via 'context' key inside 'webhook_info' param will be present here.

Sample Structure:

 "merge_info": { // Initially, the response of the output action configured in the template settings will be present. // Along with that, the below information will also be included. "initiator_info": { "user_id": <user id who initiated the merge>, "email_id": <email address of the user who initiated the merge>, "initiated_at_ms": <time stamp>, "initiated_at": <formatted date> } } "context": <String>

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 store the merged document in a specific WorkDrive folder using this deluge task.
For possible errors, refer to error codes.

Sample Request

Curl Deluge

Copiedcurl -X POST "https://www.zohoapis.com/writer/api/v2/documents/{document_id}/merge/store" \
  -H "Authorization: Zoho-oauthtoken <ACCESS_TOKEN>" \
  -F "output_settings={\"doc_name\":\"Invoice_2026_001\",\"folder_id\":\"<folder_id>\",\"format\":\"pdf\"}" \
  -F "merge_data={\"data\":[{\"name\":\"Amelia\",\"email\":\"Amelia@zylker.com\"},{\"name\":\"Johnson\",\"email\":\"johnson@zylker.com\"}]}"

Copieddocument_id = "fbsa6360a78f53f564dfa9b4a1e79febed569";
fieldInfo =  invokeurl
[
url: "https://www.zohoapis.com/writer/api/v1/documents/fbsa6360a78f53f564dfa9b4a1e79febed569/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");
outputsettings = Map();
outputsettings.put("doc_name","Student Grade");
outputsettings.put("folder_id","bsa6360a78f53f***");    //Workdrive Folder ID  //optional
outputsettings.put("format","pdf");     //<docx/pdfform/pdf>  //optional
outputsettings.put("password","*****");     //optional
outputsettings.put("overwrite_existing_file","true");     //<true/false>  //optional
param = map();
param.put("merge_data",{"data":datamap});
param.put("output_settings",outputsettings);
response = invokeurl
[
url: "https://www.zohoapis.com/writer/api/v2/documents/fbsa6360a78f53f564dfa9b4a1e79febed569/merge/store"
type: POST
parameters: param
connection:"<connection_name>"
];

Sample Response

Copied{
    "merge_report_data_url": "<url>",
    "merge_report_url": "<url>",
    "records": [
        {
            "data": [{“given input merge_data”}],
            "download_link": "<attachment download url>",
            "document_id": "<merged doc id>",
            "document_url": "<merged doc open url>",
            "status": "inprogress"
        }
    ],
    "status": "inprogress"
}

When you invoke the 'merge_report_data_url', you will receive the below response;

// If 'merge_to' = "separatedoc"
{
    "records": [
        {
            "download_link": “{url}“,
            "data": {
                            "name": “Amelia”,
                            “email”: “amelia@zylker.com”
                        },
            "document_id": "ponazfea04477109f4681a831e7177d96bc40",
            "document_url": "https://writer.zoho.com/writer/open/ponazfea04477109f4681a831e7177d96bc40",
            "status": "inprogress"
        },
        {
            "download_link": “{url}“,
            "data": {
                            "name": “John”,
                             “email”: “john@zylker.com”
                        },
            "document_id": "ponazfea04477109f4681a831e7177d96bc40",
            "document_url": "https://writer.zoho.com/writer/open/ponazfea04477109f4681a831e7177d96bc40",
            "status": "inprogress"
        }
      ],
    "status": "inprogress"
}

// If 'merge_to' = "singledoc"
{
    "records": [
        {
            "download_link": “{url}“,
            "data": [
                     {
                            “name": “Amelia”,
                            “email”: “amelia@zylker.com”
                     },
                     {
                            “name": “John”,
                            “email”: “john@zylker.com”
                    }
              ],
            "document_id": "ponazfea04477109f4681a831e7177d96bc40",
            "document_url": "https://writer.zoho.com/writer/open/ponazfea04477109f4681a831e7177d96bc40",
            "status": "inprogress"
        }
    ],
    "status": "inprogress"
}