The quiet upgrade: why image insertion looks different today than it did “before”

A few years ago, most teams treated “add an image to a PDF” as a basic finishing step—drop a logo on page one, stamp a document once, or attach a signature image at the end. The idea was simple, but implementations were often fragile: hard-coded coordinates, no page targeting beyond a single page number, and a workflow that assumed you’d always upload files from a server that had the PDF sitting on disk.

Today, the way developers use Zoho PDF Editor’s Insert Images in PDF API is more mature. The endpoint is the same concept—overlay images onto an existing PDF—but the playbook has evolved:

  • You don’t just “place an image,” you place it with rules (ranges, odd/even filtering, repeatable placement).
  • You don’t always upload assets; you often pass public URLs for the PDF and image(s), which simplifies serverless pipelines.
  • You don’t always download the output; many teams now prefer the WorkDrive store variant when they want an audit-friendly destination and less downstream file handling.
  • You design around the platform’s bounds (PDF size, image size, and per-request image count), and you plan multi-call strategies when needed.

This updated article focuses on the most practical part of the endpoint: recipes—repeatable patterns for logos, stamps, signatures, and page-targeted overlays—plus what’s changed from the “before” mindset to the “today” approach.

What the Insert Images endpoint is best at

The Insert Images endpoint is purpose-built for programmatically overlaying images onto PDFs. In real-world terms, it’s ideal for:

  • Branding invoices and reports with logos
  • Applying “PAID,” “APPROVED,” or “CONFIDENTIAL” stamps
  • Dropping in signature images at consistent locations
  • Adding compliance badges or internal routing marks
  • Inserting visual markers in long documents without manual editing

The power isn’t only that it inserts images—it’s that it can do so predictably, at specific locations, on specific pages, at scale.

How the control knobs work: input_options, page_ranges, and odd_or_even_pages

Before jumping into recipes, it helps to frame the three knobs you’ll use most:

image_rect: position and size as a rectangle

image_rect is where you define where the image goes and how big it is. It uses rectangle-style properties:

  • top
  • left
  • width
  • height

Zoho examples typically use pixel-style values such as "25px", which makes it straightforward to treat placement like a layout coordinate system. The most important takeaway: once you calibrate these values for a template, you get repeatable placement across documents of the same format.

page_ranges: control which pages receive the image

Rather than stamping everything everywhere, you can target pages using flexible patterns, including:

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

If you omit page_ranges (or pass it empty), the default behavior is typically to apply the overlay across all pages—useful for watermarks, but risky if you only meant page one.

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

odd_or_even_pages: target by page parity

Sometimes the layout shifts between odd and even pages (especially with duplex printing or mirrored margins). This option lets you apply overlays to:

  • "odd" pages only
  • "even" pages only

As with page_ranges, leaving this blank generally results in “all pages,” so you should set it intentionally when parity matters.

The “before vs. today” shift in everyday usage

Before: single placement thinking

Earlier implementations often treated overlaying as a one-off step:

  • One image
  • One page
  • One coordinate rectangle

That approach still works for trivial use cases, but it doesn’t age well when your PDFs vary, your templates change, or you need multiple overlays.

Today: rule-driven placement

Modern usage is more like template automation:

  • The same overlay can be applied across a range of pages without repeating instructions.
  • “Odd pages only” becomes a first-class behavior for invoice packets and duplex layouts.
  • You can define consistent “zones” (header logo zone, stamp zone, signature zone) and reuse them across many PDFs.
  • You can run serverless workflows using URLs rather than storing everything locally.
  • You can store results directly in WorkDrive when your process demands a controlled destination.

In short: today’s integrations behave more like a pipeline and less like a one-time edit.

Recipe 1: Put a business logo on the top-left of pages 1–3

This is a common branding pattern: your first few pages are customer-facing, and you want consistent identity without forcing the upstream PDF generator to embed brand assets.

How it works

Use image_rect to define the logo’s location and size, and page_ranges to apply it to pages 1 through 3.

{
  "image_rect": { "top": "25px", "left": "25px", "width": "140px", "height": "40px" },
  "page_ranges": "1-3"
}

Why this recipe matters more today

