Combine and Store

Purpose

Using this API, you will be able to combine PDF documents and store it in Zoho WorkDrive.

Prerequisites

Before using this API, you need to access the merge template once from Zoho Writer's UI.

Steps to access the template in Zoho Writer

  1. Open Zoho Writer dashboard and select your preferred merge template.

  2. Click the hamburger menu -> Automate tab.

Note: You need to access the template once before sending an API request. You need not access the template every time before you send an API request.

HTTP Request URL

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

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 5 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.
Optional Parameters
output_settings{
“name”: “<filename>”,
“folder_id”: "<String>”,
“overwrite_existing_file”: “<Boolean>”
}

name - Specify a unique name for the merged or combined output file .

By default, the output file name will be "output.pdf".

 

folder_id - Specify the ID of the folder where you'd like to store the combined PDF document. By default, it will be saved in the "My Folder" of WorkDrive.

 

overwrite_existing_file - If you wish to replace an existing file in Zoho WorkDrive with the combined document, use this key. By default, this value is set to false.

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

team_idString
 		If the user has multiple WorkDrive teams and wants to use a specific team for credit usage, use this parameter. By default, the user's preferred team will be used for credit calculation.

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
  • Check out the prerequisites needed to make the Combine and Store API work, here.
  • 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/store' \
--header 'Authorization: Zoho-oauthtoken xxx.yyy.zzz' \
--form 'files=@"/Users/zlyker/Downloads/pdf_1.pdf"' \
--form 'files=@"/Users/zlyker/Downloads/pdf_2.pdf"' \
--form 'input_options="{\"1\":{\"page_ranges\":\"1,3-5\"},\"2\":{\"page_ranges\":\"1-3,6\"}}"' \
--form 'output_settings="{\"name\":\"CombineAndStore.pdf\",\"folder_id\":ivahpc40bfada15d34449852686********}"'
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
];
fileobj2.setParamName("files");
output_settings = Map();
output_settings.put("name","Combine-Store-document.pdf");  // name for the combined document
output_settings.put("folder_id","wz737eddcb4eddd6b3d9a15d****");  //optional - provide the specific WorkDrive Folder Id to store the combined document 
output_settings.put("overwrite_existing_file",true);  //optional - to overwrite the file which is already present in the folder with the same name
input_options = Map();
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"});
combinepdf_response = invokeurl
[
        url :"https://www.zohoapis.com/writer/api/v1/documents/pdf/combine/store" 
	type :POST
	files:paramList
        connection:"<connection_name>"   //update 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:

{

      "document_id": "<combined pdf document id>

     "document_url": "<combined pdf document open url>

      "download_link": "<combined pdf download url>", 

       "status": "inprogress/completed/failed"

          }

2. Failure case:

In rare instances, after the combine process is completed, a store failure may occur due to unforeseen circumstances (e.g., folder permissions being revoked mid-process). In such cases, the below response will be returned, and the user can download the combined bytes via the provided download_link.

{

      "download_link": "<combined pdf download url>",  // Available only on combine process success 

       "status": "failed"

       "error": {

                      "errorcode":"<R2000>"

                      "message" :"<message>"

                    }

}