Contract OCR API: Clean JSON Out of Messy PDFs

This pack is the extraction layer I put in front of any document pipeline that has to produce structured records instead of a pile of text. The vision model reads the page in context. The schema decides what is allowed to leave. The validator decides what is allowed to write. You get the prompt, the schemas and the Python call that runs them. The thresholds and the retry wording sit beside it.

Template based OCR treats a page as a fixed map of coordinates, with every field pinned to one spot and every label to another. It works on one clean scan and falls apart on everything else, from a retainer with new letterhead to a lease with a stapled addendum to an ID photo taken at an angle. A vision-language model reads the page the way a person does, through layout, tables, handwriting and shifted blocks. The schema is what keeps that read honest.

Template OCR fails in specific, repeatable ways. Name the failure, and you know which layer to replace. Work the tables below against your current extractor before you change anything.

Table 1A · Template failure modes

Table 1B · Document inventory (fill this in)

List every document type you extract. If a type appears monthly or more, it ships a schema. If it appears yearly, route it to the generic contract schema and review.

What a context read does

One prompt template, parameterised by document type and target schema. The rules are hard on purpose. A prompt that allows prose allows silent parse failures downstream.

Extraction prompt template

What each rule prevents

Retry wording (use as written)

When the first pass fails envelope parse or schema validation, retry once with a reduced prompt. Do not argue with the model. Narrow the job.

Two attempts is the ceiling. A third attempt is superstition. After two failures the document goes to the reviewer queue with both raw responses attached.

There is one base envelope and six type-specific property sets. The envelope carries status, confidence, evidence and conflict state. The property sets carry the fields that differ by document. Validate the envelope first, then the property set for the type you requested. Anything not in the schema is dropped before it reaches a record.

Base envelope schema

Three points. additionalProperties: false is the rejection valve for invented keys. meets_threshold lets your orchestrator branch on a boolean instead of parsing free text. evidence is keyed by field name so a reviewer opens one object and sees both the claim and the page.

Type property sets

Each block below is the fields object for one document type, plus its required list. Load the base envelope, then the set for the requested type. Null means absent. Empty string is a validation failure.

Table 3A · Property set checklist (fill this in)

Validation runs in code. The prompt asks for honesty. The validator enforces it. Run every check below on every payload before anything writes.

Validation rules

• Envelope check: the <response><json> wrapper parses, then the inner object parses as JSON. Reject and retry with the reduced prompt if not.
• Type check: every field matches its declared type. Integer fields reject floats. Number fields reject strings with currency symbols still attached.
• Required check: every field in the type's required list is present. Null is allowed only where the schema allows it. A required field that is null forces escalation.
• Range check: amounts non-negative, notice days between 0 and your ceiling, confidence between 0 and 1, expiry dates in the past on identity documents.
• Enum check: fee type, lease type, filing type, urgency and jurisdiction limited to values your CRM accepts. Anything else is a mapping failure and gets rejected.
• Numeric consistency: if digits and words disagree, or the same figure appears twice with different values, set numeric_conflict and stop. Language models hallucinate numeric conversions. This is the most expensive class of error in a legal document.
• Date shape and order: values match their date_precision. End date after start date. Expiry after issue. Hearing date not before filing date. Notice windows consistent with the termination clause.
• Cross-reference parties: party names appear in the evidence map. Each party name is checked against your conflict list and existing contact records before any write.
• Evidence present: each required field has a source quote and a page. A field with no evidence is treated as absent.
• Unknown key check: any property outside the schema is dropped and logged. The model does not get to invent fields.

Cross-check matrix

Python: vision call, schema validation, routing

One module. Call the model with the document and the prompt. Parse the envelope. Validate against the base schema and the type property set. Run the cross-checks. Route on the result. This is the shape I ship.

Table 4A · Validation worksheet (fill this in)

A low confidence score is still information. The model is telling you it is unsure. The correct response is a reviewer with the payload and the source page.

Table 5A · Confidence thresholds and retry wording

Floors are starting points. Raise a floor when a document type starts producing accepted payloads that reviewers keep correcting. Lower it only with evidence that reviewers are re-reading correct output.

Escalation triggers

Escalation queue record

Reviewer checklist

• Open the source page beside the candidate payload. Work from the page itself.
• Confirm every required field against the evidence quote before changing anything.
• Correct by writing a corrected object. Never overwrite the model output. Both versions stay.
• Record why the model was wrong: layout, illegible, ambiguous clause, bad page split.
• If the same reason appears three times in a week, change the prompt or the schema. Do not keep correcting by hand.
• Close the item with a decision: accept as corrected, reject and re-request, or block for attorney sign-off.

Run the free workflow diagnostic, or read the case study, then decide. The diagnostic reads your current document path and tells you which layer is failing. The D'Alessio Law Group case study shows the document and intake pipeline end to end. When the pack is not enough, the same systems ship as client engagements through document processing agents.

Everything above is yours to read. The workbook adds the empty worksheets, so you fill them in on your own stack with your own owners, fields and failures. It opens in any browser, on any device, and it saves as you type.

When you want my read on your own stack, the document processing questionnaire takes ten minutes, and I reply with the first fix I would make and what it costs.