Air Waybill PDFs to Validated JSON: A Narrow API for Freight Developers

ttzevol — Wed, 04 Nov 2026 09:04:55 +0000

If you build cargo TMS, forwarder portals, or customs pre-alert pipelines, you already know the gap: the airline or agent emails a MAWB/HAWB PDF (or someone snaps a phone photo), and your system needs structured fields—AWB number, airports, pieces, weights—not another blob in object storage.

Generic “upload any document” tools and brittle regex/templates fail the same way: carrier layouts drift, house forms look nothing like master forms, and a wrong check digit silently lands in your database. You do not need a general document AI. You need one document type → one schema → rules that fail loudly.

That is what DocAPI is for.

The painful part is not “reading text”

OCR-ish extraction alone is not enough for air waybills. An 11-digit AWB has an IATA Mod-7 check digit. Chargeable weight is usually at least gross. Departure and destination should be real IATA three-letter codes when the form prints them. Piece counts get misread on multi-copy scans.

Regex and per-airline templates break the week a new forwarder form shows up. Chat-style extraction is fine for demos; production queues need stable JSON keys, validators, and a needs_review flag so bad rows do not auto-post.

What DocAPI does

DocAPI is a narrow document → JSON API aimed at developers—not a no-code inbox product. Same idea as category peers like FormX or Parseur (fixed document types, structured output), but scoped to air waybills only for v1.

One endpoint for Master (MAWB) and House (HAWB)
One schema for both (awb_level tells you which)
Rule validation on the extracted fields, not optional garnish

Upload a PDF or common image (file= multipart). You get back a single JSON object per document: parties, airports, flight hints when present, pieces, gross/chargeable kg, per-field confidence, validation results, and needs_review.

It does not replace EDI/FWB when you already have clean messages. It fills the PDF/scan gap—pre-alerts, emailed copies, phone photos—where structured EDI never arrives. Courier parcel labels (DHL/UPS/FedEx tracking stickers) and ocean B/L are out of scope for v1.

Fields and validators (high level)

Core keys include document_type (air_waybill), awb_level (mawb | hawb | unknown), awb_number (airline 11-digit XXX-XXXXXXXX), optional hawb_number, shipper/consignee names, airport_dep / airport_dest, pieces, gross_kg / chargeable_kg, plus field_confidence and validations.

Built-in checks:

AWB Mod-7 — last digit of the 11-digit number must match the IATA serial-mod-7 rule. Invalid candidates are rejected or replaced when a valid number is still recoverable from the page text.
chargeable_kg >= gross_kg — usual volumetric pricing constraint; failures flag review.
Low confidence or failed checks set needs_review: true so you can route to a human queue instead of writing garbage downstream.

Marketing line, honestly: dedicated AWB extraction plus rule validation on general AI models—without asking you to train a custom model or maintain carrier templates.

Try it in a few minutes

Playground: https://getdocapi.com/playground.html
Docs: https://getdocapi.com/docs.html
API base: https://docapi-awb.onrender.com

Get a free API key (100 extractions / UTC month) from the playground, or buy a prepaid pack on pricing. Every extract call needs a Bearer token:

curl -sS -X POST "https://docapi-awb.onrender.com/v1/extract/awb" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -F "file=@./sample-mawb.pdf;type=application/pdf"

Accepts PDF and common images (e.g. .pdf, .png, .jpg). Keep files under ~20 MB for the current host. Check balance with GET /v1/me using the same Bearer header.

Cold start note: the public API runs on a free Render host. The first request after idle can take ~30–60 seconds while the service wakes up. Subsequent calls are much faster. Plan a health ping or timeout accordingly in CI and demos.

Pricing (high level)

Free: 100 extractions / month (playground + API, same schema and validators)
PAYG: $0.12 per successful AWB after free quota
Prepaid packs: $12 → 100 docs, $50 → 500 docs

Details and checkout: https://getdocapi.com/pricing.html. Bill per successful air waybill document, not per page.

Who should care

Freight/logistics backend engineers who already ingest AWB PDFs weekly and want a boring HTTP contract: upload file, get validated JSON, branch on needs_review. If your lane already has perfect FWB, keep it. If humans still re-key from scans, this is the slice of the problem DocAPI targets.

DEV Community: ttzevol