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.
POST /api/bol/extract
— body is the raw file (PDF, PNG or JPG, max 10 MB). The document type — Bill of Lading, commercial invoice, packing list or CMR — is detected automatically and returned as doc_type
. Each successful extraction bills one document (metered on subscriptions, or one prepaid credit), regardless of type.
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",
"doc_type": "bill_of_lading",
"doc_label": "Bill of Lading",
"fields": {
"doc_type": "bill_of_lading",
"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_": "Rotterdam, NL",
"port_of_discharge": "New York, US",
"place_of_receipt": null,
"place_of_delivery": null,
"containers": [{
"container_number": "MSKU1234565",
"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.
When a container number fails its ISO 6346 check digit but a single unambiguous OCR-confusion fix passes, the corrected value is offered as container_number_suggestion
on that container (and echoed in warnings
). The read value is never overwritten.
One endpoint handles the freight documents that travel with a shipment. The type is classified automatically and returned as doc_type
(with a human doc_label
); fields
then carries the schema for that type. Each type has its own deterministic verification checks, and the CSV export adapts (one row per container, line item, package or goods line).
doc_type |
Document | Key fields |
|---|---|---|
bill_of_lading |
Bill of Lading | bl_number , carrier, vessel/voyage, ports, containers[] (ISO 6346 checked) |
commercial_invoice |
Commercial / proforma invoice | invoice_number , seller, buyer, line_items[] , currency, total_amount |
packing_list |
Packing list | packing_list_number , packages[] , net/gross weights, totals |
cmr |
CMR road waybill | cmr_number , sender, consignee, carrier, goods[] , gross weight |
The full per-type schemas are in the OpenAPI spec (BolFields
, InvoiceFields
, PackingListFields
, CmrFields
). To pin extraction to a known type, omit it — classification is automatic; if a file is none of the supported types it is rejected and not billed.
POST /api/bol/batch
— multipart/form-data
with up to 10 files under the field files
. Each file is processed and billed independently; the response reports a per-file outcome, so a batch that runs out of credits part-way through still returns the documents that succeeded.
curl -X POST https://bol.ai/api/bol/batch \
-H "Authorization: Bearer bolai_YOUR_KEY" \
-F "files=@maersk-bl-4711.pdf" \
-F "files=@msc-bl-8842.pdf"
{
"results": [
{ "filename": "maersk-bl-4711.pdf", "ok": true, "id": "0d7c…", "status": "done", "fields": { … }, "warnings": [] },
{ "filename": "msc-bl-8842.pdf", "ok": false, "id": null, "status": null, "error": "payment required: …" }
]
}
For larger volumes, call the single /extract
endpoint concurrently, or forward BOLs to extract@bol.ai
(below). The web app accepts a multi-file drop and runs the same batch for you.
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 /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
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... }}'
Turn a whole account's extractions into one master sheet. GET /api/bol/export
flattens every completed document into a normalized "shipment line" schema — one row per container, invoice line, package or goods line — so mixed document types land in a single file.
curl -H "Authorization: Bearer bolai_YOUR_KEY" \
"https://bol.ai/api/bol/export?format=xlsx" -o shipments.xlsx
format |
Returns |
|---|---|
csv (default) |
Normalized master sheet, one row per line item |
xlsx |
The same data as a real Excel workbook |
json |
{ count, rows: [...] } — structured rows for a TMS/ERP integration |
customs |
Customs-declaration draft from your Bills of Lading (HS code, parties, weights, container) |
Optional ?type=bill_of_lading|commercial_invoice|packing_list|cmr
limits the export to one document type. ?template=<id>
applies a saved column template — subset, reorder and rename columns to match your TMS/ERP import format. Manage templates in the app (Documents → Columns…) or via GET/PUT /api/me/export-templates
.
An export covers up to 1,000 documents (newest first). Above that the response carries an X-Export-Truncated: true
header (and truncated: true
in the json
format) so you can page the rest via the API.
Native connectors. One-click Google Sheets and direct TMS push (CargoWise, Descartes, Magaya) are roadmap items — they require a Google OAuth app and each vendor's API credentials respectively. Until then, the json
export plus webhooks are the integration path: point a webhook at Zapier/Make/n8n/Sheets, or pull format=json
straight into your own backend.
Every account has a unique, private email-in address — in-<token>@bol.ai
, shown in the app under Extract → Email documents in. Forward or scan-to-email any freight document to it and the attachments (PDF/PNG/JPG) are extracted automatically and appear in your document list — same billing as uploads. Because the account is identified by the address rather than the sender, it works from any source: office scanners, shared mailboxes, auto-forward rules. Keep the address private (anyone with it can send into your account) and regenerate it if it leaks.
Legacy: extract@bol.ai
still works, matched by the sender address on your account.
Every extraction includes a warnings
array from a deterministic verification pass: ISO 6346 container check digits (container_number_checksum_valid
per container), weight and date plausibility, and Incoterms/freight-terms validation. An empty array means nothing suspicious was found — it is not a guarantee of correctness.
A shipment's documents must agree or the customs entry gets held. GET /api/bol/:id/related
links the other documents in the same shipment (by shared reference numbers — B/L number, invoice number) and reconciles the overlapping fields, returning each linked document with field-by-field match
/mismatch
results for shipper/seller, consignee/buyer, total gross weight (5% tolerance) and total package count. In the app, open any document to see the discrepancies inline. Deterministic — no extra usage is billed.
Set a webhook URL in the app (or PUT /api/me/webhook
with {"url": "https://..."}
) and every completed extraction — uploads, batch, API and email-in — is POSTed to it. That single primitive is how you connect Bol.ai to Zapier, Make, n8n, a Google Sheet, or your own backend without polling. Use Send test event in the app to fire a sample first.
Payload (application/json
, header User-Agent: bol-ai-webhook/1.0
, 5 s timeout, best-effort):
{
"id": "0d7c2f86-…",
"filename": "maersk-bl-4711.pdf",
"status": "done",
"fields": { …the full BolFields object… },
"warnings": ["Container 1 (MSKU7234565): fails the ISO 6346 check digit — likely a misread… Did you mean MSKU1234565?"]
}
| Tool | How to receive it |
|---|---|
| Zapier | New Zap → trigger Webhooks by Zapier → Catch Hook. Copy the generated URL into Bol.ai, click Send test event, then map fields.* to any action (Sheets, Airtable, email…). |
| Make | Add a Custom webhook module, copy its address into Bol.ai, run Send test event so Make learns the data structure, then build the scenario. |
| n8n | Start with a Webhook node (POST), paste its production URL into Bol.ai. |
| Google Sheets | Publish a Google Apps Script doPost(e) web app that appends JSON.parse(e.postData.contents).fields as a row, then use its /exec URL as the webhook. |
Tip: include a hard-to-guess path or token in the URL (e.g. https://you.example.com/bol/9f3a…
) and reject anything else — that authenticates the caller without a shared secret.
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" }
}
}
}
| 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 |
Documents and extracted data are stored exclusively in the European Union (database in Western Europe, file storage under EU jurisdiction).