Bol.ai API

Send a Bill of Lading document, receive structured JSON. One endpoint does the heavy lifting; two more let you retrieve past extractions and CSV exports.

Authentication: API keys are available on the Professional plan. Create one under API keys in the app, then send it as a Bearer token. Keys are shown once and stored hashed.

Extract a Bill of Lading

POST /api/bol/extract — body is the raw file (PDF, PNG or JPG, max 10 MB). Each successful extraction bills one document (metered on subscriptions, or one prepaid credit).

curl -X POST https://bol.ai/api/bol/extract \
  -H "Authorization: Bearer bolai_YOUR_KEY" \
  -H "Content-Type: application/pdf" \
  -H "X-Filename: maersk-bl-4711.pdf" \
  --data-binary @maersk-bl-4711.pdf

Response (200):

{
  "id": "0d7c2f86-9f3e-4a4b-8e9a-1c2d3e4f5a6b",
  "status": "done",
  "fields": {
    "bl_number": "MAEU123456789",
    "booking_number": "610203040",
    "scac": "MAEU",
    "carrier": "Maersk Line",
    "vessel": "EMMA MAERSK",
    "voyage": "124W",
    "shipper":      { "name": "...", "address": "..." },
    "consignee":    { "name": "...", "address": "..." },
    "notify_party": { "name": "...", "address": "..." },
    "port_of_loading": "Rotterdam, NL",
    "port_of_discharge": "New York, US",
    "place_of_receipt": null,
    "place_of_delivery": null,
    "containers": [{
      "container_number": "MSKU1234567",
      "seal_number": "NL445566",
      "container_type": "40RF",
      "packages": "1100 cartons",
      "description": "Frozen dairy products",
      "gross_weight_kg": 21500,
      "volume_cbm": 58.4
    }],
    "freight_terms": "PREPAID",
    "incoterms": "CIF",
    "date_of_issue": "2026-05-28"
  }
}

Fields that cannot be read from the document are null — they are never guessed.

List documents

GET /api/bol — your 100 most recent documents with status (pending | done | failed).

curl https://bol.ai/api/bol -H "Authorization: Bearer bolai_YOUR_KEY"

Get one extraction

GET /api/bol/:id — full extraction result. GET /api/bol/:id/csv — the same data as CSV (one row per container).

curl https://bol.ai/api/bol/0d7c2f86-.../csv \
  -H "Authorization: Bearer bolai_YOUR_KEY" -o extraction.csv

Save corrections

PATCH /api/bol/:id — overwrite extracted fields with corrected values. Corrections are stored alongside the original output and used for CSV exports.

curl -X PATCH https://bol.ai/api/bol/0d7c2f86-... \
  -H "Authorization: Bearer bolai_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields": { ...full corrected fields object... }}'

Email ingestion

Forward a BOL to extract@bol.ai from the email address on your account. Attachments (PDF/PNG/JPG) are extracted automatically and appear in your document list — same billing as uploads.

MCP server (AI agents)

Bol.ai is also a Model Context Protocol server, so Claude and other AI agents can extract BOLs directly. Endpoint: https://bol.ai/api/mcp (streamable HTTP), authenticated with the same Bearer API key. Tools: extract_bol (url or base64), list_documents, get_document.

{
  "mcpServers": {
    "bol-ai": {
      "type": "http",
      "url": "https://bol.ai/api/mcp",
      "headers": { "Authorization": "Bearer bolai_YOUR_KEY" }
    }
  }
}

Errors

Status	Meaning
`401`	Missing, invalid or revoked API key
`402`	No active subscription or credits — subscribe or buy a credit pack
`413`	File larger than 10 MB
`422`	Extraction failed (unreadable document) — you are not billed; status is recorded as `failed`

Data residency

Documents and extracted data are stored exclusively in the European Union (database in Western Europe, file storage under EU jurisdiction).