Combine And Deliver Via Webhook

Purpose

Using this API, you will be able to combine PDF documents and post them in the given webhook url.

Quick Reference

PropertyValue
MethodPOST
Request URLhttps://{zohoapis_domain}/writer/api/v1/documents/pdf/combine/webhook
ScopesZohoWriter.documentEditor.ALL, ZohoWriter.merge.ALL, WorkDrive.organization.ALL
Rate LimitSee Writer API throttle limits

Parameters

Body Parameters

ParameterData TypeMandatory/OptionalDescription
files
or
urls		File
or
String		MandatoryMethod of providing the input file depending on its location.
files - If the input files are from your local drive or desktop.
urls - If the input files are publicly accessible Web URLs. You will have to pass them as a comma separated list.
Note:
- Up to 20 input pdf files can be combined at once. A minimum of 2 files must be provided to perform the combine operation.
- Total file size limit for the input files will be 10 MB each.
webhook{ " invoke_url ": , "timeout": 50, "retry_interval": "60", "headers":{...}, "http_method_type":"put/post"
}		Mandatoryinvoke_url - Specify the webhook url where the combined pdf needs to be posted.
Below mentioned keys are optional;
timeout - Set the timeout duration for posting bytes from Zoho server. By default, it will be set to 50 seconds.
retry_interval - Specify the interval to retry the post operation in case of any failure when sending combined bytes to your server.
Supported range is 60 seconds to 8 hours. By default, it will be set to 60 seconds.
headers - Provide the necessary header key-value pairs in JSON format for posting combined bytes from our server to the provided webhook URL.
http_method_type - Specify the http method type via this key. The default method will be POST.
output_settings{
" name ": "",
" page_number_settings ": {
" sections ": [
{
"range": "1-10",
"format": {
"font": {
"name": "Helvetica",
"size": 10,
"style": "Bold"
}
},
"numbering_config": {
"type": "1",
"start": 1
},
"header": {
"left": {
"text": "Page <> of <>",
"offsets": {
"top": 20,
"left": 40
}
}
},
"footer": {
"center": {
"text": "Page <> of <>",
"offsets": {
"bottom": 20
}
}
}
}
]
}
}		Optionalname - Specify a unique name for the merged or combined output file.
By default, the output file name will be "output.pdf".
page_number_settings - Contains the page number configuration as a JSON Object.
sections (mandatory) - List of configuration blocks, each defining how page numbers should be inserted for a specific page range.
Sample: For adding page number in header at center.
{
"sections": [
{
"header": {
"center": {
"text": "Page <> of <>",
}
}
}
]
}
input_options{
1: {
page_ranges: "3,5,7",
},
2: {
page_ranges: "1-3, 5"
}
}		OptionalIt is possible to combine selected pages or a specific range of pages in a document.
To combine selectedpages, you will have to pass the respective page numbers with comma separated (say 3,5,7,etc., ).
To combine a specific range of pages, you will have to pass the page ranges with a hypen (say 1-3 ).

webhook

ParameterTypePossible ValuesDefault Value
Mandatory Key   
invoke_urlStringURL - Maximum length is 300 characters.URL
Optional Keys   
timeoutInteger60 to 28800 seconds (8hrs)60 seconds
retry_intervalInteger1 to 120 seconds50 seconds
headersJSON- Maximum key count - 10
- Allowed characters for - Alphabets, Numbers, Hyphen, Underscore and Dot. Maximum Length - 100 characters
- Maximum length of - 2500 characters		 
http_method_typeStringput/postpost

 

Notes

  • This API will be available only for users who have Zoho WorkDrive Account.
  • This API is subject to throttle limits. For details on the applicable rate limits, please refer to this help link.
  • For possible errors, refer to error codes.

Sample Request

CurlDeluge
Copiedcurl --location 'https://www.zohoapis.com/writer/api/v1/documents/pdf/combine/webhook' \
--header 'Authorization: Zoho-oauthtoken xxx.yyy.zzz' \
--form 'output_settings="{\"name\":\"CombineWebhook.pdf\"}"' \
--form 'files=@"/Users/Zykler/Downloads/pdf1.pdf"' \
--form 'files=@"/Users/Zykler/Downloads/pdf2.pdf"' \
--form 'webhook="{\"invoke_url\": \"https://www.example.com/v1/api/webhook/savecallback/a94e32e99ad214f2de0ee0b7b6b6*******\"}"'
Copiedfileobj1 = invokeurl
[
	url :"https://freetestdata.com/wp-content/uploads/2023/07/260KB.pdf"
	type :GET
];
info fileobj1;
fileobj2 = invokeurl
[
	url :"https://freetestdata.com/wp-content/uploads/2023/07/800KB.pdf"
	type :GET
];
info fileobj2;
fileobj2.setParamName("files");
output_settings = Map();
output_settings.put("name","Combine-Webhook-document.pdf");  //name for the combined document
webhook = Map();
webhook.put("invoke_url","https://www.example.com/v1/api/webhook/savecallback/a9e3d2e99ad214f2dd0ee0b7b6b655d15840f67a70790d159afc5339ce03fc04");
//optional - if you want any additional keys in webhook callback, pass in headers as mentioned below: 
//additionalkeys = Map();
//additionalkeys.put({"additional_user_key1":"Value1","additional_user_key2":"Value2"});
//webhook.put("headers",additionalkeys);
input_options = Map();  //provide as input_options as shown below if you want to combine selected pages 
document_1 = Map();
document_1.put("page_ranges","1,3"); //page_ranges for document 1 (pages 1,3)
document_2 = Map();
document_2.put("page_ranges","1-5"); //page_ranges for document 2 (pages 1 to 5)
input_options.put("1",document_1);
input_options.put("2",document_2);
paramList = list();
paramList.add({"paramName":"files","content":fileobj1});
paramList.add({"paramName":"files1","content":fileobj2});
paramList.add({"paramName":"output_settings","content":output_settings.toString(),"Content-Type":"application/json","stringPart":"true"});
paramList.add({"paramName":"input_options","content":input_options.toString(),"Content-Type":"application/json","stringPart":"true"});
paramList.add({"paramName":"webhook","content":webhook.toString(),"Content-Type":"application/json","stringPart":"true"});
combinepdf_response = invokeurl
[
        url :"https://www.zohoapis.com/writer/api/v1/documents/pdf/combine/webhook"
	type :POST
	files :paramList
        connection:"<connection_name>" //update the oauth connection 
];
info combinepdf_response;

Sample Response

Copied{
	"status_url": "https://writer.zoho.com/writer/api/v1/documents/pdf/combine/job/f931a01183b33
    	"status": "inprogress/completed/failed"
 }

While invoking the 'status_url', you will receive the below responses;

1. Success case:

{

      "download_link": "<combined pdf download url>",  //combined bytes download link

      “webhook_response”: {

                               “http_status_code”:<200>,

                               ”message”:<message>,

                               "status":"success"

                                   }

       "status": "inprogress/completed/failed"

         }

2. Failure case:

After the combine process is completed, if there is an issue with the webhook delivery (e.g., due to your server being unavailable or down), we will attempt to retry the post operation up to three times. If your server remains unreachable, the response below will be provided, allowing the user to download the combined bytes via the download_link.

{

      "download_link": "<combined download url>",    //will be available only on combine process success

       “webhook_response”: {

                               “http_status_code”:<4xx>,

                               ”message”:<message>,

                               "status":"failed"

                                   }

       "status": "inprogress/completed/failed"

           }