Merge and Deliver via Webhook

Purpose

This API is used to deliver the merge documents via Webhook for custom handling by consumers.

HTTP Request URL

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

Path Parameters

ParameterData TypeDescription
Mandatory Parameters
document_idStringSpecify a unique id for the writer document.

Body Parameters

ParameterData TypeDescription
Mandatory Parameters
output_formatStringSupported formats are pdf, pdfform and docx. Specify a format in which you would like to download the merged document.
webhook

{

"invoke_url" : <url>,

"invoke_period": "oneveryrecord/oncomplete"

}

Pass the values for invoke_url and invoke_period via this parameter as JSON.

Provide the webhook url in which the merged documents needs to be posted in invoke_url and when the merged documents needs to be posted in invoke_period.

merge_toString

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.

You can provide the data in any one of the below formats
merge_dataJSONObjectPass a String value through 'data' key as JSON Array.
merge_data_csv_contentFileProvide the required csv content in your API request body.
merge_data_json_contentFileProvide the required json content in your API request body.
merge_data_csv_urlurlProvide the required csv url in your API request body.
merge_data_json_url urlProvide the required json url in your API request body.
Optional Parameters
passwordStringSpecify a password if you would like to protect the merged document.
test_modeBoolean (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

ParameterTypePossible ValuesDefault Value
invoke_urlstringURLURL
invoke_periodstring

oncomplete and oneveryrecord.

oncomplete - If you would like to post the merged documents after merging all the records.

oneveryrecord - If you would like to post the merged document of each record once done.

oncomplete

Sample Request

Copiedcurl --location --request POST "https://www.zohoapis.com/writer/api/v1/documents/ponazfea04477109f4681a831e7177d96bc40/merge/webhook" \
  --header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
  --form "output_format=pdf" \
  --form "password=***" \
  --form "webhook={\"invoke_period\":\"oncomplete\",\"invoke_url\":\"https://facebook.com\"}" \
  --form "merge_to=separatedoc" \
  --form "merge_data={\"data\":[{\"name\":\"Amelia\",\"email\":\"amelia@zylker.com\"},{\"name\":\"John\",\"email\":\"john@zylker.com\"}]}"

Sample Response

Copied{
    "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": [
        {
	    "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;

1. If 'merge_to' = "separatedoc"

{
    "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"
}

2. If 'merge_to' = "singledoc"

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

Deluge Snippet

Copieddata = Map();
data.put("InvoiceNo","12345"); 
data.put("InvoiceDate","27 May 2022"); 
data.put("InvoiceAmount","$100");param = Map();
param.put("output_format","docx");
webhook1 = Map();
webhook1.put("invoke_url”,”<https://facebook.com>”);
webhook1.put("invoke_period","oneveryrecord");
param.put("webhook",webhook1);
param.put("merge_to","singledoc");
param.put("merge_data",{"data":data});
info param;
response = invokeurl
[
	url :"https://www.zohoapis.com/writer/api/v1/documents/olce2ef69******331f25aaece75dd/merge/webhook"
	type :POST 
	parameters:param
	connection:"<connection_name>"
];
info response;

Sample Response

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