PDF Page Numbers API

POST

Stamp page numbers on every page of a PDF.

PDF Page Numbers stamps a page number on every page of a PDF, uploaded or fetched from a URL, and returns a download link to the numbered file. Choose the corner or edge and the font size. Paid plans can also set a label format such as Page 3 of 12, the starting number, and skip a cover page.

Try it — live request, no key required

Request

POSTapi.apiverve.com/v1/pdfpagenumbers

pdf

Click or drag a file to upload.pdf · max 400KB for live testing

Verification

Format

No key required to try it. Get a key to use it in your app.

Example

{
  "status": "ok",
  "error": null,
  "data": {
    "pdfName": "5c9f95f9-9719-47c3-a923-be3bc1f1dc91.pdf",
    "pageCount": 2,
    "numberedPages": 2,
    "position": "bottom-center",
    "format": "Page {page} of {total}",
    "startAt": 1,
    "lastLabel": "Page 2 of 2",
    "size": 6218,
    "expires": 1792230037933,
    "downloadURL": "https://storage.googleapis.com/apiverve/APIData/pdfpagenumbers/5c9f95f9-9719-47c3-a923-be3bc1f1dc91.pdf?GoogleAccessId=635500398038-compute%40developer.gserviceaccount.com&Expires=1792230037&Signature=a2sCOtSuSIIEWobe8wq5iHcCdqlJMXhrHE9ewxXsf7qrNBK3NHtxrQYk%2Fn1Jpr08aQBVtJclbKX6CFqRigV2IL4suv%2F%2B8WF9LRX%2BhY%2Frhvkw9RfdydlsvALhpPxnxv547eShgBIsuwvEOPFry%2F1J%2FCvt3X%2BT8Iwpz9EtJJVKH8C3u8u26%2FlNjj7XcRCqx6hcVIWvkJEVuZfMQUjlcbtF4IOwvITwlIQW9ChPzMIlXdXu2amBIy9PinQoKsdVopBfTre4W%2BTH6%2BgynWlvnJAHmxM6mWdfLQxTjCyFzdT4ZmJuq%2BRM36d41N62KxiTGyP1cs0YJECt36nI3a7FTzUOrA%3D%3D"
  }
}

About the PDF Page Numbers API

Numbers are drawn in Helvetica as real PDF text, so the rest of the document is untouched. Rotated pages are handled, so the number sits in the chosen corner the right way up as the page is displayed. Each call accepts one PDF of up to 10 MB and 300 pages.

What people use it for

Generated Reports: Number the pages of reports and exports produced by other tools that leave them unnumbered.
Legal and Compliance: Add Page X of Y labels to contracts and filings before they are signed or submitted.
Merged Documents: Number a document after merging several PDFs so the combined file reads as one.
Print and Publishing: Paginate manuscripts, handouts and booklets, skipping the cover page.

Ways to call it

One endpoint, many ways in — REST with JSON, XML, YAML and CSV, plus GraphQL and an MCP interface for AI agents.

JSON: Default REST response
XML: Markup format
YAML: Human-readable
CSV: Tabular export
GraphQL: Query language
MCP: For AI agents

View all integrations →

Other ways to use PDF Page Numbers

Same data, same APIVerve account, same credit balance — one key works on all of them.

Give it to an AI agentConnect over MCP and your agent calls it as a native tool — Claude, Cursor, ChatGPT.on VerveKit

Questions.

Common questions about the PDF Page Numbers API.

Read the docs →

How many PDFs does the Starter plan cover?

Starter covers 20,000 PDFs each month. At 10 credits per request, that works out to $1.50 per 1,000 PDFs, or about $0.0015 per PDF, however many pages each one has. The Free plan includes 20 PDFs per month for testing.

What can I customise on the Free plan?

The Free plan numbers every page from 1 and lets you choose the position and the font size. Paid plans add format, a label template such as Page {page} of {total}, startAt to begin from another number, and skipFirst to leave a cover page unnumbered.

