A print vendor's spec sheet does not say "add page numbers." It says something like: bottom center, format "# of {1}", 12pt, skip the cover page, 10mm margin from the bottom edge. Miss any one of those and the file bounces back with a rejection note, not a phone call explaining what to fix.
That is the part page numbering tutorials skip. Adding a number to a PDF is not the hard part. Matching an exact, often oddly specific format that someone else defined, without touching the rest of the document's layout, is the actual job. Legal briefs want "- # -". Academic submissions want "Page # of {1}" top right. Some enterprise templates skip the first page entirely because it is a cover sheet. A page numbering tool that only prints "1, 2, 3" in the corner does not solve any of these, because none of them define what "properly numbered" means the same way.
What the API actually controls
PDF4me's Add Page Number to PDF endpoint is a single POST /api/v2/AddPageNumber call. You send Base64-encoded PDF content and get Base64-encoded PDF content back, with the numbering already stamped in. Everything a print spec would ask for maps to a real parameter, not a workaround.
The format itself is controlled by two placeholders inside a pageNumberFormat string: # for the current page number and {1} for the total page count. That is enough to reproduce most of what shows up on a real spec sheet:
-
"# of {1}"renders as 1 of 10, 2 of 10, 3 of 10 -
"Page #"renders as Page 1, Page 2, Page 3 -
"# / {1}"renders as 1 / 10, 2 / 10, 3 / 10 -
"- # -"renders as - 1 -, - 2 -, - 3 - -
"[#/{1}]"renders as [1/10], [2/10], [3/10] -
"(#)"renders as (1), (2), (3)
Positioning is two required fields, alignX (left, center, right) and alignY (top, middle, bottom), so "bottom center" or "top right" is a direct instruction, not a guess involving pixel coordinates. If the spec gets more specific than that, marginXinMM and marginYinMM set the exact offset from the edge in millimeters, each accepting a 0-100 range.
Styling covers the three things a vendor spec usually cares about: fontSize (8-72), isBold, and isItalic. There is no font-family parameter, so if a spec calls for a specific typeface on the page numbers themselves, that is outside what this endpoint controls. Size, weight, and italics are what's available, and for the overwhelming majority of numbering requirements that is the whole ask anyway.
The one option that solves a genuinely common annoyance on its own: skipFirstPage. Set it to true and page 1 (the cover, the title page) gets no number stamped on it at all, while the rest of the document numbers normally. No manual splitting the document into "cover" and "body" first.
What a vendor spec turns into, in practice
Take a real example: a legal brief spec asking for "- # -" centered at the bottom of every page, 12pt, 10mm from the bottom edge, numbering starting on the first page (no cover to skip). That translates directly into the required and optional fields, nothing left to interpret:
{
"docName": "brief.pdf",
"docContent": "<base64 PDF>",
"pageNumberFormat": "- # -",
"alignX": "center",
"alignY": "bottom",
"marginYinMM": 10,
"fontSize": 12,
"skipFirstPage": false
}
Swap pageNumberFormat to "Page # of {1}", alignX to "right", and skipFirstPage to true, and the same call now matches an academic submission spec with a title page instead. Nothing about the request structure changes between the two, only the values, which is what makes this the kind of thing worth automating once rather than handling by hand every time a new document type shows up. Full runnable code samples, starting with C#, are maintained in the pdf4me-api-samples repository alongside the endpoint's own documentation.
Async for volume
Everything above runs synchronously by default and returns a 200 with the numbered PDF immediately. For high-volume runs, set async to true and the API returns a 202 with a Location header instead. Poll that URL until it returns 200; the response body is the same shape either way: docName and a Base64 docContent. For a workflow numbering hundreds of report exports overnight rather than one document a user is waiting on, that distinction matters more than it looks like on paper.
Where this sits next to header/footer stamping
PDF4me also has a dedicated Add HTML Header/Footer to PDF endpoint that supports page number variables inside a broader HTML-formatted header or footer, alongside logos, dates, or other repeating content. If page numbers are the only thing being added, the dedicated Add Page Number endpoint above is the more direct route: fewer parameters, no HTML to construct. If the number needs to live inside a designed header or footer block with other elements around it, that's the header/footer endpoint's job instead. Worth knowing both exist before building a header/footer template just to get a number in the corner.
Testing a format before it hits a pipeline
Before wiring any of this into an automated workflow, it is worth confirming the exact format string against a sample PDF first. The API Tester runs the Add Page Number endpoint directly in the browser: upload a file, set the parameters, see the numbered result, without writing a line of integration code yet. That is the fastest way to confirm "# of {1}" bottom center at 10mm margin is actually what a spec sheet means before that logic gets buried inside a Flow, a Zap, or a scenario.
Same endpoint, four ways into a workflow
The REST endpoint is the mechanism; most teams reach it through whichever automation platform they already run everything else on.
Power Automate exposes this as a connector action inside a Flow, so page numbering becomes one more step after a document generation or approval action, with no separate script to maintain. See Add Page Numbers to PDF in Power Automate.
Zapier wires the same parameters into a Zap step, useful for numbering documents the moment they land from a form submission, a CRM export, or another connected app. See Add Page Numbers to PDF in Zapier.
Make does it as a module inside a scenario, which is where this tends to sit well downstream of a merge or convert step, numbering the final assembled document rather than each source file separately. See Add Page Numbers to PDF in Make.
n8n treats it as a node, which fits a self-hosted or code-adjacent pipeline where page numbering is one node between a document-generation step and wherever the finished file gets delivered. See Add Page Number to PDF in n8n.
Across all four, the underlying contract is identical to the REST call: the same pageNumberFormat, alignX/alignY, margins, and skipFirstPage options, just exposed as connector fields instead of JSON keys. A format string validated once in the API Tester carries over exactly as-is into whichever platform actually runs the workflow.
What this does not do
It stamps a number in a fixed format, position, and style, consistently across a document. It does not do mixed numbering schemes within a single file (roman numerals for a front-matter section, then 1, 2, 3 for the body, as some formal print specs require), and there is no font-family control beyond size, bold, and italic. There is also no way to restart the count partway through a document or offset the starting number away from 1, based on the documented parameter table; if a spec calls for either of those, that request sits outside this endpoint's scope.
None of that makes it a smaller tool than it looks like at first. It makes it a more honest one. A single-purpose endpoint that takes six or seven parameters and reliably produces one specific, well-defined output is easier to build a pipeline around than a page-layout engine trying to do everything a design tool does. For the common case, a document that just needs consistent, correctly formatted page numbers wherever a spec says they should sit, that's exactly the scope of the job, and worth building for that scope rather than something heavier.
The next time a print vendor's spec sheet lists an exact page number format, position, and margin, that is a parameter list, not a design problem.
Website: pdf4me.com
Documentation: docs.pdf4me.com
Developer portal: dev.pdf4me.com
Top comments (0)