Insert Pages via Callback

Purpose

This API allows you to insert pages from multiple source PDF files into an existing PDF at specified positions. Unlike the standard Insert Pages API, this endpoint supports up to 10 source files in a single request and delivers the result via a callback URL.

Quick Reference

Property	Value
Method	POST
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 (URL)	Mandatory	Upload the existing PDF file into which pages from other PDFs will be inserted using one of the following methods: upload the PDF directly from your local drive or desktop, or provide a publicly accessible web URL using the same parameter. Note: The maximum file size allowed for the input PDF is 50 MB.
source_file	File or String (URL)	Mandatory	Upload the source PDF file(s) to be inserted using one of the following methods: upload the PDF directly from your local drive or desktop, or provide a publicly accessible web URL using the same parameter. You can pass this parameter multiple times (up to 10 source files) in a single request. Note: The maximum allowed file size for each source PDF is 50 MB.
input_options	[ { "page_number": 3, "position": "after", "page_ranges": ["1", "4-9"] }, { "page_number": 5, "position": "before", "page_ranges": ["2-6"] } ]	Mandatory	Specify the insert configuration as a JSON array. The number of objects in the array must match the number of source files provided.
callback	{ "invoke_url": "<callback_url>", "timeout": 60, "retry_interval": 60, "headers": { "header_name": "header_value" }, "http_method_type": "post" }	Mandatory	Specify the callback delivery configuration as a JSON object.

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 (for example, "1") and/or ranges (for example, "4-9").	All pages from the source PDF

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

A maximum of 10 source files can be passed in a single request. The number of objects in the input_options array must match the number of source files provided.
Each source file is mapped to its corresponding input_options object based on the order in which they are provided.
The page_ranges parameter accepts individual page numbers and page ranges. Invalid page numbers or ranges exceeding the source file's total page count will result in an error.
The maximum file size allowed for both the original PDF and each source PDF is 50 MB.
To use this API, an OAuth token should be generated with the following scope: ZohoWriter.pdfEditor.ALL

Possible Errors

Refer to the following pages for the list of possible errors for this API:

General Errors

Sample Request

Copiedcurl --location --request POST "https://{zohoapis_domain}/pdfeditor/api/v1/pdf/pages/insert/callback" \
  --header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
  --form 'original_file=@/Users/username/Documents/Original.pdf' \
  --form 'source_file=@/Users/username/Documents/Source1.pdf' \
  --form 'source_file=@/Users/username/Documents/Source2.pdf' \
  --form 'input_options=[
    {"page_number": 3, "position": "after", "page_ranges": ["1", "4-9"]},
    {"page_number": 5, "position": "before", "page_ranges": ["2-6"]}
  ]' \
  --form 'callback={
    "invoke_url": "https://www.example.com/v1/api/callback/savecallback",
    "timeout": 120,
    "retry_interval": 60,
    "headers": {"Authorization": "Bearer <your_token>"},
    "http_method_type": "post"
  }'

Sample Response

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

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/callback/inserted_c1e9f2a4d6b8e3f5c7a9d1b3e5f7a9b1.zip",
      "response_generated_time": 1780912656237
    }
  }
}