If you\u2019ve ever had to manually add \u201cPage X of Y<\/a>\u201d 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<\/a>\u2019s Insert Page Numbers into PDF<\/strong> API exists to solve that problem programmatically\u2014so pagination becomes a repeatable step in your document pipeline, not a manual cleanup task.<\/p>\n\n\n\n An earlier quickstart-style guide to this API typically focused on the basics: an endpoint, a file upload, placeholders like This article walks through how to use the API <\/a>today, and highlights what\u2019s different compared to the earlier, minimal approach\u2014so you can upgrade your implementation without rewriting your whole workflow.<\/p>\n\n\n\n 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<\/strong> in the header or footer.<\/p>\n\n\n\n You\u2019d typically call this API when you want to:<\/p>\n\n\n\n Those goals haven\u2019t changed\u2014but the \u201ctoday\u201d version of the API documentation makes it clearer how to deliver a consistent house style across many PDFs with less manual tweaking.<\/p>\n\n\n\n To insert page numbers, you send a POST request to the Insert Page Numbers<\/strong> 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.)<\/p>\n\n\n\n To call it, your OAuth token must be generated with the scope:<\/p>\n\n\n\n Earlier summaries often wrote the endpoint in a more generic or inconsistent way (sometimes even showing non-TLS examples). Today\u2019s documentation is more explicit about the endpoint structure and the need to use the correct regional domain. That sounds small, but it\u2019s a practical improvement: fewer integration errors caused by mismatched domains.<\/p>\n\n\n\n This API uses a You can provide the PDF in two ways using the same parameter:<\/p>\n\n\n\n Zoho also sets clear limits:<\/p>\n\n\n\n The limits were sometimes mentioned briefly, but today\u2019s documentation places them prominently next to the file parameter. If you\u2019re building a production workflow, that matters because you can enforce the constraints early (before you upload) and avoid failed jobs downstream.<\/p>\n\n\n\n This is where \u201ctoday\u201d looks very different from \u201cbefore.\u201d Earlier quickstarts usually stopped at: \u201cPut page text in footer center.\u201d Now you can define sections<\/strong>, apply rules to specific page ranges, configure fonts and numbering types, optionally insert dates, and nudge placement with pixel offsets.<\/p>\n\n\n\n This is straightforward: you specify the output PDF name, such as The earlier minimal approach to this API relied on placeholders in a string, and that\u2019s still the simplest way to get useful results. Two key placeholders are:<\/p>\n\n\n\n A common pattern is:<\/p>\n\n\n\n You can place that string in the header or footer, then decide whether it appears left, center, or right.<\/p>\n\n\n\n The placeholders are the same, but today the documentation is clearer about where<\/em> they can be used (inside Today\u2019s documentation highlights (and explains more clearly) the concept that unlocks advanced layouts: sections<\/strong>.<\/p>\n\n\n\n You can set a page range such as:<\/p>\n\n\n\n Key behavior to understand:<\/p>\n\n\n\n This range feature is what makes professional document formatting possible in automated workflows, for example:<\/p>\n\n\n\n Earlier quickstarts typically didn\u2019t mention range-based formatting at all; today it\u2019s one of the first tools you\u2019ll reach for when your PDFs have front matter, appendices, or mixed formatting requirements.<\/p>\n\n\n\n The updated documentation specifies a It also documents defaults:<\/p>\n\n\n\n In practice, you can treat formatting as a layered system:<\/p>\n\n\n\n Minimal guides often implied you could style text, but didn\u2019t spell out defaults or common style values. Today\u2019s documentation makes formatting predictable: even if you omit font settings, you know what you\u2019ll get.<\/p>\n\n\n\n The Zoho supports multiple numbering patterns, including:<\/p>\n\n\n\n If you don\u2019t specify numbering configuration, it defaults to standard 1,2,3 numbering.<\/p>\n\n\n\n Earlier quickstarts usually treated page numbering as \u201calways 1,2,3.\u201d Today you can build publishing-style layouts\u2014like Roman numeral front matter\u2014without special handling outside the API.<\/p>\n\n\n\n Another practical \u201ctoday\u201d addition is A key rule:<\/p>\n\n\n\n In real workflows, the date is often paired with pagination in headers\/footers:<\/p>\n\n\n\n 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.<\/p>\n\n\n\n Earlier minimal summaries rarely mentioned adding dates alongside page numbering. Today it\u2019s a first-class option, with clear validation rules that help teams avoid inconsistent output.<\/p>\n\n\n\n The layout rules are straightforward but important:<\/p>\n\n\n\n The documentation also explains Offsets are optional, but they become essential when you need to:<\/p>\n\n\n\n Previously, most examples only showed \u201cfooter center.\u201d Today you can use offsets to fit pagination into an existing template, avoid collisions, and align content across multiple PDF sources.<\/p>\n\n\n\n To illustrate how the \u201ctoday\u201d version is more capable than the earlier minimal example, consider a configuration that:<\/p>\n\n\n\n The key takeaway isn\u2019t the exact JSON you copy\/paste\u2014it\u2019s the expanded design surface:<\/p>\n\n\n\n sections + format + numbering_config + (optional) date_config + header\/footer placements + offsets<\/strong><\/p>\n\n\n\n That combination is what turns a quickstart into a production-quality pagination system.<\/p>\n\n\n\n This API runs as an asynchronous job. When you submit the request, you initially receive an \u201cin progress\u201d status and a status-check URL you can poll.<\/p>\n\n\n\n When the job completes successfully, you receive a success status and a downloadable output location.<\/p>\n\n\n\n Some descriptions refer to a \u201cstatus URL,\u201d while example payloads may label it slightly differently. In practice, treat the returned URL field as the authoritative link for polling\u2014your code should read the response property and follow it, rather than hardcoding a single field name.<\/p>\n\n\n\n Older short guides often just said \u201cpoll status until you get a download link.\u201d Today, the documentation emphasizes that you\u2019re monitoring a scheduled job and shows both the in-progress and success states, which makes it easier to build robust polling and error handling.<\/p>\n\n\n\n If your earlier integration only did \u201cfooter center Page X of Y,\u201d you don\u2019t need to throw it away. You can upgrade in layers.<\/p>\n\n\n\n Your foundation stays the same:<\/p>\n\n\n\n Today\u2019s documentation clarifies what happens if you omit format and numbering config:<\/p>\n\n\n\n That means you can intentionally omit fields you don\u2019t care about and still get consistent results. Earlier guides often led teams to over-specify everything \u201cjust in case.\u201d<\/p>\n\n\n\n Once you adopt This is one of the clearest \u201cbefore vs today\u201d improvements: your pagination becomes layout-aware instead of one-size-fits-all.<\/p>\n\n\n\n If you\u2019re 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.<\/p>\n\n\n\n If you want \u201cGenerated on \u2026\u201d alongside pagination, Since the API caps inputs at 50 MB and 150 pages, add a pre-check in your pipeline so you fail early and clearly.<\/p>\n\n\n\n Define one or two canonical text templates:<\/p>\n\n\n\n Then reuse them across projects so your output looks consistent.<\/p>\n\n\n\n Because the API is asynchronous, build polling that:<\/p>\n\n\n\n Defaults exist for a reason. If you only need page numbers, you can skip font config and numbering config and still get predictable output.<\/p>\n\n\n\n The earlier way of thinking about this endpoint was: \u201cAdd page numbers.\u201d The modern, fully documented approach is: build a consistent header\/footer system across every PDF your workflow produces<\/strong>.<\/p>\n\n\n\n That shift\u2014supported by sections, ranges, formatting defaults, numbering patterns, date insertion rules, and pixel offsets\u2014means 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.<\/p>\n\n\n\n \u00a9 Image credits to Sharon\u00a0Snider<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<<page_number>><\/code> and <<total_pages>><\/code>, and an asynchronous response you poll until a download link appears. That foundation is still accurate. What\u2019s changed \u201cfrom before to today\u201d is how complete and configurable<\/strong> 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<\/strong>. The result is less guesswork, more consistency, and fewer \u201cWhy is page 1 missing a footer?\u201d surprises.<\/p>\n\n\n\nWhat the API does (and what it\u2019s for)<\/h2>\n\n\n\n
Common real-world uses<\/h3>\n\n\n\n
\n
The endpoint and authentication you need today<\/h2>\n\n\n\n
\n
ZohoWriter.pdfEditor.ALL<\/code><\/li>\n<\/ul>\n\n\n\nWhat changed vs earlier quickstarts?<\/h3>\n\n\n\n
Request structure: multipart form data, with three key parts<\/h2>\n\n\n\n
multipart\/form-data<\/code> POST request and expects three major inputs:<\/p>\n\n\n\n\n
file<\/code> (required)<\/li>\n\n\n\ninput_options<\/code> (JSON string)<\/li>\n\n\n\noutput_settings<\/code> (JSON)<\/li>\n<\/ol>\n\n\n\nfile (required)<\/h3>\n\n\n\n
\n
\n
What changed vs earlier quickstarts?<\/h4>\n\n\n\n
input_options (JSON string)<\/h3>\n\n\n\n
input_options<\/code> contains the full configuration, including page_number_settings<\/code> and the layout details for where the text should appear.<\/p>\n\n\n\noutput_settings (JSON)<\/h3>\n\n\n\n
\"ModifiedFile.pdf\"<\/code>. In automated workflows, teams often generate output names consistently (for example, appending -paginated<\/code> or a timestamp) so downstream systems can identify the processed file without opening it.<\/p>\n\n\n\nThe placeholders that still power everything<\/h2>\n\n\n\n
\n
<<page_number>><\/code><\/li>\n\n\n\n<<total_pages>><\/code><\/li>\n<\/ul>\n\n\n\nExample: \u201cPage X of Y\u201d<\/h3>\n\n\n\n
\n
Page <<page_number>> of <<total_pages>><\/code><\/li>\n<\/ul>\n\n\n\nWhat changed vs earlier quickstarts?<\/h4>\n\n\n\n
text<\/code> fields for header\/footer placement blocks), and how you can reuse the same placeholders across multiple sections and layouts.<\/p>\n\n\n\nThe biggest update: sections and page ranges<\/h2>\n\n\n\n
sections<\/code> is a list of configuration blocks, and each block can apply to a specific page range (or all pages by default).<\/p>\n\n\n\nUsing range to target specific pages<\/h3>\n\n\n\n
\n
\"range\": \"1-10\"<\/code><\/li>\n<\/ul>\n\n\n\n\n
range<\/code> is optional<\/li>\n\n\n\nWhy this matters in practice<\/h4>\n\n\n\n
\n
Formatting controls: fonts, size, and style (with defaults)<\/h2>\n\n\n\n
format<\/code> object that can include font settings such as:<\/p>\n\n\n\n\n
name<\/code> (font name)<\/li>\n\n\n\nsize<\/code> (font size)<\/li>\n\n\n\nstyle<\/code> (font style)<\/li>\n<\/ul>\n\n\n\n\n
Supported values you can rely on<\/h3>\n\n\n\n
\n
What changed vs earlier quickstarts?<\/h4>\n\n\n\n
Numbering patterns: Arabic, letters, Roman numerals, and start value<\/h2>\n\n\n\n
numbering_config<\/code> object defines how numbering appears and where it begins. Two particularly useful properties are:<\/p>\n\n\n\n\n
type<\/code> controls the numbering pattern<\/li>\n\n\n\nstart<\/code> controls the starting number<\/li>\n<\/ul>\n\n\n\nSupported numbering types<\/h3>\n\n\n\n
\n
1<\/code> \u2192 1,2,3<\/li>\n\n\n\na<\/code> \u2192 a,b,c<\/li>\n\n\n\nA<\/code> \u2192 A,B,C<\/li>\n\n\n\ni<\/code> \u2192 i,ii,iii<\/li>\n\n\n\nI<\/code> \u2192 I,II,III<\/li>\n<\/ul>\n\n\n\nWhat changed vs earlier quickstarts?<\/h4>\n\n\n\n
Date insertion: optional, but now clearly defined<\/h2>\n\n\n\n
date_config<\/code>, which allows inserting dates alongside pagination using a controlled format.<\/p>\n\n\n\n\n
date_config<\/code>, locale and timezone become mandatory<\/strong><\/li>\n<\/ul>\n\n\n\nWhy date configuration matters<\/h3>\n\n\n\n
\n
What changed vs earlier quickstarts?<\/h4>\n\n\n\n
Header and footer placement: left, center, right\u2014at least one is required<\/h2>\n\n\n\n
\n
text<\/code> is mandatory inside each placement block, and can include placeholders like <<page_number>><\/code> and <<total_pages>><\/code><\/li>\n<\/ul>\n\n\n\nOffsets: pixel-based positioning for precision<\/h3>\n\n\n\n
offsets<\/code>, which let you set positioning adjustments in pixels using:<\/p>\n\n\n\n\n
top<\/code>, bottom<\/code>, left<\/code>, right<\/code><\/li>\n<\/ul>\n\n\n\n\n
What changed vs earlier quickstarts?<\/h4>\n\n\n\n
A modern \u201ctoday\u201d configuration example (conceptual)<\/h2>\n\n\n\n
\n
range<\/code>)<\/li>\n\n\n\nformat<\/code>)<\/li>\n\n\n\nnumbering_config<\/code>)<\/li>\n\n\n\nResponse handling: asynchronous job flow (and what\u2019s clarified today)<\/h2>\n\n\n\n
status_url vs status_check_url<\/h3>\n\n\n\n
What changed vs earlier quickstarts?<\/h4>\n\n\n\n
Practical upgrade guide: how your implementation changes from earlier to today<\/h2>\n\n\n\n
Step 1: Keep your existing placeholders and async handling<\/h3>\n\n\n\n
\n
file<\/code>, input_options<\/code>, and output_settings<\/code> via multipart form data.<\/li>\n\n\n\n<<page_number>><\/code> and <<total_pages>><\/code> in a text<\/code> field.<\/li>\n\n\n\nStep 2: Use defaults deliberately to reduce configuration noise<\/h3>\n\n\n\n
\n
Step 3: Introduce sections for professional layouts<\/h3>\n\n\n\n
sections<\/code> (and optionally range<\/code>), you can solve the most common pagination pain points:<\/p>\n\n\n\n\n
Step 4: Use offsets when you need pixel-perfect alignment<\/h3>\n\n\n\n
Step 5: Add date insertion only where it adds value<\/h3>\n\n\n\n
date_config<\/code> supports it\u2014just remember that locale and timezone become required when you turn it on.<\/p>\n\n\n\nBest practices for production use<\/h2>\n\n\n\n
Validate file limits before uploading<\/h3>\n\n\n\n
Standardize a \u201chouse footer\u201d and reuse it everywhere<\/h3>\n\n\n\n
\n
Page <<page_number>> of <<total_pages>><\/code><\/li>\n\n\n\nMake polling resilient<\/h3>\n\n\n\n
\n
Avoid over-formatting unless needed<\/h3>\n\n\n\n
Closing thoughts: the \u201ctoday\u201d API is about consistency, not just numbering<\/h2>\n\n\n\n