“Before,” teams often hard-coded page 1 only. “Today,” page ranges are the difference between a polished multi-page packet and an inconsistent branded document where only the cover page looks official.

Practical tips

  • Keep logos small and aligned to a predictable header area.
  • If your PDFs have variable top margins, calibrate top across representative samples.
  • Store the rectangle values as configuration per template rather than hard-coding them.

Recipe 2: Stamp only odd pages as “PAID”

Invoices and statements sometimes alternate layouts per page, especially when the first page is a summary and subsequent pages are line-item detail. If your design expects stamps only on the odd pages (for example, customer-facing pages), parity targeting saves time and prevents layout collisions.

How it works

Use odd_or_even_pages: "odd" with a stamp-sized rectangle.

{
  "image_rect": { "top": "120px", "left": "320px", "width": "220px", "height": "220px" },
  "odd_or_even_pages": "odd"
}

What changed from before to today

Older workflows often duplicated documents or used separate PDF templates to control stamping behavior. Today, parity targeting makes it a single rule—cleaner logic, fewer template variants, fewer edge cases.

Practical tips

  • Use a transparent PNG stamp so the PDF content remains visible underneath.
  • Test on multi-page invoices to ensure the stamp doesn’t overlap totals or addresses.
  • If you also use page_ranges, remember you’re effectively combining filters (only pages in the range and matching odd/even).

Recipe 3: Apply a marker from page 7 onward

Long documents—contracts, agreements, policy packets—often need a visual cue that begins after a certain section. Instead of stamping the whole document (which may be undesirable for signature pages or covers), you can begin stamping at a specific page and continue to the end.

How it works

Use the open-ended range "7-".

{
  "image_rect": { "top": "25px", "left": "25px", "width": "120px", "height": "120px" },
  "page_ranges": "7-"
}

Why this is a “today” pattern

In the past, many teams solved this with manual merges or by splitting PDFs. Modern API usage favors rule-driven overlays because it’s more maintainable: if a template grows from 10 pages to 14 pages, the rule still holds.

Practical tips

  • Use this for section markers, internal routing stamps, or “continued” badges.
  • If you need “from page N onward, but skip the last page,” you may need a two-step strategy: stamp the range, then re-run with a corrective overlay strategy (or design your workflow so the last page doesn’t conflict).

Recipe 4: Insert images using public URLs (no file upload required)

This recipe matters because it changes your infrastructure needs. If your pipeline receives a PDF URL and an image URL, you can call the API without first downloading files into your own storage.

How it works

  • Provide the PDF as a publicly accessible URL in the file parameter.
  • Provide images as a comma-separated list of public image URLs in image_files.

What changed from before to today

Earlier integrations assumed a traditional server that stores files locally. Today, many workflows are event-driven and serverless, and URL-based inputs reduce the “download → store → upload” overhead.

Practical tips

  • “Publicly accessible” must truly mean accessible to Zoho’s servers—no authentication walls, expiring links without enough TTL, or IP-restricted assets.
  • If you must keep assets private, stick to file upload.
  • If your URLs are time-limited, ensure they remain valid long enough for asynchronous processing and retries.

Recipe 5: Use PNG when you need transparency

Both PNG and JPEG are supported, but transparency is often the difference between a professional overlay and a clunky one.

When PNG is the better choice

  • Logos with transparent backgrounds
  • Stamps placed over text or graphics
  • Signature images that shouldn’t show a white rectangle behind them

JPEG doesn’t support transparency, so it can introduce unwanted background blocks behind your overlay.

Today’s best practice

Even if your team historically used JPEG “because it’s smaller,” modern workflows typically standardize on PNG for overlay assets. The slight increase in size is often worth the visual quality and the flexibility.

Recipe 6: Stay within platform bounds to prevent job failure

A big part of “today’s” maturity is designing around documented limits instead of discovering them through failures.

Key bounds to respect

  • Maximum input PDF size: 50 MB
  • Maximum images per PDF request: 10
  • Maximum size per image: 10 MB
  • Supported image types: PNG and JPEG

What changed from before to today

