Document parsing API reference

All requests go to the base URL below over HTTPS. Authenticate with the API key from your dashboard in a bearer header. Keys are secret, so call the API from your server, never from a browser or mobile app.

BASE_URL=https://api.pdfparse.ai/v1
curl "$BASE_URL/usage" -H "Authorization: Bearer pp_live_your_key"

Starter includes 1 API key, Growth 5, Scale 20, and Enterprise has unlimited keys with limits per key. A request without a valid key returns 401.

Send the file as multipart form data in a field named file, or send a JSON body with a url the API can download. Accepted formats are PDF, scanned PDF, PNG, JPG and TIFF, including multi page files.

curl https://api.pdfparse.ai/v1/parse \
  -H "Authorization: Bearer pp_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://files.example.com/invoice.pdf",
    "outputs": ["json", "markdown", "csv"],
    "ocr": "auto",
    "pages": "1-5",
    "schema_id": "sch_supplier_invoice",
    "chunking": {"strategy": "section", "max_tokens": 800}
  }'

Small files return 200 with the complete result. Larger files return 202 with the job id and a status, and the result is read from GET /v1/jobs/{id} or delivered by webhook.

POST /v1/schemas takes a name and a list of fields. Each field has a name, a type and a description that tells the engine what to look for. The accepted types are string, number, date, money, boolean and array. GET /v1/schemas lists what you have saved. Growth stores up to 10 schemas, Scale and Enterprise have no limit.

POST /v1/batches accepts up to 500 files per job on Growth and above, with the same options as a single parse. GET /v1/batches/{id} reports overall progress and the id of every job inside the batch. GET /v1/usage returns pages used, the allowance and the dates of the current billing period, and on Scale and Enterprise a breakdown per API key. Pages count as usage in the billing period, and deleting a document never returns them.

Errors return a JSON body with a code, a readable message and the HTTP status.

Jobs wait in the queue when your account submits more than it can run at once, and the API returns 429 when that queue is full. Scale and Enterprise use a priority queue. Prices for each plan are on PDF extraction API pricing.

On Growth and above you can register an HTTPS endpoint in the dashboard. PdfParse sends two events, parse.completed and parse.failed, each as a JSON body with a type and a data object that holds the job. Every delivery carries the PdfParse-Signature header, the hex encoded HMAC SHA256 of the raw body computed with your endpoint secret. Compute the same value on your side over the raw bytes and compare in constant time before trusting the payload. Deliveries that do not receive a 2xx answer are retried with backoff, so handlers should tolerate the same event twice.

import hmac, hashlib

def is_valid(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Add an Idempotency-Key header with a unique value to POST /v1/parse and POST /v1/batches. If a timeout makes you send the same request again with the same key, the API returns the original job instead of creating a second one, so pages are never counted twice for one intended request.

The version is part of the path, /v1. Within a version we only add things, such as new optional request options, new response fields or new block types, so clients should ignore fields they do not know. A change that would break existing code is released under a new path, and /v1 keeps working alongside it.

The Python PDF parser and the PDF parse npm package cover every endpoint in this reference with typed results, polling and retries. The processing stages behind each call are described on the PDF extraction API page, and the module list by plan is on the data extraction tool page.