Where can the page number go?

bottom-center (the default), bottom-right, bottom-left, top-center, top-right or top-left, 28 points from the edge. On rotated pages the number is placed by the page as displayed, the right way up.

What are the limits per call?

One PDF of up to 10 MB and 300 pages. Uploads on the Free plan are limited to 400 KB. Encrypted PDFs are rejected; remove the password first.

How long is the numbered file kept?

The download link is a signed URL that expires after 2 days, given in the expires field as a Unix timestamp in milliseconds.

Request parameters — POST /v1/pdfpagenumbers

Sent as JSON in the request body. Premium parameters are accepted on every plan but only take effect on plans that include them. Anything not listed here is dropped rather than passed through.

Optional

Parameter	Type	Example	Description
`pdf`Optional	string		The PDF file to number (up to 10 MB and 300 pages), or a public PDF URL url
`position`Optional	string	`bottom-center`	Where to place the number `bottom-centerbottom-rightbottom-lefttop-centertop-righttop-left` default bottom-center
`fontSize`Optional	number	`10`	Font size in points, from 6 to 36 default 10 · range 6-36
`format`OptionalPremium	string	`Page {page} of {total}`	Label template containing {page}, and optionally {total}, such as Page {page} of {total}
`startAt`OptionalPremium	integer	`1`	Number for the first numbered page range 0-100000
`skipFirst`OptionalPremium	boolean	`false`	Leave the first page (a cover) unnumbered

Example request

curl -X POST "https://api.apiverve.com/v1/pdfpagenumbers" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"position":"bottom-center","fontSize":10,"format":"Page {page} of {total}","startAt":1,"skipFirst":false}'

Authentication

Send your key in the x-api-key header. That is the only auth step — no token exchange, and no per-endpoint scope to configure.

Header	When	Value
`x-api-key`Required	Every request	Your API key. Header names are case-insensitive, so `X-API-Key` is the same header.
`Authorization`Alternate	Instead of the above	`Bearer <key>` — for clients that only expose bearer auth. Resolves to the same account and the same billing.
`content-type`Required	POST body	`application/json`

401 is the only auth verdict

A 401 means the key is missing, invalid or expired. A 403 means the key is valid but not permitted here — blocked by a key restriction or an IP allow-list. Running out of credits is a 429.

Response — POST /v1/pdfpagenumbers

Every APIVerve endpoint returns the same three top-level keys, so one response handler covers your whole integration: status, error and data. Only data changes shape.

Sample response

{
  "status": "ok",
  "error": null,
  "data": {
    "pdfName": "5c9f95f9-9719-47c3-a923-be3bc1f1dc91.pdf",
    "pageCount": 2,
    "numberedPages": 2,
    "position": "bottom-center",
    "format": "Page {page} of {total}",
    "startAt": 1,
    "lastLabel": "Page 2 of 2",
    "size": 6218,
    "expires": 1792230037933,
    "downloadURL": "https://storage.googleapis.com/apiverve/APIData/pdfpagenumbers/5c9f95f9-9719-47c3-a923-be3bc1f1dc91.pdf?GoogleAccessId=635500398038-compute%40developer.gserviceaccount.com&Expires=1792230037&Signature=a2sCOtSuSIIEWobe8wq5iHcCdqlJMXhrHE9ewxXsf7qrNBK3NHtxrQYk%2Fn1Jpr08aQBVtJclbKX6CFqRigV2IL4suv%2F%2B8WF9LRX%2BhY%2Frhvkw9RfdydlsvALhpPxnxv547eShgBIsuwvEOPFry%2F1J%2FCvt3X%2BT8Iwpz9EtJJVKH8C3u8u26%2FlNjj7XcRCqx6hcVIWvkJEVuZfMQUjlcbtF4IOwvITwlIQW9ChPzMIlXdXu2amBIy9PinQoKsdVopBfTre4W%2BTH6%2BgynWlvnJAHmxM6mWdfLQxTjCyFzdT4ZmJuq%2BRM36d41N62KxiTGyP1cs0YJECt36nI3a7FTzUOrA%3D%3D"
  }
}

