Why the addimages API matters now

Adding a logo, “PAID” stamp, signature image, watermark badge, or compliance mark to a PDF used to be a repetitive manual step: open a PDF editor, place an image, resize it, export, and repeat for every document. The Zoho PDF Editor API changes that workflow by letting your application insert images into an existing PDF programmatically—so your system can brand invoices, stamp receipts, or apply signatures automatically, without human editing.

That automation is especially valuable when PDFs are generated at scale (invoicing, onboarding packets, shipping labels, legal exhibits, reports). Instead of pushing PDFs through a manual queue, you can treat image overlays as a predictable post-processing step: generate PDF → call addimages → deliver the updated PDF.

This updated article explains how the addimages endpoint works today, what details are clearer in current documentation, and how to implement it reliably in real-world pipelines.

What has changed from “before” to “today”

The image limits are now clearer and easier to implement correctly

Earlier drafts and informal summaries sometimes described the endpoint as inserting “ten or more” images. Today’s documentation makes the limit unambiguous: you can insert up to 10 images per request, with a maximum of 10 MB per image, using PNG or JPEG.

This change matters because limits shape architecture. If you need to place more than 10 images (for example, a multi-page package with multiple stamps per page), you’ll need to split the work into multiple API calls or rethink placement rules so fewer unique images are used.

Domain selection is treated as a real deployment requirement, not a footnote

Implementations used to fail because developers hard-coded a single base domain and later discovered their Zoho account lived in a different data center. Current guidance emphasizes that your API base domain must match your account’s data center (US, EU, IN, and others). In practice, “works on my machine” becomes “works everywhere” only when your code makes the domain configurable.

Placement rules (input_options) are now better understood as a structured model

The biggest source of errors isn’t authentication—it’s formatting input_options. Today it’s much clearer that placement instructions are a structured payload describing:

  • Where the image goes (rectangle coordinates and size)
  • Which pages get it (page ranges)
  • Whether page parity matters (odd/even filtering)

This makes the endpoint more flexible than many first-time users assume. You’re not limited to “one image, one page.” You can define repeatable rules that apply across multiple pages without repeating the same instructions manually.

Storage workflows are more prominent in modern usage

Many teams no longer want “download and then store somewhere else” as a separate step. The WorkDrive storage variant (the /store path) supports workflows where the API saves the result into a managed repository. That’s a meaningful shift in “today’s” best practice: fewer moving parts, clearer ownership, and better auditability—especially for organizations that already use WorkDrive.

What the Insert Images endpoint does

The Insert Images in PDF endpoint is built for overlaying images onto an existing PDF. Your request includes:

LOOKING FOR A ONE-STOP SOLUTION TO YOUR GROWTH NEEDS?

  • A PDF input (uploaded file or a publicly accessible URL)
  • One or more images (uploaded files or publicly accessible URLs)
  • Output settings (such as the modified file name)
  • Placement settings (input_options) that define where the images appear and which pages they apply to

Key constraints you should design around:

  • Input PDF size: up to 50 MB
  • Images per request: up to 10
  • Image formats: PNG and JPEG
  • Image size: up to 10 MB per image

Requirements before you call the API

Choose the correct data-center domain

Zoho APIs are domain-specific by data center. Your addimages request must go to the correct base domain for your Zoho account. Treat this as configuration, not a constant.

A practical recommendation: store the base domain as an environment variable (or tenant setting if you support multiple Zoho accounts). That way you can switch domains without code changes.

Create an OAuth access token with the right scope

Your OAuth token must include the scope:

  • ZohoWriter.pdfEditor.ALL

If you use the WorkDrive storage endpoint, you’ll also need the relevant WorkDrive scopes, and the account you’re using must have WorkDrive available.

Endpoint you’ll call

Insert images and download later

Use a POST request to the addimages path:

/pdfeditor/api/v1/pdf/addimages

Prepend the correct base domain for your data center.

Insert images and store in WorkDrive

