Form Data Extraction API: Turn Scanned Forms into Typed JSON

If you searched for a form data extraction API, you already know plain OCR is not the finish line. You need named values from applications, claims packets, KYC packs, surveys, and multi-field layouts so your app can validate and store them. Short answer: pick an API that returns typed fields from a schema you declare, not a text blob you re-parse. OCRskill does that with POST /ocr.json?fields=...: you list the form keys you care about, upload the scan or photo, and get trimmed strings and normalized dates back as JSON.

This guide treats forms as a document class. For the product announcement of structured JSON, see structured OCR JSON. For format tradeoffs (JSON vs XML), see OCR output as structured JSON or XML. Field lists and error behavior live in the Structured OCR JSON API reference.

What buyers mean by form OCR

“Form OCR” is shorthand for a pipeline that does more than read every character on the page. Teams evaluating a form data extraction API usually want:

• Named fields that match their domain (last_name, birthdate, nationality, company_name, invoice_date)
• Predictable types so dates land as YYYY-MM-DD and strings arrive trimmed
• Required vs optional behavior so missing critical fields fail loudly instead of silently writing nulls
• Upload flexibility for phone photos, scanner PDFs, and the same patterns they already use for plain OCR

Applications, insurance claims, onboarding packs, and survey sheets share a layout trait: many labeled blanks, often mixed print and handwriting, sometimes multiple pages. The extraction goal is a record your backend can insert, not a Markdown dump for human reading.

Template matching vs schema-field APIs

Two common product shapes show up in RFPs. They solve different problems.

Approach	How it works	Strengths	Weak spots
Template matching	Align the page to a fixed layout; read by coordinates or zones	Fast when every form is identical	Breaks when vendors change layouts, people photograph at an angle, or you onboard many form variants
Schema-field extraction	You declare field names; the model maps text on the page to those keys	Works across layout variants without a template per form	Still depends on readable print/handwriting and clear labels; you must choose required vs optional carefully

Template engines shine for a single government PDF that never changes. Schema-field APIs fit product and ops teams that see dozens of claim forms, partner applications, or invoice-like sheets with the same logical fields in different places. OCRskill’s /ocr.json path is the second model: you pass a comma-separated fields list, and the response is keyed JSON built from those names. Details and supported field names are documented on the OCR JSON API page.

If your only need is searchable text for review or RAG, stay on Markdown via /ocr. Structure is worth the schema when a database column or validation rule depends on a specific key.

A practical form extraction call

Get a key, declare the form schema, upload the file:

curl https://api.ocrskill.com/get-key.json

curl "https://api.ocrskill.com/ocr.json?fields=last_name,first_name,birthdate,nationality,company_name?,invoice_date?" \
  -H "Authorization: Bearer sk-your-key-here" \
  -F "file=@claim-form.jpg"

Example response shape:

{
  "last_name": "MUSTERMANN",
  "first_name": "ERIKA",
  "birthdate": "1964-08-12",
  "nationality": "DEUTSCH",
  "company_name": "ACME Supplies SRL"
}

invoice_date was optional (invoice_date?) and absent on this page, so it is omitted. Required fields without a ? fail with 400 if the document does not contain them. That is intentional for KYC and claims: better to reject a blurry scan early than to persist a half-empty applicant record.

The same upload styles work as on /ocr: multipart (-F "file=@..."), raw binary (--data-binary), and Mistral-style JSON with a document_url data URI. Inputs include common images (PNG, JPEG, WebP, GIF, and related formats) and documents (PDF and office formats covered in the existing docs). For a deeper walkthrough of typed output and discovery mode (omit fields to explore what is present), start from the structured OCR JSON API post.

Validation patterns that keep form pipelines honest

Extraction is only half of a trustworthy form flow. Wire these checks around the API:

1. Schema first. Decide which keys are required for each form type (application vs claim vs survey). Encode that in the fields query string with name vs name?.
2. Fail closed on critical fields. Treat 400 on missing required values as a review signal, not a retry storm. Surface the error (and any returned OCR text when present) to a human queue.
3. Normalize once. Dates already arrive as YYYY-MM-DD; do not re-parse locale strings in your app unless you have a second source of truth.
4. Type checks after JSON. Validate enums (country codes, product codes) and length bounds in your own layer. The API returns typed, trimmed values; domain rules stay yours.
5. Discovery only for onboarding. Run without fields when learning a new partner form. Lock a fixed schema before production traffic so response shape stays stable.

A clean pattern for multi-form products: map each inbound document type to a field list, call /ocr.json, then validate against a small JSON Schema or Zod/Pydantic model before write. Keep Markdown /ocr for free-text attachments that do not map to columns.

Form-focused pipeline shape

Think in stages so form OCR does not become a grab bag of scripts:

1. Capture – scanner profile, mobile photo, or PDF export into a staging bucket.
2. Classify – route applications, claims, invoices, and surveys to the right field list (rules, a light classifier, or human triage for new partners).
3. Extract – POST /ocr.json?fields=... with auth Authorization: Bearer sk-....
4. Validate – required keys, date sanity, enum checks, optional confidence or human review for handwriting-heavy pages.
5. Persist – write typed JSON to your DB or DMS; store the original image for audit.

Energy and utility ops that archive many packet types often pair DMS metadata with structured fields for high-volume invoices; the same split works for forms: archive the scan, store the record. See the energy company paperless document workflow if your forms also feed a long-term searchable archive.

Limitations (and when Markdown is better)

Be honest about failure modes before you promise automation:

• Handwriting quality. Messy pen, faint pencil, and heavy stamps still reduce accuracy. Plan a review path for field-captured forms.
• Multi-page strategies. For multi-page PDFs, decide whether one request covers the packet or you split pages and merge keys in your code. Do not assume every page carries every field.
• Required vs optional. Over-marking fields as required creates noisy 400s on incomplete forms. Under-marking hides missing KYC data. Tune per form type.
• Layout extremes. Extremely dense tables, overlapping stamps, or cropped phone photos may need a rescan rather than endless retries.
• When /ocr wins. Use Markdown OCR when you need full-page text for search, RAG, or human reading, not a fixed schema. Use /ocr.json when your app needs named columns.

None of this requires inventing vendor-specific templates for every partner form. It does require clear schemas and a review queue for the pages that fail required fields.

Choosing a form data extraction API

When you compare vendors, ask questions that map to production, not demos:

• Can I declare required and optional fields without writing a prompt?
• Do dates and strings arrive normalized, or do I re-clean every response?
• Are upload methods compatible with how I already send images and PDFs?
• Is there a discovery mode for new form types before I freeze a schema?
• Where is the field reference, and how do errors expose enough context to debug?

OCRskill’s answer is the fields query on https://api.ocrskill.com/ocr.json, Bearer auth, optional name? syntax, discovery when you omit fields, and the same upload styles as plain /ocr. Grab a key from get-key.json, lock a form schema, and wire validation around the typed JSON. For format choices after extraction (JSON first, XML only if a legacy consumer demands it), keep JSON vs XML for OCR output nearby. For the full field catalog and request shapes, use the OCR JSON API reference.

The durable win is not another text dump. It is a form record your application can trust: named keys, typed values, and a pipeline that fails closed when the scan cannot support the schema you declared.