Response fields

Paths are relative to data. Premium fields are absent rather than zeroed on plans that do not include them, so check for presence instead of comparing to 0.

Field	Type	Example	Description
`pdfName`	string	`"5c9f95f9-9719-47c3-a923-be3bc1f1dc91.pdf"`	File name of the numbered PDF
`pageCount`	number	`2`	Pages in the PDF
`numberedPages`	number	`2`	Pages that received a number
`position`	string	`"bottom-center"`	Where the numbers were placed
`format`	string	`"Page {page} of {total}"`	The label template used
`startAt`	number	`1`	The number given to the first numbered page
`lastLabel`	string	`"Page 2 of 2"`	The label on the last page, such as Page 12 of 12
`size`	number	`6218`	Size of the numbered PDF in bytes
`expires`	number	`1792230037933`	When the download link expires (Unix time in milliseconds)
`downloadURL`	string	`"https://storage.googleapis.com/apiverve/APIData/pdfpagenumbers/5c9f95f9-9719-47c3-a923-be3bc1f1dc91.pdf?GoogleAccessId=635500398038-compute…`	Signed link to download the numbered PDF, valid for 2 days

Response headers

Every response carries your balance, so your own code always knows where it stands without polling anything. All four are exposed to browsers through CORS.

Header	What it carries
`x-api-remaining-credits`	Credits left in the current cycle
`x-api-credits-used`	Credits spent in the current cycle
`x-api-max-credits`	The allowance for the cycle
`x-api-version`	Version of the endpoint that answered

Errors

Read the HTTP status first, then error for the specific reason. The body names the parameter that has to change.

Status	Meaning	What to do
`400`	Input was rejected	Read `error`; it names the parameter that has to change.
`401`	Key missing or invalid	Check the header name and the key value.
`403`	Key valid, but not permitted here	A key restriction or an IP allow-list — never a bad key.
`429`	Rate limited, or out of credits	Read `error` to tell them apart, then back off or top up.

What a call costs — 10 credits per call

Credits are shared across every APIVerve API — one balance, one key, one bill. Failed requests never count against it, so a rejected input costs nothing.

Plan	Per month	Credits	PDF Page Numbers calls	Per 1,000 calls
Free	Free	200	20	Free
Starter	$29.99	200,000	20,000	$1.50
Pro	$99.99	1,000,000	100,000	$1.00
Mega	$299.99	4,000,000	400,000	$0.75

Calls are what the credits buy at this API's rate — spend them here, on any of the other APIs, or across both. Nothing is reserved per endpoint.

Compare all pricing tiers →

Call it from cURL — POST /v1/pdfpagenumbers

No SDK to install — this is a plain HTTPS call to /v1/pdfpagenumbers with your key in the x-api-key header. Swap in a real key and it runs as-is.

cURL

1
2

curl "https://api.apiverve.com/v1/pdfpagenumbers" \
  -H "x-api-key: YOUR_API_KEY"

Resources

ReferencePDF Page Numbers API docsEvery parameter, every response field, and the errors.ParametersWhat this call acceptsRequired and optional inputs, with example values.

Call it from Node.js — POST /v1/pdfpagenumbers

No SDK to install — this is a plain HTTPS call to /v1/pdfpagenumbers with your key in the x-api-key header. Swap in a real key and it runs as-is.

Node.js