Use a POST request to the addimages/store path:

/pdfeditor/api/v1/pdf/addimages/store

This path is designed for storing the final PDF in WorkDrive (rather than only returning a download flow).

How the request body works (multipart/form-data)

The API expects multipart/form-data, typically with four key parts: file, image_files, output_settings, and input_options.

PDF input: file

You can provide the PDF in either of two ways:

  • Upload the PDF file as a binary form part
  • Provide a publicly accessible PDF URL as a string

The “URL input” approach is useful when the PDF already lives in a location accessible to Zoho’s servers, and you want to avoid downloading and re-uploading it in your own infrastructure. The “file upload” approach is safer when your PDFs are private, generated on the fly, or gated behind authentication.

Image input: image_files

You can provide images in either of two ways:

  • Upload one or more image files as binary form parts
  • Provide public image URLs as a comma-separated string

This flexibility makes it easy to support both “local file pipeline” workflows and “cloud-hosted asset” workflows. For example, you might store logos and stamps in object storage and pass them by URL, while uploading PDFs generated dynamically by your app.

Output name: output_settings

This parameter is a JSON string that defines the output file name:

{ "name": "ModifiedFile.pdf" }

When using the WorkDrive storage variant, output settings can also control storage behavior, such as where to place the file and whether to overwrite an existing file (depending on your chosen WorkDrive configuration).

Placement rules: input_options

This is the most important parameter because it controls where images go.

The payload lets you define:

  • image_rect: the rectangle for placement and size (top, left, width, height)
  • page_ranges (optional): which pages receive the image
  • odd_or_even_pages (optional): apply only to odd or even pages

Understanding image_rect

You’ll define the placement rectangle using properties like:

  • top
  • left
  • width
  • height

Zoho examples commonly use pixel-style strings like "25px". The key takeaway is that placement is deterministic once you’ve calibrated the coordinates for your PDF template.

If your PDFs aren’t consistent (different page sizes, varying margins, mixed templates), you may need to segment your workflow by template type and apply different rectangles per template.

Using page_ranges

Page selection can be expressed in several patterns:

  • "1,2,5" for specific pages
  • "2-4,7-9" for multiple ranges
  • "-5" for “from the first page through page 5”
  • "7-" for “from page 7 through the last page”

If page_ranges is omitted or empty, the placement defaults to all pages.

Using odd_or_even_pages

You can restrict placement to odd pages or even pages. This is especially useful when:

  • Your PDFs print double-sided and margins differ by side
  • You want stamps only on customer-facing pages
  • Your document layout alternates positions across pages

If odd_or_even_pages is omitted or empty, placement defaults to all pages.

A clean curl example (with correct structure)

Below is a corrected, readable curl example that matches the required multipart parts. Replace the token value and file paths with your own.

curl --location --request POST "<BASE_DOMAIN>/pdfeditor/api/v1/pdf/addimages" \
  --header "Authorization: Zoho-oauthtoken <ACCESS_TOKEN>" \
  --form 'file=@"/path/to/Sample.pdf"' \
  --form 'image_files=@"/path/to/img.png"' \
  --form 'output_settings={"name":"ModifiedFile.pdf"}' \
  --form 'input_options={"image_rect":{"top":"25px","left":"25px","width":"200px","height":"200px"}}'

A common mistake in older examples is broken quoting around JSON strings or mixing up where output_settings and input_options belong. Keep each JSON value as a single, valid JSON string inside its corresponding form part.

Understanding the asynchronous response workflow

The job-based response model

The addimages endpoint returns an asynchronous job rather than immediately returning the final PDF. That means your application should:

  1. Submit the request
  2. Receive a response containing a status check URL and an “in progress” status
  3. Poll the status URL until the job completes
  4. Retrieve the final PDF using the provided download URL template when the status becomes “success”

This approach is common for PDF processing APIs because the output time depends on file size, page count, and the number of image operations.

