Insert Page Numbers into PDF
Adds page numbers, along with any header or footer text, to a PDF's pages in one or more configurable sections, and makes the modified PDF available for download.
Endpoint
OAuth Scope
curl --request POST \
--url https://www.zohoapis.com/pdfeditor/api/v1/pdf/insertpagenumber \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'content-type: multipart/form-data' \
-F 'file=@file_path' \
-F 'input_options={
"page_number_settings": {
"sections": [
{
"range": "1-10",
"numbering_config": {
"type": "1",
"start": 1
},
"format": {
"font": {
"name": "Helvetica",
"size": 10,
"color": "rgb(0,0,0)"
}
},
"date_config": {
"format": "dd-MM-yyyy",
"locale": "en-US",
"timezone": "UTC"
},
"header": {
"left": {
"text": "Quarterly Review"
},
"right": {
"text": "<<date>>",
"offsets": {
"top": "20px",
"right": "10px"
}
}
},
"footer": {
"center": {
"text": "Page <<page_number>> of <<total_pages>>"
}
}
}
]
}
}' \
-F 'output_settings={
"name": "quarterly-review-numbered.pdf"
}'Request Body
multipart/form-dataThe source PDF to add page numbers to, uploaded directly or imported from a publicly accessible URL. The file must be no larger than 50 MB, contain no more than 400 pages, and have no page larger than 2,400 square inches. Its filename must not exceed 255 characters. Supported formats: pdf.
Configures the page numbering, formatting, and header/footer placement.
{
"page_number_settings": {
"sections": [
{
"range": "1-10",
"numbering_config": {
"type": "1",
"start": 1
},
"format": {
"font": {
"name": "Helvetica",
"size": 10,
"color": "rgb(0,0,0)"
}
},
"date_config": {
"format": "dd-MM-yyyy",
"locale": "en-US",
"timezone": "UTC"
},
"header": {
"left": {
"text": "Quarterly Review"
},
"right": {
"text": "<<date>>",
"offsets": {
"top": "20px",
"right": "10px"
}
}
},
"footer": {
"center": {
"text": "Page <<page_number>> of <<total_pages>>"
}
}
}
]
}
}Show Sub-Attributes
Contains the page number configuration.
{
"sections": [
{
"range": "1-10",
"numbering_config": {
"type": "1",
"start": 1
},
"format": {
"font": {
"name": "Helvetica",
"size": 10,
"color": "rgb(0,0,0)"
}
},
"date_config": {
"format": "dd-MM-yyyy",
"locale": "en-US",
"timezone": "UTC"
},
"header": {
"left": {
"text": "Quarterly Review"
},
"right": {
"text": "<<date>>",
"offsets": {
"top": "20px",
"right": "10px"
}
}
},
"footer": {
"center": {
"text": "Page <<page_number>> of <<total_pages>>"
}
}
}
]
}Show Sub-Attributes
One configuration block per page range, each defining the numbering style, formatting, and header/footer placement for its pages.
[
{
"range": "1-10",
"numbering_config": {
"type": "1",
"start": 1
},
"format": {
"font": {
"name": "Helvetica",
"size": 10,
"color": "rgb(0,0,0)"
}
},
"date_config": {
"format": "dd-MM-yyyy",
"locale": "en-US",
"timezone": "UTC"
},
"header": {
"left": {
"text": "Quarterly Review"
},
"right": {
"text": "<<date>>",
"offsets": {
"top": "20px",
"right": "10px"
}
}
},
"footer": {
"center": {
"text": "Page <<page_number>> of <<total_pages>>"
}
}
}
]Show Sub-Attributes
The page range this section applies to, as a single starting page number and an optional hyphenated end page (e.g. 1-10, or 5 to number from page 5 through the end of the document). If omitted, the section applies to the whole document.
Controls the numbering style and starting value for the section.
{
"type": "1",
"start": 1
}Show Sub-Attributes
The numbering style used to render the page number: 1 for numeric, a/A for lowercase/uppercase letters, i/I for lowercase/uppercase Roman numerals.
The page number value to start counting from for this section.
Font formatting applied to the page number and header/footer text.
{
"font": {
"name": "Helvetica",
"size": 10,
"color": "rgb(0,0,0)"
}
}Show Sub-Attributes
The font used to render the text.
{
"name": "Helvetica",
"size": 10,
"color": "rgb(0,0,0)"
}Show Sub-Attributes
A web-safe font family name.
The font size, in points. Maximum 108.
The text color, as a hex value (#RGB or #RRGGBB), an rgb(r,g,b) value, or one of a fixed set of named colors.
Supported named colors: red, blue, green, black, white.
Formats the <<date>> placeholder used in this section's header and footer text.
{
"format": "dd-MM-yyyy",
"locale": "en-US",
"timezone": "UTC"
}Show Sub-Attributes
A date format pattern.
A BCP 47 language tag used to render the formatted date.
An IANA timezone ID used to compute the formatted date.
Header text placement for the section. Provide at least one of left, center, or right.
{
"left": {
"text": "Quarterly Review"
},
"right": {
"text": "<<date>>",
"offsets": {
"top": "20px",
"right": "10px"
}
}
}Show Sub-Attributes
Header content aligned to the left margin.
{
"text": "Quarterly Review",
"offsets": {
"left": "10px",
"top": "20px",
"right": "10px",
"bottom": "20px"
}
}Show Sub-Attributes
The text to render. Supports the placeholders <<page_number>>, <<total_pages>>, and <<date>>.
Pixel offsets controlling the placement of the text within the page margin.
{
"left": "10px",
"top": "20px",
"right": "10px",
"bottom": "20px"
}Show Sub-Attributes
The offset from the left of the page, as a pixel value ending in px (e.g. 10px).
The offset from the top of the page, as a pixel value ending in px (e.g. 20px).
The offset from the right of the page, as a pixel value ending in px (e.g. 10px).
The offset from the bottom of the page, as a pixel value ending in px (e.g. 20px).
Header content aligned to the center.
{
"text": "Page <<page_number>> of <<total_pages>>",
"offsets": {
"left": "10px",
"top": "20px",
"right": "10px",
"bottom": "20px"
}
}Show Sub-Attributes
The text to render. Supports the placeholders <<page_number>>, <<total_pages>>, and <<date>>.
Pixel offsets controlling the placement of the text within the page margin.
{
"left": "10px",
"top": "20px",
"right": "10px",
"bottom": "20px"
}Show Sub-Attributes
The offset from the left of the page, as a pixel value ending in px (e.g. 10px).
The offset from the top of the page, as a pixel value ending in px (e.g. 20px).
The offset from the right of the page, as a pixel value ending in px (e.g. 10px).
The offset from the bottom of the page, as a pixel value ending in px (e.g. 20px).
Header content aligned to the right margin.
{
"text": "<<date>>",
"offsets": {
"left": "10px",
"top": "20px",
"right": "10px",
"bottom": "20px"
}
}Show Sub-Attributes
The text to render. Supports the placeholders <<page_number>>, <<total_pages>>, and <<date>>.
Pixel offsets controlling the placement of the text within the page margin.
{
"left": "10px",
"top": "20px",
"right": "10px",
"bottom": "20px"
}Show Sub-Attributes
The offset from the left of the page, as a pixel value ending in px (e.g. 10px).
The offset from the top of the page, as a pixel value ending in px (e.g. 20px).
The offset from the right of the page, as a pixel value ending in px (e.g. 10px).
The offset from the bottom of the page, as a pixel value ending in px (e.g. 20px).
Configures the modified PDF's filename.
{
"name": "quarterly-review-numbered.pdf"
}Show Sub-Attributes
The filename for the modified PDF. A .pdf extension is appended when the name does not already end with one.
// Note: payload contains multiple type attributes
// type: file
file = quarterly-review.pdf
// type: object
input_options = {
"page_number_settings": {
"sections": [
{
"range": "1-10",
"numbering_config": {
"type": "1",
"start": 1
},
"format": {
"font": {
"name": "Helvetica",
"size": 10,
"color": "rgb(0,0,0)"
}
},
"date_config": {
"format": "dd-MM-yyyy",
"locale": "en-US",
"timezone": "UTC"
},
"header": {
"left": {
"text": "Quarterly Review"
},
"right": {
"text": "<<date>>",
"offsets": {
"top": "20px",
"right": "10px"
}
}
},
"footer": {
"center": {
"text": "Page <<page_number>> of <<total_pages>>"
}
}
}
]
}
}
// type: object
output_settings = {
"name": "quarterly-review-numbered.pdf"
} {
"status": "inprogress",
"status_check_url": "https://www.zohoapis.com/pdfeditor/api/v1/pdf/insertpagenumber/job/qE8Vn4M2kP7sR9xW"
}
Rate Limits
Duration - Time window for the threshold.
Threshold - Number of API calls allowed within the specified duration.
Lock Period - Wait time before consecutive API requests.
© 2026, Zoho Corporation Pvt. Ltd. All Rights Reserved.