Insert Pages from PDF
Purpose
This API allows you to insert pages from one or more source PDFs into an original PDF, and return the result as a download, store it in Zoho WorkDrive, or deliver it via callback.
Quick Reference
| Property | Value |
|---|---|
| Method | POST |
| Request URL (Download) | https://{zohoapis_domain}/pdfeditor/api/v1/pdf/pages/insert |
| Request URL (Store) | https://{zohoapis_domain}/pdfeditor/api/v1/pdf/pages/insert/store |
| Request URL (Callback) | https://{zohoapis_domain}/pdfeditor/api/v1/pdf/pages/insert/callback |
Body Parameters
| Parameter | Value | Mandatory/Optional | Description |
|---|---|---|---|
| original_file | File or String | Mandatory | Upload the existing PDF file into which pages should be inserted from local drive/desktop, or provide a publicly accessible web URL. Maximum file size is 50 MB. |
| source_file | File or String | Mandatory | Upload source PDF file(s) from local drive/desktop, or provide publicly accessible web URLs. For callback variant, you can pass this parameter multiple times (up to 10 source files). Maximum size per source PDF is 50 MB. |
| input_options | { | Mandatory | Specify insertion configuration. For download/store variants, pass a JSON object with page_number and position. For callback variant, pass a JSON array where each object maps to each source_file in the same order. |
| output_settings | { "name": "<document_name>" } | Mandatory for download variant | Specify output configuration for downloadable result. |
| output_settings | { "name": "<document_name>", "folder_id": "<folder_id>", "overwrite_existing_file": true | false } | Mandatory for store variant | name – Specify the name for the modified PDF document. folder_id – Specify the ID of the WorkDrive folder in which to store the output file. overwrite_existing_file(optional) – Set to true to overwrite an existing file with the same name in the folder. |
| callback | { "invoke_url": "<callback_url>", "timeout": 60, "retry_interval": 60, "headers": { "header_name": "header_value" }, "http_method_type": "post" } | Mandatory for callback variant | Specify the callback delivery configuration for the /callback variant. |
input_options Parameters
| Parameter | Data Type | Possible Values | Default Value |
|---|---|---|---|
| page_number | Integer | Positive integer page number in the original PDF where insertion should happen. | – |
| position | String | before, after | – |
| page_ranges | JSON Array | Array of single page numbers and/or ranges, for example: ["1", "4-9"] | All pages from source PDF |
output_settings (Download) Parameters
| Parameter | Data Type | Possible Values | Default Value |
|---|---|---|---|
| name | String | Name for the modified PDF document | – |
output_settings (Store) Parameters
| Parameter | Data Type | Possible Values | Default Value |
|---|---|---|---|
| name | String | Name for the modified PDF document | – |
| folder_id | String | ID of the folder in Zoho WorkDrive to store the modified PDF | – |
| overwrite_existing_file | Boolean | true, false | false |
callback Parameters
| Parameter | Data Type | Possible Values | Default Value |
|---|---|---|---|
| invoke_url | String | URL. Maximum length: 300 characters. | – |
| timeout | Integer | 10 to 120 seconds | 60 seconds |
| retry_interval | Integer | 60 to 28800 seconds | 60 seconds |
| headers | JSON Object | Maximum 10 keys. Allowed characters for keys: alphabets, numbers, hyphen, underscore, dot. Maximum key length: 100. Maximum value length: 2500. | – |
| http_method_type | String | put, post | post |
Notes and Limits
- The maximum file size allowed for original_file is 50 MB, and the PDF cannot exceed 400 pages.
- The maximum file size allowed for each source_file is 50 MB, and the PDF cannot exceed 400 pages.
- For callback variant, a maximum of 10 source files can be passed in one request.
- For callback variant, the number of objects in input_options must match the number of source_file values.
- For callback variant, each source file is mapped to its corresponding input_options object by order.
- The store variant requires a Zoho WorkDrive account.
- To use the download or callback variants, an OAuth token should be generated with the following scopes: ZohoWriter.pdfEditor.ALL
- To use the store variant, an OAuth token should be generated with the following scopes: ZohoWriter.pdfEditor.ALL, WorkDrive.organization.ALL, WorkDrive.files.ALL
Possible Errors
Refer to the following pages for the list of possible errors for this API:
Download Sample Request
Copiedcurl --location --request POST "https://www.zohoapis.com/pdfeditor/api/v1/pdf/pages/insert" \
--header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
--form 'original_file=@"/Users/username/Documents/Existing.pdf"' \
--form 'source_file=@"/Users/username/Documents/Source.pdf"' \
--form 'input_options=“{\”page_number\”:\”3\",\”position\”:\”after\"}"' \
--form 'output_settings=“{\”name\”:\”ModifiedFile.pdf\"}"'
Once the process begins, you will initially receive the 'status_url'. By invoking the 'status_url', you will be able to monitor the status of the scheduled job.
Store Sample Request
Copiedcurl --location --request POST "https://www.zohoapis.com/pdfeditor/api/v1/pdf/pages/insert" \
--header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
--form 'original_file=@"/Users/username/Documents/Existing.pdf"' \
--form 'source_file=@"/Users/username/Documents/Source.pdf"' \
--form 'input_options=“{\”page_number\”:\”3\",\”position\”:\”after\"}"' \
--form 'output_settings=“{\”name\”:\”ModifiedFile.pdf\"}"'
Once the process begins, you will initially receive the 'status_url'. By invoking the 'status_url', you will be able to monitor the status of the scheduled job.
Callback Sample Request
Copiedcurl --location --request POST "https://www.zohoapis.com/pdfeditor/api/v1/pdf/pages/insert/store" \
--header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
--form 'original_file=@"/Users/username/Documents/Existing.pdf"' \
--form 'source_file=@"/Users/username/Documents/Source.pdf"' \
--form 'input_options=“{\”page_number\”:\”3\",\”position\”:\”after\"}"' \
--form 'output_settings=“{\”name\”:\”ModifiedFile.pdf\",\”folder_id\”:\”1a2b3cefg\"}"'Once the process begins, you will initially receive the 'status_url'. By invoking the 'status_url', you will be able to monitor the status of the scheduled job.
Download Sample Response
Copied{
"status_check_url": "https://pdf.zoho.com/pdfeditor/api/v1/pdf/pages/insert/job/f931a01183b33",
"status": "inprogress"
}Download Success Response
Copied{
"download_url" : "https://pdf.zoho.com/pdfeditor/api/v1/pdf/pages/insert/download/f931a01183b33",
"status": "success"
}Store Sample Response
Copied{
"download_url" : "https://pdf.zoho.com/pdfeditor/api/v1/pdf/pages/insert/download/f931a01183b33",
"status": "success"
}Store Success Response
Copied{
"status_check_url" : "https://pdf.zoho.com/pdfeditor/api/v1/pdf/pages/insert/job/f931a01183b33",
"document_url" : "https://workdrive.zoho.com/file/ponazfea04477109f4681a831e7177d96bc40",
"document_id" : "ponazfea04477109f4681a831e7177d96bc40",
"status" : "inprogress"
}