5 credits / callPOST /api/v1/extract/document

Extract — AI Document Extraction

Extract structured data from PDFs, invoices, contracts, and any document using Claude AI. Define a schema with the fields you need and waypoints returns a clean JSON object — no regex, no brittle parsing, no hallucinated free text.

How it works

You send a document

Base64-encode your PDF, image, or document and POST it with your extraction schema.

Claude reads it

waypoints sends the document to Claude using forced tool_use — Claude must populate your schema fields exactly.

You get clean JSON

The response is a typed JSON object matching your schema, with a confidence score and detected language.

Structured output guarantee

The Extract module always uses tool_choice: { type: "tool" } with the Claude API. Claude is forced to call your tool (schema) — it cannot respond with free text. This guarantees a valid, parseable JSON object every time.

POST/api/v1/extract/document

Submit a base64-encoded document and a schema describing the fields to extract. Supported MIME types include application/pdf, image/png, image/jpeg, and image/webp.

Parameter	Type	Required	Description
file	string	yes	Base64-encoded document content
mimeType	string	yes	MIME type of the document: application/pdf, image/png, image/jpeg, image/webp
schema	object	yes	Extraction schema: { type: string, fields: string[] }
language	string	no	Expected language hint. "auto" (default) lets Claude detect it automatically

Schema object

Field	Type	Description
type	string	A label for the document type, e.g. "invoice", "contract", "receipt"
fields	string[]	Array of field names to extract from the document

cURL — extract invoice data

# First base64-encode your PDF:
# B64=$(base64 -i invoice.pdf)

curl -X POST https://api.waypoints.tech/v1/extract/document \
  -H "x-api-key: wp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "<base64-encoded-pdf>",
    "mimeType": "application/pdf",
    "schema": {
      "type": "invoice",
      "fields": [
        "vendor_name",
        "vendor_vat",
        "total_amount",
        "vat_amount",
        "invoice_date",
        "invoice_number",
        "line_items"
      ]
    },
    "language": "auto"
  }'

SDK (@waypoints/sdk)

import waypoints from "@waypoints/sdk";
import { readFileSync } from "fs";

const wp = new waypoints({ apiKey: process.env.WAYPOINTS_API_KEY });

const pdfBuffer = readFileSync("./invoice.pdf");
const base64 = pdfBuffer.toString("base64");

const result = await wp.extract.document({
  file: base64,
  mimeType: "application/pdf",
  schema: {
    type: "invoice",
    fields: [
      "vendor_name",
      "vendor_vat",
      "total_amount",
      "vat_amount",
      "invoice_date",
      "invoice_number",
      "line_items",
    ],
  },
  language: "auto",
});

console.log(result.data.vendor_name);   // "Acme NV"
console.log(result.data.total_amount);  // 1210.00
console.log(result.confidence);         // 0.97
console.log(result.language);           // "nl"

Response

{
  "data": {
    "vendor_name": "Acme NV",
    "vendor_vat": "BE0123456789",
    "total_amount": 1210.00,
    "vat_amount": 210.00,
    "invoice_date": "2026-03-15",
    "invoice_number": "INV-2026-0042",
    "line_items": [
      { "description": "Web development services", "quantity": 1, "unit_price": 1000.00, "amount": 1000.00 }
    ]
  },
  "confidence": 0.97,
  "language": "nl",
  "credits_used": 5,
  "request_id": "req_01jx9k2m3n4p5q6r7s8t9u0v"
}

Common Schema Examples

Receipt

{
  "type": "receipt",
  "fields": ["merchant_name", "total", "date", "payment_method", "items"]
}

Contract

{
  "type": "contract",
  "fields": ["parties", "effective_date", "termination_date", "governing_law", "key_obligations"]
}

Identity document

{
  "type": "id_document",
  "fields": ["full_name", "date_of_birth", "document_number", "expiry_date", "nationality"]
}

Notes

File size

Maximum base64-encoded file size is 5 MB (approximately 3.75 MB raw). For larger documents, split into pages and extract each page individually.

Confidence score

The confidence field (0–1) reflects Claude's certainty about the extraction. Values above 0.85 are considered high-confidence. Lower values indicate ambiguous content — verify manually before using in production workflows.

Missing fields

If a requested field cannot be found in the document, it is returned as null in the data object rather than omitted. This lets you distinguish between "not found" and "not requested".

The Extract module uses claude-sonnet-4-20250514 via the Anthropic API. Extraction results may vary for low-resolution scans or handwritten documents. For best results, use machine-readable PDFs or high-resolution scans (≥ 150 DPI).