Designing a robust polling strategy

To avoid rate limits and reduce unnecessary traffic:

  • Use an increasing backoff between polls (for example, 1s → 2s → 4s → 8s)
  • Stop polling after a reasonable timeout and surface a clear error to your user/system
  • Log the job ID and status check URL for diagnostics

If your architecture supports background workers, this is an ideal job for a queue: submit → enqueue polling task → complete → store output.

Real-world use cases that benefit from addimages

Branding outgoing documents

Many teams use addimages to apply a consistent logo to PDFs generated by different systems. This is especially useful when the upstream generator can’t embed brand assets cleanly or when you need to add branding after the fact.

Adding signatures and stamps

If you capture signatures as images (for example, a signed consent captured on a tablet), addimages can embed that signature at the correct position on the signature page. Stamps like “APPROVED,” “PAID,” “CONFIDENTIAL,” or “DRAFT” are also common.

Compliance overlays and audit marks

Organizations in regulated industries often add compliance marks or document control badges. Using placement rules plus page targeting, you can apply these consistently across standard forms.

Template-based PDF pipelines

If you have a set of known templates (invoice template A, invoice template B, contract template C), you can store placement rectangles per template and apply them deterministically. That’s where addimages becomes “set and forget.”

Troubleshooting: quick checks that resolve most errors

Size and format constraints

Start by confirming:

  • PDF is not larger than 50 MB
  • You’re inserting no more than 10 images
  • Each image is ≤ 10 MB
  • Images are PNG or JPEG

When your system scales, these constraints should be validated before you call the API so failures are predictable and user-facing messages are clear.

Token problems (401 Unauthorized)

If you receive an authorization error, check:

  • The token is not expired
  • The token includes ZohoWriter.pdfEditor.ALL
  • You’re calling the correct data-center domain for the account

For the /store endpoint, confirm WorkDrive scopes and WorkDrive availability as well.

Bad request formatting (400 Bad Request)

Most formatting issues come from JSON strings:

  • output_settings must be valid JSON
  • input_options must be valid JSON
  • Quotes inside JSON must be properly escaped depending on your HTTP client
  • Your multipart boundary must be correct (most libraries handle this automatically)

If you’re using a server-side language, prefer a mature multipart library and build the JSON using native objects → JSON serialization, rather than manual string concatenation.

Best practices for production reliability

Validate inputs before calling the API

Build a validation layer that checks file size, image count, and format. This saves time and reduces API calls that are guaranteed to fail.

Treat placement as a template calibration step

Even with correct rectangles, placement quality depends on page size and layout consistency. Run a calibration pass:

  • Choose a representative PDF for each template
  • Test placement with your chosen rectangles
  • Adjust until the overlay is consistent
  • Store those rectangles in configuration (not hard-coded in source)

Make the base domain configurable

If you support multiple Zoho accounts (or you might migrate between data centers), keep the base domain in configuration. This prevents brittle deployments and makes your integration portable.

Choose download vs. store early

If your system needs to immediately deliver a PDF to the end user, the standard job + download flow is straightforward. If you need retention and centralized access, the WorkDrive storage flow can simplify your downstream steps. The key is to pick the approach that matches your business process, not just the one that seems easiest in a quick test.

Conclusion

The Zoho PDF Editor addimages API is a practical way to automate one of the most common “last-mile” PDF tasks: placing images onto an existing PDF with consistent positioning and predictable page rules. The modern documentation makes today’s limits and structure clearer—especially around the maximum of 10 images per request, supported image types, file size constraints, domain-specific endpoints, and the structured input_options model for page targeting and placement.

If you’d like, paste your current input_options JSON (with your intended placement goal—logo, signature, stamp, etc.), and I’ll rewrite it into a clean, validated payload you can drop into your code without quoting errors.

© Image credits to Steve Johnson

LOOKING FOR A ONE-STOP SOLUTION TO YOUR GROWTH NEEDS?

Posted in CRM