Add Page Number to PDF - Pagination API

PDF4me Add Page Number to PDF enables you to add customizable page numbers to PDF documents with control over position, format, and styling. This API service processes PDF files and adds page numbers using format placeholders where # represents the current page number and {1} represents the total number of pages. The API receives PDF content through REST API calls, utilizing Base64 encoding for secure transmission. This solution is ideal for document organization, legal documentation, academic papers, and enterprise PDF workflows.

Authenticating Your API Request

To access the PDF4me REST API, every request must include proper authentication credentials. Authentication ensures secure communication and validates your identity as an authorized user of the REST API.

Get your api Key

Key Features

• Flexible Formatting: Choose from multiple page number formats using # for current page and {1} for total pages (e.g., "# of 1", "Page #")
• Precise Positioning: Control horizontal and vertical alignment with pixel-perfect accuracy
• Custom Styling: Adjust font size, bold, italic, and other text formatting options
• Margin Control: Set precise margins in millimeters for optimal placement
• Skip First Page: Option to exclude page numbers from the first page
• Professional Results: Create consistent, professional page numbering across documents

REST API Endpoint

The PDF4me REST API uses standard HTTP methods to interact with resources. All page number addition operations are performed through a single endpoint:

• Method: POST
• Endpoint: /api/v2/AddPageNumber

REST API Parameters

Complete list of parameters for the Add Page Number to PDF REST API. Parameters are organized by category for better understanding and implementation.

Important: Parameters marked with an asterisk (*) are required and must be provided for the API to function correctly.

Required Parameters

Parameter	Type	Description	Example
docName*	String	Output PDF file name with .pdf extension	output.pdf
docContent*	Base64	PDF file content encoded in Base64	JVBERi...
pageNumberFormat*	String	Page number format. Use # for current page number, {1} for total pages. Examples: "# of 1", "Page #", "# / 1"	# of {1}
alignX*	String	Horizontal alignment: left, center, or right	right
alignY*	String	Vertical alignment: top, middle, or bottom	bottom

Optional Parameters

Parameter	Type	Description	Example
marginXinMM	Integer	Horizontal margin from edge in millimeters (0-100)	2
marginYinMM	Integer	Vertical margin from edge in millimeters (0-100)	2
fontSize	Integer	Font size for page numbers (8-72)	12
isBold	Boolean	Make page numbers bold (true) or regular (false)	true
isItalic	Boolean	Make page numbers italic (true) or normal (false)	false
skipFirstPage	Boolean	Skip numbering on first page (true) or include it (false)	false
async	Boolean	Enable asynchronous processing. When true, the API returns a 202 status and provides a polling URL in the Location header	true

Page Number Format Placeholders

The pageNumberFormat parameter uses the following placeholders:

• # - Replaced with the current page number (1, 2, 3, etc.)
• {1} - Replaced with the total number of pages

Format Examples:

• "# of {1}" → Displays "1 of 10", "2 of 10", "3 of 10", etc.
• "Page #" → Displays "Page 1", "Page 2", "Page 3", etc.
• "# / {1}" → Displays "1 / 10", "2 / 10", "3 / 10", etc.
• "- # -" → Displays "- 1 -", "- 2 -", "- 3 -", etc.
• "[#/{1}]" → Displays "[1/10]", "[2/10]", "[3/10]", etc.
• "(#)" → Displays "(1)", "(2)", "(3)", etc.
• "#" → Displays just the page number: "1", "2", "3", etc.

Output

The PDF4me Add Page Number to PDF REST API returns different responses based on the processing mode. The API returns the PDF as a Base64-encoded string in JSON format, not as binary data.

Success Response

Synchronous Processing (Default)

When async is not set or set to false, the API processes the request immediately:

Status Code: 200 OK

Content-Type: application/json

Response Body:

{
  "docName": "output.pdf",
  "docContent": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPD4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovTWVkaWFCb3ggWzAgMCA2MTIgNzkyXQovUmVzb3VyY2VzIDw8Ci9Gb250IDw8Ci9GMSA0IDAgUgo+Pgo+PgovQ29udGVudHMgNSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUxCi9CYXNlRm9udCAvSGVsdmV0aWNhCj4+CmVuZG9iago1IDAgb2JqCjw8Ci9MZW5ndGggNDQKPj4Kc3RyZWFtCkJUCi9GMSAxMiBUZgoxMDAgNzAwIFRkCihIZWxsbyBXb3JsZCkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iagp4cmVmCjAgNgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1NCAwMDAwMCBuIAowMDAwMDAwMTAxIDAwMDAwIG4gCjAwMDAwMDAxNzAgMDAwMDAgbiAKMDAwMDAwMDI0NCAwMDAwMCBuIAp0cmFpbGVyCjw8Ci9TaXplIDYKL1Jvb3QgMSAwIFIKPj4Kc3RhcnR4cmVmCjM0MQolJUVPRg=="
}

