Insert Images in PDF
Purpose
This API allows you to insert one or more images into an existing PDF and either download the modified file or store it in Zoho WorkDrive.
Quick Reference
| Property | Value |
|---|---|
| Method | POST |
| Request URL (Download) | https://{zohoapis_domain}/pdfeditor/api/v1/pdf/addimages |
| Request URL (Store) | https://{zohoapis_domain}/pdfeditor/api/v1/pdf/addimages/store |
Body Parameters
| Parameter | Value | Mandatory/Optional | Description |
|---|---|---|---|
| file | File or String | Mandatory | Upload the PDF file from your local drive or desktop. If the PDF file is available via a publicly accessible web URL, you can provide the URL using the same parameter. |
| image_files | Files or String | Mandatory | Upload image files from your local drive or desktop. If the image files are publicly accessible web URLs, you can pass them as a comma-separated list using the same parameter. |
| input_options | [ [ { "image_rect": { "top": "25px", "left": "25px", "width": "200px", "height": "200px" }, "page_ranges": "1,2-5,7-", "odd_or_even_pages": "odd" }, ... ], ... ] | Mandatory | Specify image position, page scope, and placement behavior for each uploaded image. The outer array order should match the order of files passed in image_files. |
| 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. |
input_options Parameters
| Parameter | Data Type | Possible Values | Default Value |
|---|---|---|---|
| image_rect | JSON Object | {"top":"25px","left":"25px","width":"200px","height":"200px"} | – |
| page_ranges | String | "1,2,5", "2-4,7-9", "-5", "7-" | all pages |
| odd_or_even_pages | String | "odd", "even" | all pages |
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 |
Notes and Limits
- The maximum file size allowed for the input PDF is 50 MB, and the PDF cannot exceed 400 pages.
- Up to 10 images can be inserted in a single request.
- Maximum size per image is 10 MB. Supported image file formats are png and jpeg.
- If page_ranges or odd_or_even_pages is omitted, image insertion applies to all pages by default.
- The store variant requires a Zoho WorkDrive account.
- To use the download variant, 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 Variant Sample Request
Copiedcurl --location --request POST "https://www.zohoapis.com/pdfeditor/api/v1/pdf/addimages" \
--header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
--form 'file=@"/Users/username/Documents/Sample.pdf"' \
--form ‘image_files=@"/Users/username/Documents/img.png”’ \
--form 'output_settings=“{\”name\”:\”ModifiedFile.pdf\"}"' \
--form 'input_options="{\"image_rect\":{\"top\":\"25px\",\"left\":\"25px\",\"height\":\"200px\",\"width\":\"200px\"}}"'Store Variant Sample Request
Copiedcurl --location --request POST "https://www.zohoapis.com/pdfeditor/api/v1/pdf/addimages/store" \
--header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
--form 'file=@"/Users/username/Documents/Sample.pdf"' \
--form ‘image_files=@"/Users/username/Documents/img.png”’ \
--form 'output_settings=“{\”name\”:\”ModifiedFile.pdf\"}"' \
--form 'input_options="{\"image_rect\":{\"top\":\"25px\",\"left\":\"25px\",\"height\":\"200px\",\"width\":\"200px\"}}"'Download Variant Sample Response
Copied{
"status_check_url": "https://pdf.zoho.com/pdfeditor/api/v1/pdf/addimages/job/f931a01183b33",
"status": inprogress
}