Insert Page Numbers into PDF

Open in ChatGPT Open in ChatGPT to ask questions about this page
Open in Claude Open in Claude to ask questions about this page
Copy as MarkdownCopy this page as markdown to use with AI assistants
View as Markdown Open this page as markdown in a new tab

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

ZohoWriter.pdfEditor.ALLCopied!

Request Example

cURL
cURL
Java
Python
Deluge
Copied!
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-data
filebinary(Required)

The 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.

Example
quarterly-review.pdf
input_optionsJSON Object(Required)

Configures the page numbering, formatting, and header/footer placement.

Example
{
  "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
page_number_settingsJSON Object(Required)

Contains the page number configuration.

Example
{
  "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
sectionsJSON Array[object](Required)

One configuration block per page range, each defining the numbering style, formatting, and header/footer placement for its pages.

Example
[
  {
    "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
rangestring(Optional)

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.

Example
1-10
Maximum Length :500500Copied!
numbering_configJSON Object(Optional)

Controls the numbering style and starting value for the section.

Example
{
  "type": "1",
  "start": 1
}
Show Sub-Attributes
typestring(Optional)

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.

Example
1
Allowed Values :
Show Values ▾
1Copied!
aCopied!
ACopied!
iCopied!
ICopied!
Copied!Copy all as JSON Array
Default Value :11Copied!
startinteger(Optional)

The page number value to start counting from for this section.

Example
1
Default Value :11Copied!
formatJSON Object(Optional)

Font formatting applied to the page number and header/footer text.

Example
{
  "font": {
    "name": "Helvetica",
    "size": 10,
    "color": "rgb(0,0,0)"
  }
}
Show Sub-Attributes
fontJSON Object(Optional)

The font used to render the text.

Example
{
  "name": "Helvetica",
  "size": 10,
  "color": "rgb(0,0,0)"
}
Show Sub-Attributes
namestring(Optional)

A web-safe font family name.

Example
Helvetica
Default Value :HelveticaHelveticaCopied!
Maximum Length :100100Copied!
sizeinteger(Optional)

The font size, in points. Maximum 108.

Example
10
Default Value :1212Copied!
colorstring(Optional)

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.

Example
rgb(0,0,0)
Default Value :#000000#000000Copied!
Maximum Length :5050Copied!
date_configJSON Object(Optional)

Formats the <<date>> placeholder used in this section's header and footer text.

Example
{
  "format": "dd-MM-yyyy",
  "locale": "en-US",
  "timezone": "UTC"
}
Show Sub-Attributes
formatstring(Optional)

A date format pattern.

Example
dd-MM-yyyy
Default Value :dd-MM-yyyydd-MM-yyyyCopied!
localestring(Optional)

A BCP 47 language tag used to render the formatted date.

Example
en-US
Default Value :en-USen-USCopied!
timezonestring(Optional)

An IANA timezone ID used to compute the formatted date.

Example
UTC
Default Value :UTCUTCCopied!
headerJSON Object(Optional)

Header text placement for the section. Provide at least one of left, center, or right.

Example
{
  "left": {
    "text": "Quarterly Review"
  },
  "right": {
    "text": "<<date>>",
    "offsets": {
      "top": "20px",
      "right": "10px"
    }
  }
}
Show Sub-Attributes
leftJSON Object(Optional)

Header content aligned to the left margin.

Example
{
  "text": "Quarterly Review",
  "offsets": {
    "left": "10px",
    "top": "20px",
    "right": "10px",
    "bottom": "20px"
  }
}
Show Sub-Attributes
textstring(Optional)

The text to render. Supports the placeholders <<page_number>>, <<total_pages>>, and <<date>>.

Example
Quarterly Review
Maximum Length :255255Copied!
offsetsJSON Object(Optional)

Pixel offsets controlling the placement of the text within the page margin.

Example
{
  "left": "10px",
  "top": "20px",
  "right": "10px",
  "bottom": "20px"
}
Show Sub-Attributes
leftstring(Optional)

The offset from the left of the page, as a pixel value ending in px (e.g. 10px).

Example
10px
Default Value :0px0pxCopied!
topstring(Optional)

The offset from the top of the page, as a pixel value ending in px (e.g. 20px).

Example
20px
Default Value :0px0pxCopied!
rightstring(Optional)

The offset from the right of the page, as a pixel value ending in px (e.g. 10px).

Example
10px
Default Value :0px0pxCopied!
bottomstring(Optional)

The offset from the bottom of the page, as a pixel value ending in px (e.g. 20px).

Example
20px
Default Value :0px0pxCopied!
centerJSON Object(Optional)

Header content aligned to the center.

Example
{
  "text": "Page <<page_number>> of <<total_pages>>",
  "offsets": {
    "left": "10px",
    "top": "20px",
    "right": "10px",
    "bottom": "20px"
  }
}
Show Sub-Attributes
textstring(Optional)

The text to render. Supports the placeholders <<page_number>>, <<total_pages>>, and <<date>>.

Example
Page <<page_number>> of <<total_pages>>
Maximum Length :255255Copied!
offsetsJSON Object(Optional)

Pixel offsets controlling the placement of the text within the page margin.

Example
{
  "left": "10px",
  "top": "20px",
  "right": "10px",
  "bottom": "20px"
}
Show Sub-Attributes
leftstring(Optional)

The offset from the left of the page, as a pixel value ending in px (e.g. 10px).

Example
10px
Default Value :0px0pxCopied!
topstring(Optional)

The offset from the top of the page, as a pixel value ending in px (e.g. 20px).

Example
20px
Default Value :0px0pxCopied!
rightstring(Optional)

The offset from the right of the page, as a pixel value ending in px (e.g. 10px).

Example
10px
Default Value :0px0pxCopied!
bottomstring(Optional)

The offset from the bottom of the page, as a pixel value ending in px (e.g. 20px).

Example
20px
Default Value :0px0pxCopied!
rightJSON Object(Optional)

Header content aligned to the right margin.

Example
{
  "text": "<<date>>",
  "offsets": {
    "left": "10px",
    "top": "20px",
    "right": "10px",
    "bottom": "20px"
  }
}
Show Sub-Attributes
textstring(Optional)

The text to render. Supports the placeholders <<page_number>>, <<total_pages>>, and <<date>>.

Example
<<date>>
Maximum Length :255255Copied!
offsetsJSON Object(Optional)

Pixel offsets controlling the placement of the text within the page margin.

Example
{
  "left": "10px",
  "top": "20px",
  "right": "10px",
  "bottom": "20px"
}
Show Sub-Attributes
leftstring(Optional)

The offset from the left of the page, as a pixel value ending in px (e.g. 10px).

Example
10px
Default Value :0px0pxCopied!
topstring(Optional)

The offset from the top of the page, as a pixel value ending in px (e.g. 20px).

Example
20px
Default Value :0px0pxCopied!
rightstring(Optional)

The offset from the right of the page, as a pixel value ending in px (e.g. 10px).

Example
10px
Default Value :0px0pxCopied!
bottomstring(Optional)

The offset from the bottom of the page, as a pixel value ending in px (e.g. 20px).

Example
20px
Default Value :0px0pxCopied!
output_settingsJSON Object(Required)

Configures the modified PDF's filename.

Example
{
  "name": "quarterly-review-numbered.pdf"
}
Show Sub-Attributes
namestring(Required)

The filename for the modified PDF. A .pdf extension is appended when the name does not already end with one.

Example
quarterly-review-numbered.pdf
Maximum Length :255255Copied!

Body Parameters

Copied!
// 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"
}
▼ Show full

Response Example

200
Copied!
  {
    "status": "inprogress",
    "status_check_url": "https://www.zohoapis.com/pdfeditor/api/v1/pdf/insertpagenumber/job/qE8Vn4M2kP7sR9xW"
  }
                
▼ Show full

Rate Limits

Duration1 minute
Threshold50
Lock Period5 minutes 30 seconds
Duration1 hour
Threshold200
Lock Period15 minutes
Duration1 day
Threshold2000
Lock Period2 hours

Duration - Time window for the threshold.
Threshold - Number of API calls allowed within the specified duration.
Lock Period - Wait time before consecutive API requests.