PDFinity Docs

Introduction

Welcome to the PDFinity API documentation. Our REST API provides a powerful suite of tools for programmatically manipulating PDF documents. You can integrate functionalities like converting, merging, splitting, and securing PDFs directly into your applications. All API endpoints are accessible via HTTPS and are located at the base URL:

https://api.pdfinity.com/v1/

Authentication

The PDFinity API uses API Keys to authenticate requests. You can get your API key from your developer dashboard. All API requests must include your key in an Authorization header as a Bearer token.

HTTP Header
Authorization: Bearer YOUR_API_KEY

Requests made without a valid API key will fail with a 401 Unauthorized error.

Rate Limiting

To ensure stability for all users, we enforce rate limits on API requests. The limits depend on your subscription plan:

  • Developer Plan: 1 request per second.
  • Business Plan: 10 requests per second.
  • Enterprise Plan: Custom limits with dedicated infrastructure.

If you exceed the rate limit, you will receive a 429 Too Many Requests error. We recommend implementing an exponential backoff strategy for retries.

SDKs

To make integration even easier, we provide official SDKs for popular programming languages. These libraries handle authentication, requests, and error handling for you.

Python

Install via PyPI: pip install pdfinity

Node.js

Install via npm: npm install @pdfinity/sdk

PHP

Install via Composer: composer require pdfinity/sdk

Java

Maven dependency available on Maven Central.

Convert PDF

Converts a supplied PDF file into various formats like Microsoft Word (.docx), Excel (.xlsx), or an image (.png, .jpg).

POST /convert/{output_format}

URL Parameters

  • output_format (required): The target format. Can be docx, xlsx, png, or jpg.

Request Body

The request must be sent as multipart/form-data.

  • file (required): The PDF file to be converted.

Example Request (Python)


import requests
# ... (rest of the code as before)
response = requests.post(
    'https://api.pdfinity.com/v1/convert/docx',
    # ...
)

Merge PDFs

Combines multiple PDF files into a single PDF document. The files are merged in the order they are provided.

POST /merge

Request Body

The request must be multipart/form-data.

  • files[] (required, min 2): The array of PDF files to merge.

Example Request (Python)


import requests
files_to_merge = [
  ('files[]', ('file1.pdf', open('path/to/file1.pdf', 'rb'), 'application/pdf')),
  ('files[]', ('file2.pdf', open('path/to/file2.pdf', 'rb'), 'application/pdf'))
]
response = requests.post(
    'https://api.pdfinity.com/v1/merge',
    headers={'Authorization': f'Bearer {api_key}'},
    files=files_to_merge
)

Secure a PDF

Adds password protection and encryption to a PDF file.

POST /secure

Request Body

The request must be multipart/form-data.

  • file (required): The PDF file to secure.
  • password (required): The password to set for the PDF.

Example Request (Python)


import requests
response = requests.post(
    'https://api.pdfinity.com/v1/secure',
    headers={'Authorization': f'Bearer {api_key}'},
    files={'file': open('path/to/document.pdf', 'rb')},
    data={'password': 'super-secret'}
)

Split a PDF

Splits a PDF into multiple documents based on a specified page range.

POST /split

Request Body

  • file (required): The PDF file to split.
  • range (required): A string specifying the page range (e.g., "1-3", "5", "8-10").

Add a Watermark

Applies a text or image watermark to a PDF document.

POST /watermark

Request Body Parameters

Provide either text or an image_file for the watermark content.

OCR Text Extraction

Extracts text content from a scanned PDF or image file using Optical Character Recognition (OCR).

POST /ocr

Get Document Properties

Retrieves metadata and properties from a PDF file, such as page count, author, subject, and creation date.

POST /properties

Error Codes

The PDFinity API uses conventional HTTP status codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate a client-side error, and codes in the 5xx range indicate a server-side error.

Status Code Meaning
400 Bad Request Your request is malformed (e.g., missing required parameters).
401 Unauthorized Your API key is missing or invalid.
404 Not Found The requested endpoint does not exist.
429 Too Many Requests You have exceeded your plan's rate limit.
500 Internal Server Error We had a problem with our server. Please try again later.