Skip to content
Docs Security Sign in
PdfParse

PDF extraction API in four steps

Send one request with a PDF, a scan or an image. PdfParse reads the layout, runs OCR where a page has no text layer, applies your schema and returns JSON, Markdown and CSV in the same response or through a webhook.

Parse PDF

See the four steps on one page

Drop a PDF or scan and watch the steps run on page one. The result shows the rendered page with block outlines next to the JSON, Markdown and CSV tabs.

Drop a PDF or scan

PDF, PNG or JPG up to 10 MB. Page one is parsed in full, right here.

Or try a sample file
Output

Optional. Comma separated field names, for example invoice_number, total, due_date.

Page one is parsed in your browser and never uploaded. No card needed to try page one.

What one call returns

Page one rendered with every block outlined, next to the JSON your code receives.

  1. Reading text layer
  2. Detecting layout
  3. Extracting tables
  4. Building JSON
Rendered page Page 1 of your document

Headings, paragraphs, tables and totals detected

heading
Invoice
paragraph
Harbor Street Joinery
14 Dock Lane
Portsmouth, NH 03801
key_value
Invoice no.INV-2026-0418IssuedOct 14, 2026DueNov 13, 2026
table
DescriptionQtyUnitAmount
Oak countertop, 2.4 m2640.001,280.00
Cabinet doors, shaker1285.001,020.00
On site fitting1450.00450.00
total
Subtotal2,750.00Tax 8.5%233.75Total dueUSD 2,983.75
paragraph
Payment by bank transfer within 30 days.
Quote the invoice number with your transfer.
Goods remain ours until paid in full.
footer
Harbor Street JoineryPage 1 of 2
Locked page

Pages 2 and later are parsed after you create an account.

Output 
{
  "document": {
    "pages": 2,
    "parsed_pages": 1,
    "language": "en"
  },
  "pages": [
    {
      "number": 1,
      "blocks": [
        { "type": "heading", "text": "Invoice", "bbox": [48, 52, 132, 84] },
        { "type": "paragraph", "text": "Harbor Street Joinery, 14 Dock Lane, Portsmouth" },
        { "type": "key_value", "pairs": {
            "Invoice no.": "INV-2026-0418",
            "Issued": "Oct 14, 2026",
            "Due": "Nov 13, 2026" } },
        { "type": "table", "columns": ["Description", "Qty", "Unit", "Amount"],
          "rows": [
            ["Oak countertop, 2.4 m", 2, 640.00, 1280.00],
            ["Cabinet doors, shaker", 12, 85.00, 1020.00],
            ["On site fitting", 1, 450.00, 450.00] ] },
        { "type": "total", "label": "Total due", "value": 2983.75, "currency": "USD", "confidence": 0.98 }
      ]
    }
  ],
  "fields": {
    "invoice_number": { "value": "INV-2026-0418", "confidence": 0.99, "page": 1 },
    "total": { "value": 2983.75, "confidence": 0.98, "page": 1 },
    "due_date": { "value": "2026-11-13", "confidence": 0.97, "page": 1 }
  }
}

Downloads from the demo include a watermark field and cover page one only.

Page one is parsed in your browser, so your file never reaches our servers.

Request
The same request from your code
Read the API reference 
$ curl https://api.pdfparse.ai/v1/parse \
  -H "Authorization: Bearer $PDFPARSE_API_KEY" \
  -F file[email protected] \
  -F outputs=json,markdown,csv
200 OK, 1 page parsed

One request, four stages

Every file that reaches the PDF extraction API moves through the same pipeline. You do not configure the stages one by one. You send the file with the outputs you want, and the response tells you what the engine found on every page.

Step What happens What you control
1. Upload The file arrives as multipart data or as a URL Page range, outputs, OCR mode
2. Layout and OCR Text, blocks, reading order and tables are detected OCR set to auto, always or off
3. Extraction and schema Your fields are filled and chunks are built Schema, chunking strategy and size
4. Output and webhook JSON, Markdown and CSV are returned or delivered Sync response, job polling or webhook

Step 1. Upload the file

You call POST /v1/parse with the file as multipart form data, or with a JSON body that holds a "url" field pointing to the document. Accepted inputs are PDF, scanned PDF, PNG, JPG and TIFF, including multi page files. Authentication is a single bearer header with your API key.

The pages option narrows the work to a range such as "1-5". This matters on long reports where only the summary tables are useful, because pages outside the range are skipped and never billed against your monthly allowance. Each PDF page counts as one page, and so does each image file.

