How to Use the PDF.ai Extract API

What Extract is for

• You sent a JSON schema that names the fields you want

• The response includes data.result shaped like that schema, plus data.citations that point each field back to source segments

• You know whether parse credits applied (new file/url) or you reused a cached docId

Practical rule: Extract answers "give me these fields." Ask answers a free-form question. Parse turns the PDF into markdown/contents first. Use Extract when your next step is a database row, not a chat reply.

Browser extract vs Extract API

Credits before you scale a schema

• Extraction credits: 2 credits × page count when the schema has ≤5 fields; 4 credits × page count when the schema has >5 fields

• Parse credits: apply when you send a file or url and there is no cached parse; 0 when you pass a cached docId

• Total: parse credits + extraction credits

• 10-page PDF, not cached, advanced parse quality, schema with 3 fields → parse 20 + extract 20 = 40 credits

• 5-page PDF, cached docId, schema with 8 fields → parse 0 + extract 20 = 20 credits

• Free: $0/month for 200 credits/month, no credit card required

• Paid examples: $49 / 3,000, $99 / 10,000, $249 / 30,000, $599 / 100,000 credits per month

Practical rule: keep schemas ≤5 fields while you are proving the pipeline. Crossing 5 fields doubles extract credits per page.

How to call Extract

1. Have an API key

2. Prefer a cached docId when you already parsed

3. POST a schema

• schema — JSON Schema string defining the structure to extract

• system_prompt — default "Be precise and thorough."

• docId, or url, or file

• quality: standard (default) or advanced

• lang_list: languages for standard OCR (default ["en"])

import requests
import json

url = "https://pdf.ai/api/v2/extract"
headers = {"X-API-Key": "YOUR_API_KEY"}

schema = {
    "type": "object",
    "properties": {
        "title": {"type": "string"},
        "author": {"type": "string"}
    },
    "required": ["title"]
}

data = {
    "docId": "your-document-id",
    "schema": json.dumps(schema),
    "system_prompt": "Extract document metadata accurately."
}

response = requests.post(url, headers=headers, data=data)
print(response.json())

4. Check the output before you trust it

• Confirm success and that data.result keys match your schema

• Open at least one citations[].pageNumber in the source PDF and compare the cited content to the field value

• If you get Invalid API key / No API key present, fix the header before you change the schema

• If fields are empty on a scanned PDF, parse first with quality=standard (or set quality on Extract when sending file/url) and retry with the returned docId

Practical rule: a non-empty result object is not a verified invoice. Read the citation for every field you will write to a database.

When Extract is the wrong tool

• You only need one chat answer in a browser. Use How to Chat with a PDF. No API key required for that job.

• You need a free-form answer in code. Use POST https://pdf.ai/api/v2/ask with a prior docId (Ask). Ask is 3 credits × total page count across the docIds you query.

• You only need searchable markdown / contents. Prefer Parse first (How to Get Started with the PDF.ai API).

• You wanted a generic “pdf api” category hub. Stay on https://pdf.ai/developer. This page is the Extract how-to, not a replacement hub.

A short action plan

1. Open https://pdf.ai/developer, create a key, store it once.

2. Check credit usage against page count and field count (≤5 vs >5).

3. Parse a short PDF (or reuse a docId), then POST https://pdf.ai/api/v2/extract with a tight schema.

4. Verify data.result against data.citations and the source PDF before you wire production.