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.

HTTP Request URL

https://{zohoapis_domain}/writer/api/v1/documents/pdf/combine/webhook

Body Parameters

ParameterData TypeDescription
Mandatory Parameters

files

or

urls
 

File

or

String
 

Method 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”: <URL>, 
  “timeout”: 50,
  "retry_interval": "60”,   
  “headers”:{...},
  "http_method_type":"put/post" 

}

invoke_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.

Optional Parameters
output_settings

{ 

“name”: “<filename>”,

 "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 <<page_number>> of <<total_pages>>", 

"offsets": { 

"top": 20, 

"left": 40

 } 

} 

}, 

"footer": { 

"center": { 

"text": "Page <<page_number>> of <<total_pages>>", 

"offsets": { 

"bottom": 20 

} 

} 

} 

} 

] 

} 

} 

 

name - 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 <<page_number>> of <<total_pages>>", 

} 

} 

} 

] 

}  

 

 

input_options{
   1: {   
             page_ranges  : "3,5,7" ,    
        },
    2 :  {
           page_ranges : "1-3, 5"
       }
}

It 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 
timeoutInteger

60 to 28800 seconds (8hrs)

60 seconds
retry_intervalInteger

1 to 120 seconds

50 seconds
headersJSON

  • Maximum key count - 10

  • Allowed characters for <additional_user_key> - Alphabets, Numbers, Hyphen, Underscore and Dot. Maximum Length - 100 characters

  • Maximum length of <value> - 2500 characters
 
http_method_typeString

put/post

post

sections

ParameterTypePossible ValuesDefault Value

range

(optional) 

string"1-9" 

Specify the page ranges from where the page number needs to be inserted. 

By default, page numbers will be added in all pages.

format

(optional) 

JSON Object

 { 

"font":{

 "name":"Roboto",

 "size": 12, 

"style": "Normal" 

} 

}

Defines the formatting for the page numbers. 

font (optional) - Contains font styling details. 

name (optional)  -Web-safe fonts. 

size (optional)  - Specify font size.

style (optional) - Specify the font styles. 

Allowed values:  Normal, Bold, Italic, Bold Italic. 

By default, 

font -Roboto 

size -12 

style - Normal

numbering_config 

(optional)

JSONObject

{

 "type":"1|a|A|i|I",

 "start": 5 

}

type (optional) -  Defines the numbering style. Allowed values:  1/a/A/i/I 

By default:  1,2,3 

start (optional) - Defines the starting number for the page numbers. 

For example: If type is "a" and start is 5 then the numbering will start from 'e'.     

header / footer

 (atleast one is mandatory)  

 

JSONObject

{ 

"left": { 

"text": "Page <<page_number>> of <<total_pages>>",

 "offsets": { 

"top": "20px",

 "left": "40px"

} 

}, 

"center": { 

}, 

"right": { 

} 

} 

Contains layout sections where page numbers or text can be added in header/footer.

 left/center/right - (atleast one mandatory in either header or footer) - Specify the placement and content of text in the left, center or right position. 

text (mandatory) - Specify the text content to be displayed. You may use placeholders like <<page_number>> and <<total_pages>>.

offsets (optional) - Specify the positioning offsets for the text, with top, bottom, left, and right values in pixels. Defaults to header/footer position if not provided. 

Note:

  • This API will be available only for users who have Zoho WorkDrive Account.
  • To use this API, an OAuth token should be generated with the following scopes; ZohoWriter.documentEditor.ALL,ZohoWriter.merge.ALL,WorkDrive.organization.ALL
  • This API is subject to throttle limits. For details on the applicable rate limits, please refer to this help link.

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"

           }