const res = await fetch("https://api.apiverve.com/v1/pdfpagenumbers", {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const { data } = await res.json();
console.log(data);

Resources

ReferencePDF Page Numbers API docsEvery parameter, every response field, and the errors.ParametersWhat this call acceptsRequired and optional inputs, with example values.

Call it from Python — POST /v1/pdfpagenumbers

No SDK to install — this is a plain HTTPS call to /v1/pdfpagenumbers with your key in the x-api-key header. Swap in a real key and it runs as-is.

Python

import requests

res = requests.get(
    "https://api.apiverve.com/v1/pdfpagenumbers",
    headers={"x-api-key": "YOUR_API_KEY"},
)
print(res.json()["data"])

Resources

ReferencePDF Page Numbers API docsEvery parameter, every response field, and the errors.ParametersWhat this call acceptsRequired and optional inputs, with example values.

Call it from C# / .NET — POST /v1/pdfpagenumbers

No SDK to install — this is a plain HTTPS call to /v1/pdfpagenumbers with your key in the x-api-key header. Swap in a real key and it runs as-is.

C# / .NET

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var json = await client.GetStringAsync("https://api.apiverve.com/v1/pdfpagenumbers");
Console.WriteLine(json);

Resources

ReferencePDF Page Numbers API docsEvery parameter, every response field, and the errors.ParametersWhat this call acceptsRequired and optional inputs, with example values.

Call it from Go — POST /v1/pdfpagenumbers

No SDK to install — this is a plain HTTPS call to /v1/pdfpagenumbers with your key in the x-api-key header. Swap in a real key and it runs as-is.

req, _ := http.NewRequest("GET", "https://api.apiverve.com/v1/pdfpagenumbers", nil)
req.Header.Set("x-api-key", "YOUR_API_KEY")

res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))

Resources

ReferencePDF Page Numbers API docsEvery parameter, every response field, and the errors.ParametersWhat this call acceptsRequired and optional inputs, with example values.

Call it from PHP — POST /v1/pdfpagenumbers

No SDK to install — this is a plain HTTPS call to /v1/pdfpagenumbers with your key in the x-api-key header. Swap in a real key and it runs as-is.

PHP

$ch = curl_init("https://api.apiverve.com/v1/pdfpagenumbers");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY"]);

$response = curl_exec($ch);
echo $response;

Resources

ReferencePDF Page Numbers API docsEvery parameter, every response field, and the errors.ParametersWhat this call acceptsRequired and optional inputs, with example values.

Call it from Ruby — POST /v1/pdfpagenumbers

No SDK to install — this is a plain HTTPS call to /v1/pdfpagenumbers with your key in the x-api-key header. Swap in a real key and it runs as-is.

Ruby

require "net/http"

uri = URI("https://api.apiverve.com/v1/pdfpagenumbers")
req = Net::HTTP::Get.new(uri)
req["x-api-key"] = "YOUR_API_KEY"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Resources

ReferencePDF Page Numbers API docsEvery parameter, every response field, and the errors.ParametersWhat this call acceptsRequired and optional inputs, with example values.

PDF Page Numbers API

Try it — live request, no key required

About the PDF Page Numbers API

What people use it for

Ways to call it

Other ways to use PDF Page Numbers

Questions.

Request parameters — POST /v1/pdfpagenumbers

Optional

Authentication

Response — POST /v1/pdfpagenumbers

Response fields

Response headers

Errors

What a call costs — 10 credits per call

Call it from cURL — POST /v1/pdfpagenumbers

Resources

Call it from Node.js — POST /v1/pdfpagenumbers

Resources

Call it from Python — POST /v1/pdfpagenumbers

Resources

Call it from C# / .NET — POST /v1/pdfpagenumbers

Resources

Call it from Go — POST /v1/pdfpagenumbers

Resources

Call it from PHP — POST /v1/pdfpagenumbers

Resources

Call it from Ruby — POST /v1/pdfpagenumbers

Resources

Zero-code embed — one snippet, no backend

Changelog — PDF Page Numbers API

Documents

Ready to build with PDF Page Numbers? Start with 200 free credits — one key unlocks all 300+ APIs.

Explore the catalog