Site icon Little Marketing Book

Pagination That Ships: What’s New in Zoho PDF Editor API Page Number Insertion (and How to Use It Today)

respect

Why this update matters

If you’ve ever had to manually add “Page X of Y” to a report, exhibit bundle, invoice packet, or client deliverable, you already know the pain: different sources generate different PDFs, page counts change at the last minute, and headers/footers rarely match across systems. Zoho PDF Editor’s Insert Page Numbers into PDF API exists to solve that problem programmatically—so pagination becomes a repeatable step in your document pipeline, not a manual cleanup task.

An earlier quickstart-style guide to this API typically focused on the basics: an endpoint, a file upload, placeholders like <<page_number>> and <<total_pages>>, and an asynchronous response you poll until a download link appears. That foundation is still accurate. What’s changed “from before to today” is how complete and configurable the integration can be when you use the full set of options now documented: page ranges (sections), font formatting defaults, numbering patterns, date insertion configuration, and pixel-based positioning offsets. The result is less guesswork, more consistency, and fewer “Why is page 1 missing a footer?” surprises.

This article walks through how to use the API today, and highlights what’s different compared to the earlier, minimal approach—so you can upgrade your implementation without rewriting your whole workflow.

What the API does (and what it’s for)

At its core, the API inserts page numbers into a PDF. But the real value is the customization: you can control font, style, numbering pattern, and placement in the header or footer.

Common real-world uses

You’d typically call this API when you want to:

Those goals haven’t changed—but the “today” version of the API documentation makes it clearer how to deliver a consistent house style across many PDFs with less manual tweaking.

The endpoint and authentication you need today

To insert page numbers, you send a POST request to the Insert Page Numbers endpoint under your Zoho API regional domain. (The exact domain varies by region/account setup, which is why many implementations treat the domain as a configurable environment value.)

To call it, your OAuth token must be generated with the scope:

What changed vs earlier quickstarts?

Earlier summaries often wrote the endpoint in a more generic or inconsistent way (sometimes even showing non-TLS examples). Today’s documentation is more explicit about the endpoint structure and the need to use the correct regional domain. That sounds small, but it’s a practical improvement: fewer integration errors caused by mismatched domains.

Request structure: multipart form data, with three key parts

This API uses a multipart/form-data POST request and expects three major inputs:

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

  1. file (required)
  2. input_options (JSON string)
  3. output_settings (JSON)

file (required)

You can provide the PDF in two ways using the same parameter:

Zoho also sets clear limits:

What changed vs earlier quickstarts?

The limits were sometimes mentioned briefly, but today’s documentation places them prominently next to the file parameter. If you’re building a production workflow, that matters because you can enforce the constraints early (before you upload) and avoid failed jobs downstream.

input_options (JSON string)

input_options contains the full configuration, including page_number_settings and the layout details for where the text should appear.

This is where “today” looks very different from “before.” Earlier quickstarts usually stopped at: “Put page text in footer center.” Now you can define sections, apply rules to specific page ranges, configure fonts and numbering types, optionally insert dates, and nudge placement with pixel offsets.

output_settings (JSON)

This is straightforward: you specify the output PDF name, such as "ModifiedFile.pdf". In automated workflows, teams often generate output names consistently (for example, appending -paginated or a timestamp) so downstream systems can identify the processed file without opening it.

The placeholders that still power everything

The earlier minimal approach to this API relied on placeholders in a string, and that’s still the simplest way to get useful results. Two key placeholders are:

Example: “Page X of Y”

A common pattern is:

You can place that string in the header or footer, then decide whether it appears left, center, or right.

What changed vs earlier quickstarts?

The placeholders are the same, but today the documentation is clearer about where they can be used (inside text fields for header/footer placement blocks), and how you can reuse the same placeholders across multiple sections and layouts.

The biggest update: sections and page ranges

Today’s documentation highlights (and explains more clearly) the concept that unlocks advanced layouts: sections.

sections is a list of configuration blocks, and each block can apply to a specific page range (or all pages by default).

Using range to target specific pages

You can set a page range such as:

Key behavior to understand:

Why this matters in practice

This range feature is what makes professional document formatting possible in automated workflows, for example:

Earlier quickstarts typically didn’t mention range-based formatting at all; today it’s one of the first tools you’ll reach for when your PDFs have front matter, appendices, or mixed formatting requirements.

Formatting controls: fonts, size, and style (with defaults)

The updated documentation specifies a format object that can include font settings such as:

It also documents defaults:

Supported values you can rely on

In practice, you can treat formatting as a layered system:

What changed vs earlier quickstarts?

Minimal guides often implied you could style text, but didn’t spell out defaults or common style values. Today’s documentation makes formatting predictable: even if you omit font settings, you know what you’ll get.

