Insert Page Numbers into PDF

Purpose

This API enables you to insert page numbers into a PDF file, including options to customize font, style, numbering pattern, and placement in headers or footers.

Quick Reference

PropertyValue
MethodPOST
Request URLhttps://{zohoapis_domain}/pdfeditor/api/v1/pdf/insertpagenumber

Body Parameters

ParameterValueMandatory/OptionalDescription
fileFile or StringMandatoryUpload the PDF file from your local drive or desktop. If the PDF is available via a publicly accessible web URL, you can provide the URL using the same parameter.
input_options{
  "page_number_settings": {
    "sections": [
      {
        "range": "1-10",
        "format": {
          "font": {
            "name": "Helvetica",
            "size": 10,
            "style": "Bold"
          }
        },
        "numbering_config": {
          "type": "1",
          "start": 1
        },
        "date_config": {
          "format": "DD-MM-YYYY",
          "locale": "en-US",
          "timezone": "UTC"
        },
        "header": {
          "left": {
            "text": "Page <<page_number>> of <<total_pages>>",
            "offsets": { "top": 20, "left": 40 }
          }
        },
        "footer": {
          "center": {
            "text": "Page <<page_number>> of <<total_pages>>",
            "offsets": { "bottom": 20 }
          }
        }
      }
    ]
  }
}		Mandatorypage_number_settings – Contains the page number configuration as a JSON Object.
sections – List of configuration blocks, each defining how page numbers should be inserted for a specific page range.
range(optional) – Specify the page range for page number insertion. Defaults to all pages if not provided.
format(optional) – Defines the formatting for the page numbers. Defaults to Roboto, size 12 if not provided.
font(optional) – Contains font styling details.
numbering_config(optional) – Defines the numbering style and starting number. Defaults to 1, 2, 3 if not provided.
type(optional) – Numbering type. Examples: 1 (1,2,3), a (a,b,c), A (A,B,C), i (i,ii,iii), I (I,II,III).
start(optional) – Starting number for page numbering.
date_config(optional) – Configuration for inserting the date. Defaults to dd-MM-yyyy if not provided.
locale – Specify the locale value. Defaults to en-US. Mandatory if date_config is used.
timezone – Timezone for rendering the date. Defaults to UTC. Mandatory if date_config is used.
header / footer – At least one is mandatory. Contains layout sections where page numbers or text can be added.
left / center / right – At least one is mandatory in either header or footer.
text(mandatory) – Specify the text content to be displayed. Placeholders: <<page_number>>, <<total_pages>>.
offsets(optional) – Positioning offsets (top, bottom, left, right) in pixels. Defaults to header/footer position if not provided.
output_settings{
  "name": "<document_name>"
}		MandatorySpecify the name for the output PDF document.

input_options Parameters

ParameterData TypePossible ValuesDefault Value
nameStringWeb-safe fontsRoboto
sizeIntegerMaximum up to 10812
styleStringNormal, Bold, Italic, Bold ItalicNormal
typeString1 / a / A / i / I1

Notes and Limits

  • The maximum file size allowed for the input PDF is 50 MB. It cannot be more than 150 pages.
  • To use this API, an OAuth token should be generated with the following scopes: ZohoWriter.pdfEditor.ALL

Possible Errors

Refer to the following pages for the list of possible errors for this API:

Sample Request

Copiedcurl --location --request POST "https://www.zohoapis.com/pdfeditor/api/v1/pdf/insertpagenumber" \
  --header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
  --form 'file=@"/Users/username/Documents/Sample.pdf"' \
  --form 'input_options="{\"page_number_settings\":{\"sections\":{\"header\":{\"left\":{\"text\":\"Page <<page_number>> of <<total_pages>>\"}}}}}"'  \
  --form 'output_settings=“{\”name\”:\”ModifiedFile.pdf\"}"'

Once the process begins, you will initially receive the 'status_url'. By invoking the 'status_url', you will be able to monitor the status of the scheduled job.

Sample Response

Copied{
    "status_check_url": "https://pdf.zoho.com/pdfeditor/api/v1/pdf/insertpagenumber/job/f931a01183b33",
    "status": "inprogress"
}

Success Response

Copied{
	"download_url" :"https://pdf.zoho.com/pdfeditor/api/v1/pdf/insertpagenumber/download/f931a01183b33",
	"status": "success"
}