Each plan sets a ceiling per file, checked before any work starts.

Plan Max file size Max pages per file
Starter 25 MB 100
Growth 50 MB 300
Scale 100 MB 1,000
Enterprise 200 MB 2,000
curl 
curl https://api.pdfparse.ai/v1/parse \
  -H "Authorization: Bearer pp_live_your_key" \
  -F [email protected] \
  -F 'outputs=["json","markdown","csv"]' \
  -F ocr=auto \
  -F pages=1-5

Step 2. Layout and OCR

The engine first reads the embedded text layer when the PDF has one. It then detects blocks on each page and labels them as heading, paragraph, table, list, form field, checkbox or image. Every block carries its text, a bounding box in page coordinates and a confidence value.

Reading order is rebuilt from the layout, not from the order in which characters were written into the file. A two column research page comes back as the left column followed by the right column, with footnotes after the body text instead of in the middle of a sentence.

Tables get their own pass. Merged header cells are expanded so every column has a name, and a table that continues across pages is joined into one table with its page span recorded.

With ocr set to "auto", pages without a text layer go through OCR and pages with one do not. Set "always" for PDFs whose text layer is broken or misencoded, and "off" when you only want born digital pages and prefer to skip scans.

Step 3. Extraction and schema

Layout tells you where things are. A schema tells PdfParse what you need. You define field names, types and short descriptions once with POST /v1/schemas, then pass the schema_id on each parse call, or send an inline schema for a one off request.

Supported field types are string, number, date, money, boolean and array. The response returns them in a "fields" object, each with its own confidence value and the page it came from, so your code can accept clean values and send doubtful ones to a person.

For retrieval pipelines, the chunking option splits the document by section. A setting such as strategy "section" with max_tokens 800 keeps each chunk inside one heading where possible, and every chunk lists its start page, end page, section path and bounding box. Schemas and chunking are part of the Growth plan and above.

Step 4. Output and webhook

One call returns every format you asked for. JSON holds pages, blocks, tables, fields, chunks and usage. Markdown keeps headings, lists and tables in a form that language models and documentation tools read well. CSV gives you each table as its own file, with rows and column counts listed in the response.

For longer documents you can register a webhook. PdfParse sends parse.completed or parse.failed to your endpoint, signs every delivery with the PdfParse-Signature header using HMAC SHA256, and retries with backoff when your server does not answer.

Synchronous and asynchronous jobs

Small files are parsed while the request is open and the full result comes back in the response body. Larger files return a job id straight away, and the work continues in the queue.

You then have two options. Poll GET /v1/jobs/{id} until the status reports completion, or skip polling and let the webhook tell you when the job ends. Both routes return the same result object.

Scale and Enterprise use a priority queue, which keeps latency steady when many accounts submit large batches at once.

Python 
job = client.parse("annual-report.pdf", outputs=["json"], wait=False)
status = client.jobs.get(job.id)
print(status.status)

What happens to the file afterwards

Files travel over TLS and are encrypted at rest while they are stored. How long they stay depends on your plan. Starter keeps documents and results for 7 days. Growth lets you set retention up to 30 days. Scale and Enterprise add a zero retention mode, where the file and the result are removed as soon as the response or webhook has been delivered.

Deleting a document removes the stored copy, but it does not return pages to your allowance, because pages count as usage in the billing period. Files dropped into the demo on this site are parsed in your browser and never uploaded. Files are never used to train models, on any plan.

For the full data handling picture, see secure document processing. For every option and field, read the document parsing API reference.

FAQ

How do I know if my file will be processed synchronously?

Send the request the same way in every case. If the file is small, the response already contains the full result. If it is larger, the response contains a job id, and you either poll GET /v1/jobs/{id} or wait for the webhook.

Does OCR run on every page?

Only when needed with the default setting. With ocr set to auto, pages that already have a text layer are read directly and only image pages go through OCR. You can force OCR on all pages or turn it off.

Can I parse only part of a long PDF?

Yes. Pass a range such as "1-5" in the pages option. Only the pages you parse count toward your monthly allowance.

What happens when I reach my monthly page limit?

Parsing pauses and the dashboard shows an Upgrade button. Nothing is charged automatically. If you upgrade, the difference is charged right away and parsing continues.

Are my files used to improve the models?

No. Files are never used to train models. They are kept only for the retention period of your plan, or not at all in zero retention mode on Scale and Enterprise.

Run the four steps on your own documents

Pick a plan, get an API key and send your first file in a few minutes.