API Documentation

Getting Started

The PDFDrill API allows you to convert PDFs programmatically. API access is available on Business and manually enabled Enterprise accounts. All requests require authentication via API key.

Python

import os
import requests

API_KEY = os.environ["PDFDRILL_API_KEY"]
BASE_URL = "https://pdfdrill.com/api/api"

# Upload PDF
with open("document.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/upload",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f}
    )
    response.raise_for_status()
    job_id = response.json()["id"]

# Check status (poll until done or error before downloading)
status = requests.get(
    f"{BASE_URL}/jobs/{job_id}",
    headers={"Authorization": f"Bearer {API_KEY}"}
).json()

# Download results
if status["status"] == "done":
    response = requests.get(
        f"{BASE_URL}/jobs/{job_id}/download",
        params={"output_type": "excel"},
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    response.raise_for_status()
    with open("output.xlsx", "wb") as f:
        f.write(response.content)

JavaScript (server-side Node.js)

import { readFile, writeFile } from "node:fs/promises";

const API_KEY = process.env.PDFDRILL_API_KEY;
if (!API_KEY) throw new Error("Set PDFDRILL_API_KEY on your server");
const BASE_URL = "https://pdfdrill.com/api/api";

// Upload PDF
const formData = new FormData();
formData.append("file", new Blob([await readFile("document.pdf")], {
  type: "application/pdf"
}), "document.pdf");

const uploadResponse = await fetch(`${BASE_URL}/upload`, {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}` },
  body: formData
});
if (!uploadResponse.ok) throw new Error("Upload failed");
const { id: job_id } = await uploadResponse.json();

// Check status (poll until done or error before downloading)
const statusResponse = await fetch(`${BASE_URL}/jobs/${job_id}`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});
const status = await statusResponse.json();

// Download results
if (status.status === "done") {
  const result = await fetch(
    `${BASE_URL}/jobs/${job_id}/download?output_type=excel`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
  if (!result.ok) throw new Error("Download failed");
  await writeFile("output.xlsx", Buffer.from(await result.arrayBuffer()));
}

Business and manually API-enabled Enterprise accounts can optionally add webhook_url to the multipart fields sent to POST /api/api/upload. PDFDrill sends a signed JSON callback when the job finishes. The URL must be HTTPS on port 443 and resolve only to public IP addresses; redirects are not followed. Callback delivery has a bounded timeout and up to three retries. Callback delivery problems do not change job status or page quota.

curl -X POST https://pdfdrill.com/api/api/upload \
  -H "Authorization: Bearer your_api_key_here" \
  -F "file=@document.pdf" \
  -F "webhook_url=https://example.com/pdfdrill-callback" \
  -F "webhook_secret=your-private-secret-of-at-least-32-characters"

webhook_secret is optional. If supplied, it must be at least 32 characters; treat it as a secret and do not put it in source control or logs. If omitted, PDFDrill derives a signing key from the API key used for this upload. The callback body contains only event (job.done or job.error), job_id, status, pages, and error; it never contains converted file contents.

Verify the signature

PDFDrill sends X-PDFDrill-Timestamp (Unix seconds) and X-PDFDrill-Signature (sha256=<hex HMAC>). Sign the exact raw request body, not re-serialized JSON. The signed bytes are the ASCII timestamp, a period, then the raw body. Reject timestamps more than five minutes from your clock and compare signatures in constant time.

import hashlib, hmac, os, time

webhook_secret = os.getenv("PDFDRILL_WEBHOOK_SECRET")
if webhook_secret:
    key = webhook_secret.encode()
else:
    api_key = os.environ["PDFDRILL_API_KEY"]
    key = hmac.new(api_key.encode(), b"PDFDrill webhook signing key v1",
                   hashlib.sha256).digest()
timestamp = request.headers["X-PDFDrill-Timestamp"]
signature = request.headers["X-PDFDrill-Signature"]
expected = "sha256=" + hmac.new(
    key, timestamp.encode("ascii") + b"." + request.get_data(),
    hashlib.sha256
).hexdigest()
if abs(time.time() - int(timestamp)) > 300:
    reject_request()
if not hmac.compare_digest(expected, signature):
    reject_request()

API requests use the same page quota as web conversions. API access is not included with Free, Starter, or Pro plans.