Earlier articles often glossed over limits, treating them as edge cases. In production, limits are architecture constraints. Modern teams build validation at the edges:

  • Reject or downscale oversized images before the API call
  • Enforce image count rules upfront
  • Split large jobs into multiple calls as a deliberate workflow

How to handle “more than 10 images”

If you truly need more than 10 overlays:

  • Break the work into multiple API calls.
  • Chain outputs: the result of call 1 becomes the input PDF for call 2.
  • Group overlays logically (branding first, stamps second, signatures last) so you can debug and roll back by stage.

This chained approach is the “today” solution—predictable, modular, and easier to troubleshoot than a single mega-request that fails halfway through.

Recipe 7: Store the result directly in WorkDrive (optional but increasingly common)

Many document workflows don’t end at “download the PDF.” They end at “store it where the business can find it, share it, audit it, and retain it.”

How it works conceptually

Instead of using the standard insert-and-download flow, you use the addimages/store variant to save the output directly to WorkDrive.

What changed from before to today

“Before,” teams typically handled storage themselves: download the output, then upload it to a drive, bucket, or document system. “Today,” direct storage reduces integration complexity:

  • Fewer moving parts
  • Clearer destination semantics
  • Better alignment with governance workflows if your org already uses WorkDrive

Practical tips

  • You’ll need the appropriate WorkDrive permissions/scopes in addition to the PDF Editor scope.
  • Decide whether to overwrite existing files or store new versions, depending on your business rules.
  • Treat storage destination (folder selection) as configuration, especially across environments (dev/stage/prod).

Putting it all together: a “today-style” overlay strategy

If you want your integration to feel modern and resilient, combine the recipes into a simple overlay pipeline:

Step 1: Branding layer

  • Apply logo to pages 1–3 (Recipe 1)

Step 2: Status stamping layer

  • Apply “PAID” to odd pages (Recipe 2)

Step 3: Document control layer

  • Apply markers from a page onward for long packets (Recipe 3)

Step 4: Asset strategy

  • Use PNG for overlays that require transparency (Recipe 5)
  • Use URLs for serverless workflows when assets can be public (Recipe 4)

Step 5: Delivery strategy

  • Download for immediate distribution
  • Store in WorkDrive for long-term retention (Recipe 7)

Step 6: Guardrails

  • Validate file sizes and image counts up front (Recipe 6)

That structure is the real “today” upgrade: your integration becomes a predictable sequence of small, testable operations instead of one brittle call.

Common mistakes that still show up (and how “today” teams avoid them)

Incorrect JSON formatting in input_options

Modern teams serialize JSON from objects (in their language of choice) instead of manually building strings. This prevents broken quotes, missing braces, and malformed payloads.

Coordinates calibrated on one PDF only

If you calibrate image_rect on a single example PDF, you risk misalignment across variants. Today’s best practice is to calibrate per template family and store the coordinates in configuration.

Forgetting defaults apply to all pages

Leaving out page_ranges or odd_or_even_pages can unintentionally stamp every page. Modern implementations treat page targeting as explicit configuration, not an optional afterthought.

Overlooking the asynchronous nature of the job

Because processing is job-based, your pipeline must handle polling, retries, and timeouts. Today’s approach is to implement this as a background worker or queue task rather than blocking a user request.

Conclusion: the endpoint didn’t just add features—teams changed how they use it

The Insert Images API has always been about placing images onto PDFs. What’s changed is how teams think about it. The “before” mindset was manual replacement: “How do I mimic what a person does in an editor?” The “today” mindset is workflow automation: “How do I apply repeatable placement rules across many PDFs, reliably, with clean storage and scalable inputs?”

If you adopt the recipes above—logo ranges, odd/even stamping, onward ranges, URL-based inputs, PNG transparency, limit-aware chaining, and WorkDrive storage—you end up with an integration that feels like a real document pipeline, not a fragile script.

If you paste your exact use case (invoice, contract, report, packet) and where you want the overlay placed (top-left header, center stamp, signature block, etc.), I can translate these recipes into a single cohesive input_options design and a practical multi-step plan that respects the 10-image constraint without complicating your system.

© Image credits to Steve Johnson

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

Posted in CRM