Numbering patterns: Arabic, letters, Roman numerals, and start value

The numbering_config object defines how numbering appears and where it begins. Two particularly useful properties are:

Supported numbering types

Zoho supports multiple numbering patterns, including:

If you don’t specify numbering configuration, it defaults to standard 1,2,3 numbering.

What changed vs earlier quickstarts?

Earlier quickstarts usually treated page numbering as “always 1,2,3.” Today you can build publishing-style layouts—like Roman numeral front matter—without special handling outside the API.

Date insertion: optional, but now clearly defined

Another practical “today” addition is date_config, which allows inserting dates alongside pagination using a controlled format.

A key rule:

Why date configuration matters

In real workflows, the date is often paired with pagination in headers/footers:

The key is consistency. Locale/timezone settings help avoid confusing edge cases when jobs run around midnight or when documents are generated for different regions.

What changed vs earlier quickstarts?

Earlier minimal summaries rarely mentioned adding dates alongside page numbering. Today it’s a first-class option, with clear validation rules that help teams avoid inconsistent output.

Header and footer placement: left, center, right—at least one is required

The layout rules are straightforward but important:

Offsets: pixel-based positioning for precision

The documentation also explains offsets, which let you set positioning adjustments in pixels using:

Offsets are optional, but they become essential when you need to:

What changed vs earlier quickstarts?

Previously, most examples only showed “footer center.” Today you can use offsets to fit pagination into an existing template, avoid collisions, and align content across multiple PDF sources.

A modern “today” configuration example (conceptual)

To illustrate how the “today” version is more capable than the earlier minimal example, consider a configuration that:

The key takeaway isn’t the exact JSON you copy/paste—it’s the expanded design surface:

sections + format + numbering_config + (optional) date_config + header/footer placements + offsets

That combination is what turns a quickstart into a production-quality pagination system.

Response handling: asynchronous job flow (and what’s clarified today)

This API runs as an asynchronous job. When you submit the request, you initially receive an “in progress” status and a status-check URL you can poll.

When the job completes successfully, you receive a success status and a downloadable output location.

status_url vs status_check_url

Some descriptions refer to a “status URL,” while example payloads may label it slightly differently. In practice, treat the returned URL field as the authoritative link for polling—your code should read the response property and follow it, rather than hardcoding a single field name.

What changed vs earlier quickstarts?

Older short guides often just said “poll status until you get a download link.” Today, the documentation emphasizes that you’re monitoring a scheduled job and shows both the in-progress and success states, which makes it easier to build robust polling and error handling.

Practical upgrade guide: how your implementation changes from earlier to today

If your earlier integration only did “footer center Page X of Y,” you don’t need to throw it away. You can upgrade in layers.

Step 1: Keep your existing placeholders and async handling

Your foundation stays the same:

Step 2: Use defaults deliberately to reduce configuration noise

Today’s documentation clarifies what happens if you omit format and numbering config:

That means you can intentionally omit fields you don’t care about and still get consistent results. Earlier guides often led teams to over-specify everything “just in case.”

Step 3: Introduce sections for professional layouts

Once you adopt sections (and optionally range), you can solve the most common pagination pain points:

This is one of the clearest “before vs today” improvements: your pagination becomes layout-aware instead of one-size-fits-all.

Step 4: Use offsets when you need pixel-perfect alignment

If you’re integrating into branded templates, offsets help you align with letterheads, stamps, pre-printed footer art, or signature blocks. Offsets are also a reliable fix when different source systems generate slightly different page margins.

Step 5: Add date insertion only where it adds value

If you want “Generated on …” alongside pagination, date_config supports it—just remember that locale and timezone become required when you turn it on.

Best practices for production use

Validate file limits before uploading

Since the API caps inputs at 50 MB and 150 pages, add a pre-check in your pipeline so you fail early and clearly.

Standardize a “house footer” and reuse it everywhere

Define one or two canonical text templates:

Then reuse them across projects so your output looks consistent.

Make polling resilient

Because the API is asynchronous, build polling that:

Avoid over-formatting unless needed

Defaults exist for a reason. If you only need page numbers, you can skip font config and numbering config and still get predictable output.

Closing thoughts: the “today” API is about consistency, not just numbering

The earlier way of thinking about this endpoint was: “Add page numbers.” The modern, fully documented approach is: build a consistent header/footer system across every PDF your workflow produces.

That shift—supported by sections, ranges, formatting defaults, numbering patterns, date insertion rules, and pixel offsets—means your team can treat pagination as a reliable automation step rather than a last-minute formatting chore. And because the job runs asynchronously with clear in-progress and success outcomes, it fits neatly into high-volume systems as well as one-off document pipelines.

© Image credits to Sharon Snider

Exit mobile version