Response Fields:

• docName (string): The output PDF file name
• docContent (string): The PDF file with page numbers added, encoded as Base64 string

How to Use:

1. Extract the docContent field from the JSON response
2. Decode the Base64 string to get the binary PDF data
3. Save or process the PDF file as needed

Example (JavaScript):

const response = await fetch(url, options);
const data = await response.json();
const pdfBytes = atob(data.docContent); // Decode Base64
// Save or process pdfBytes

Asynchronous Processing

Asynchronous Processing

When async: true is set, the API processes the request asynchronously:

Status Code: 202 Accepted

Response Headers:

Location: https://api.pdf4me.com/api/v2/AddPageNumber/poll/12345-abcde-67890

Polling Process:

1. Extract the Location header from the 202 response
2. Poll the URL using GET requests
3. Continue polling until you receive a 200 OK status
4. The final response contains the same JSON format with docName and docContent (Base64)

Polling Example:

// Initial request returns 202 with Location header
const response = await fetch(url, options);
const location = response.headers.get('Location');

// Poll until complete
while (true) {
  const pollResponse = await fetch(location, { headers: { 'Authorization': 'Basic ' + apiKey } });
  if (pollResponse.status === 200) {
    const data = await pollResponse.json();
    // Process data.docContent (Base64 PDF)
    break;
  }
  await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2 seconds
}

Error Responses

Error Responses

The API returns standard HTTP error codes with error details:

400 Bad Request

• Invalid request parameters
• Missing required fields (docContent, docName, pageNumberFormat, alignX, alignY)
• Invalid Base64 encoding in docContent
• Invalid alignment values (must be "left", "center", "right" for alignX; "top", "middle", "bottom" for alignY)
• Invalid font size (must be between 8-72)
• Invalid margin values (must be integers between 0-100)

401 Unauthorized

• Invalid or missing API key
• API key not properly Base64 encoded in Authorization header
• Missing Authorization: Basic header

500 Internal Server Error

• Server-side processing error
• PDF processing failure
• Page number addition failure

Error Response Format:

{
  "error": "Error message describing what went wrong"
}

Response Format Details

Response Format Details

Important: The API always returns JSON, never binary PDF data directly.

Response Structure:

{
  "docName": "string",      // Output PDF filename
  "docContent": "string"    // Base64-encoded PDF content
}

Content-Type Header:

• Success: application/json
• The PDF is embedded as a Base64 string within the JSON response

Why Base64?

• JSON-safe encoding for binary data
• Easy to transmit over HTTP
• Compatible with all programming languages
• Can be directly embedded in JSON without escaping issues

Decoding Base64 to PDF:

JavaScript/Node.js:

const base64 = response.docContent;
const binary = atob(base64); // Browser
// OR
const binary = Buffer.from(base64, 'base64').toString('binary'); // Node.js

Python:

import base64
pdf_bytes = base64.b64decode(response['docContent'])
with open('output.pdf', 'wb') as f:
    f.write(pdf_bytes)

C#:

byte[] pdfBytes = Convert.FromBase64String(response.docContent);
File.WriteAllBytes("output.pdf", pdfBytes);

Request Example

Header

Content-Type: application/json
Authorization: Basic YOUR_BASE64_ENCODED_API_KEY

Note:

• Get your API key from the PDF4me Dashboard
• The API key must be Base64 encoded and prefixed with "Basic " in the Authorization header
• Example: If your API key is abc123, encode it to Base64 and use Authorization: Basic YWJjMTIz

Payload

Basic Example (Required Fields Only):

{
  "docName": "output.pdf",
  "docContent": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPD4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovTWVkaWFCb3ggWzAgMCA2MTIgNzkyXQovUmVzb3VyY2VzIDw8Ci9Gb250IDw8Ci9GMSA0IDAgUgo+Pgo+PgovQ29udGVudHMgNSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUxCi9CYXNlRm9udCAvSGVsdmV0aWNhCj4+CmVuZG9iago1IDAgb2JqCjw8Ci9MZW5ndGggNDQKPj4Kc3RyZWFtCkJUCi9GMSAxMiBUZgoxMDAgNzAwIFRkCihIZWxsbyBXb3JsZCkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iagp4cmVmCjAgNgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1NCAwMDAwMCBuIAowMDAwMDAwMTAxIDAwMDAwIG4gCjAwMDAwMDAxNzAgMDAwMDAgbiAKMDAwMDAwMDI0NCAwMDAwMCBuIAp0cmFpbGVyCjw8Ci9TaXplIDYKL1Jvb3QgMSAwIFIKPj4Kc3RhcnR4cmVmCjM0MQolJUVPRg==",
  "pageNumberFormat": "# of {1}",
  "alignX": "right",
  "alignY": "bottom"
}

