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	{ "page_number": 3, "position": "before" \| "after" } (OR) [ { "page_number": 3, "position": "after", "page_ranges": ["1", "4-9"] }, { "page_number": 5, "position": "before", "page_ranges": ["2-6"] } ]	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 Variant Sample Response

Copied{
	"status_check_url": "https://pdf.zoho.com/pdfeditor/api/v1/pdf/pages/insert/job/f931a01183b33",
	"status": "inprogress"
}

Download Variant Success Response

Copied{
	"download_url" : "https://pdf.zoho.com/pdfeditor/api/v1/pdf/pages/insert/download/f931a01183b33",
	"status": "success",
    "response_generated_time": 1780912656237
}

Store Variant Sample Response

Copied{
	"status": "inprogress",
	"status_check_url": "https://pdf.zoho.com/pdfeditor/api/v1/pdf/pages/insert/job/2ae74c719bdb14ed9941fe351ade742439bf75ab0fb8fdf0a68b57a7a60cbd54ab7cb7bea5d0fafb4d2560a90331aaf8",
	"document_id": "hf3e60435a4c7576f4d21a16cfc292a4c64a9",
	"document_url": "https://workdrive.zoho.com/file/hf3e60435a4c7576f4d21a16cfc292a4c64a9"
}

Store Variant Success Response

Copied{
	"status": "success",
	"document_id": "hf3e60435a4c7576f4d21a16cfc292a4c64a9",
	"document_url": "https://workdrive.zoho.com/file/hf3e60435a4c7576f4d21a16cfc292a4c64a9",
	"response_generated_time": 1780912529135
}

Callback Variant Sample Response

Copied{
	"status": "inprogress",
	"status_check_url": "https://pdf.zoho.com/pdfeditor/api/v1/pdf/pages/insert/job/1d358192770dc68d173ca34b8f7c9dcb121ad0bf3d6307b7387be79e76dacf586f9d62cd253c26020f8c3dcf79d51b6b"
}

Callback Variant Success Response

Copied{
	"status": "success",
	"callback_response": {
		"invoked_time": 1780912655806,
		"http_status_code": 200,
		"message": {
			"download_url": "https://pdf.zoho.com/pdfeditor/api/v1/pdf/pages/insert/download/c9f2e5b8a1d4e7f0c3a6b9d2e5f8a1b4",
			"response_generated_time": 1780912656237
		}
	}
}