Reading bills of lading from a photo

The POST /api/v1/verify/bol endpoint takes a single photo of a Bill of Lading and returns a structured object with the fields a TMS, freight audit, or chargeback workflow needs. It uses Gemini gemini-2.5-flash in structured-output mode (responseMimeType: "application/json", temperature: 0) with a BOL-specific prompt, and a Zod schema in lib/verify-ai/bol-extract.ts validates every response before it reaches your code.

Endpoint

POST /api/v1/verify/bol
X-API-Key: vai_your_api_key

The endpoint accepts two body shapes:

• multipart/form-data with an image file field, or
• application/json with { "image": "<base64>" } (data URLs are fine — the leading data:image/...;base64, is stripped).

JPEG, PNG, and WebP are accepted, up to 10 MB.

Response

{
  "bol_number": "BOL-44128301",
  "pro_number": "0123-4567-89",
  "weight_lbs": 1840,
  "freight_class": "70",
  "ship_from": {
    "name": "Acme Manufacturing",
    "address": "1200 Industrial Way",
    "city": "Cincinnati",
    "state": "OH",
    "zip": "45202"
  },
  "ship_to": {
    "name": "Walmart DC 6094",
    "address": "1101 N Maxwell Rd",
    "city": "Bentonville",
    "state": "AR",
    "zip": "72712"
  },
  "pieces": 24,
  "confidence": 0.91,
  "processing_time_ms": 1432
}

Every field is validated against the Zod schema in lib/verify-ai/bol-extract.ts before the response is returned. If the model can't confidently extract a field it comes back as null rather than a hallucinated value (address sub-fields are independently nullable — a single-line address may have only address set, with city / state / zip null). confidence is a model-reported self-score in [0, 1] — use it to gate downstream automation. processing_time_ms is wall-clock time from the start of extractBolFields() to the JSON response.

Worked example

curl -X POST https://verify.switchlabs.dev/api/v1/verify/bol \
-H "X-API-Key: vai_your_api_key" \
-F "image=@bol_photo.jpg"

Use cases

Trucking dispatch automation. Drop a photo of the BOL at pickup into your dispatch tool; the tool back-fills load weight, freight class, and PRO without anyone re-keying.

Freight audit. Compare the extracted weight against the carrier invoice. A 200lb discrepancy on a reweigh charge is one of the most common audit recoveries — having the BOL number and recorded weight together turns it into a one-click dispute.

OS&D dispute evidence. Pair a damaged-goods photo (run through /api/v1/verify) with the BOL extraction so the claim packet has the load identifier, the carrier identifier, and the visual evidence attached.

Retailer chargeback prep. Walmart Code 22 / 24 / 25 / 90 deductions all reference the BOL number on the receiving paperwork. Extracting it directly from the driver's copy keeps you in sync with what the DC scanned in. Pass the extracted value as metadata.bol_number on the corresponding /api/v1/verify call — the chargeback defense workflow uses that exact key to join the verification to the matching verify_ai_shipments row when draftDispute() is called.

Limitations (v1)

• Image input only. PDF uploads are not supported in v1. Convert PDFs client-side (e.g. via pdf2image) and submit the first page.
• Single-page extraction. Multi-page BOLs are common in long-haul; v1 reads only the page in the image. For multi-page loads, submit each page individually and merge the results server-side.
• Handwritten amendments. Counts and weights overwritten by hand at the dock will sometimes return the printed value rather than the corrected value. Treat handwritten edits as a "send to review" signal in your downstream code.
• No rate-limit budget separate from /v1/verify. Calls count against the same per-key rate limit as standard verifications.

What's next

• Chargeback defense — the downstream workflow that consumes extracted BOL numbers as shipment keys.
• TMS integrations — how to push extracted BOLs straight into McLeod, SupplyPike, or a custom adapter.
• API reference: Verify — the underlying compliance endpoint; the BOL endpoint shares its auth and rate-limit behavior.