Advanced Example (With All Optional Fields):

{
  "docName": "output.pdf",
  "docContent": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPD4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovTWVkaWFCb3ggWzAgMCA2MTIgNzkyXQovUmVzb3VyY2VzIDw8Ci9Gb250IDw8Ci9GMSA0IDAgUgo+Pgo+PgovQ29udGVudHMgNSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUxCi9CYXNlRm9udCAvSGVsdmV0aWNhCj4+CmVuZG9iago1IDAgb2JqCjw8Ci9MZW5ndGggNDQKPj4Kc3RyZWFtCkJUCi9GMSAxMiBUZgoxMDAgNzAwIFRkCihIZWxsbyBXb3JsZCkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iagp4cmVmCjAgNgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1NCAwMDAwMCBuIAowMDAwMDAwMTAxIDAwMDAwIG4gCjAwMDAwMDAxNzAgMDAwMDAgbiAKMDAwMDAwMDI0NCAwMDAwMCBuIAp0cmFpbGVyCjw8Ci9TaXplIDYKL1Jvb3QgMSAwIFIKPj4Kc3RhcnR4cmVmCjM0MQolJUVPRg==",
  "pageNumberFormat": "# of {1}",
  "alignX": "right",
  "alignY": "bottom",
  "marginXinMM": 2,
  "marginYinMM": 2,
  "fontSize": 12,
  "isBold": true,
  "isItalic": false,
  "skipFirstPage": false,
  "async": true
}

Code Samples

The PDF4me Add Page Number to PDF REST API provides code samples in multiple programming languages. Choose the language that best fits your development environment:

C#

C# (CSharp) Sample

Complete C# implementation for adding page numbers to PDF:

View C# Sample

Java

Java Sample

Java implementation with full error handling and response processing:

View Java Sample

JavaScript

JavaScript Sample

Node.js and browser-compatible JavaScript implementation:

View JavaScript Sample

Python

Python Sample

Python implementation with requests library and JSON handling:

View Python Sample

Salesforce

Salesforce Sample

Salesforce implementation with Apex and HTTP callouts:

View Salesforce Sample

n8n

n8n Sample

n8n workflow implementation with HTTP request nodes:

View n8n Sample

Google Script

Google Script Sample

Google Apps Script implementation with UrlFetchApp:

View Google Script Sample

AWS Lambda

AWS Lambda Sample

AWS Lambda implementation with Node.js and API Gateway:

View AWS Lambda Sample

Page Number Features

Formatting Options

• Multiple Formats: Support for various numbering styles and patterns
• Flexible Positioning: Precise control over page number placement
• Custom Styling: Full control over font appearance and formatting
• First Page Control: Option to exclude cover pages from numbering

Document Enhancement

• Professional Layout: Create consistent, professional page numbering across documents
• Print Optimization: Optimize page numbers for different printing requirements
• Digital Distribution: Maintain formatting across different viewing devices
• Brand Consistency: Apply uniform page numbering standards across organizations

Advanced Features

• Batch Processing: Process multiple documents with consistent page numbering
• Quality Assurance: Ensure page number integrity and proper PDF compatibility
• Layout Preservation: Maintain document structure while adding page numbers
• Custom Margins: Precise control over page number positioning

Industry Use Cases & Applications

Legal & Professional Services

Legal & Professional Services Use Cases

• Legal Documentation: Number pages in contracts, agreements, and legal briefs
• Court Documents: Add page numbers to court filings and legal documents
• Compliance Documentation: Number pages in compliance and regulatory documents
• Client Documentation: Organize client documents with page numbering

Education & Research

Education & Research Use Cases

• Academic Papers: Format research papers and theses with proper page numbering
• Research Documents: Add page numbers to research papers and publications
• Thesis Formatting: Number pages in theses and dissertations
• Educational Materials: Organize educational documents with page numbers

Business & Enterprise

Business & Enterprise Use Cases

• Business Reports: Create professional reports with consistent page numbering
• Document Organization: Add page numbers to reports, manuals, and technical documents
• Technical Manuals: Organize technical documentation with clear page references
• Corporate Documentation: Number pages in corporate documents and manuals

Government & Compliance

Government & Compliance Use Cases

• Archival Documents: Prepare documents for long-term storage with page numbers
• Government Reports: Add page numbers to government reports and documents
• Regulatory Documentation: Number pages in regulatory and compliance documents
• Public Records: Organize public records with page numbering

Get Help

Get Your API KeyAPI SamplesGetting Started