API Reference

Base URL: https://api.getbl.ai/api/v1

Authentication

All API requests (except /templates) require your API key in the X-API-Key header.

X-API-Key: gbl_your_api_key_here

API keys are prefixed with gbl_. Keys are stored as SHA-256 hashes — if you lose your key, rotate it from the dashboard.

POST /extract

Extract structured data from a freight document PDF.

Request body

Field	Type	Required	Description
pdfBase64	string	Yes	Base64-encoded PDF, max 10MB
templateName	string	No	BillOfLading, CommercialInvoice, PackingList, AirWaybill, CustomsEntry
templateJson	string	No	Custom JSON schema (overrides templateName)
instructions	string	No	Natural language guidance for the AI — restrict fields, specify units, override formatting behaviour
webhookUrl	string	No	Optional async webhook callback URL

Response

{
  "success": true,
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "processedAt": "2026-04-18T10:22:00Z",
  "data": {
    "billOfLadingNumber": { "value": "MSCU1234567", "confidence": "high" },
    "vessel": { "value": "MSC DIANA", "confidence": "high" },
    "portOfLoading": { "value": "Shanghai, CN", "confidence": "high" },
    "etd": { "value": "2026-03-15", "confidence": "medium" },
    "grossWeightKg": { "value": 12450.0, "confidence": "high" }
  },
  "unrecognizedFields": []
}

GET /templates

Returns all available extraction templates. No authentication required.

GET /api/v1/templates

GET /usage

Returns usage statistics for the current month for your API key.

{
  "totalCalls": 42,
  "successfulCalls": 41,
  "failedCalls": 1,
  "totalInputTokens": 77364,
  "totalOutputTokens": 13104,
  "monthlyLimit": 100,
  "callsRemaining": 58,
  "tier": "Free",
  "periodStart": "2026-04-01T00:00:00Z",
  "periodEnd": "2026-05-01T00:00:00Z"
}

Template reference

BillOfLading Ocean Bill of Lading — shipper, consignee, vessel, containers, weights

▾

{
  "shipper": {"value": null, "_confidence": ""},
  "consignee": {"value": null, "_confidence": ""},
  "notify_party": {"value": null, "_confidence": ""},
  "bill_of_lading_number": {"value": null, "_confidence": ""},
  "booking_number": {"value": null, "_confidence": ""},
  "vessel_name": {"value": null, "_confidence": ""},
  "voyage_number": {"value": null, "_confidence": ""},
  "port_of_loading": {"value": null, "_confidence": ""},
  "port_of_discharge": {"value": null, "_confidence": ""},
  "place_of_receipt": {"value": null, "_confidence": ""},
  "place_of_delivery": {"value": null, "_confidence": ""},
  "etd": {"value": null, "_confidence": "", "format": "YYYY-MM-DD"},
  "eta": {"value": null, "_confidence": "", "format": "YYYY-MM-DD"},
  "container_numbers": {"value": [], "_confidence": ""},
  "seal_numbers": {"value": [], "_confidence": ""},
  "description_of_goods": {"value": null, "_confidence": ""},
  "hs_codes": {"value": [], "_confidence": ""},
  "number_of_packages": {"value": null, "_confidence": ""},
  "package_type": {"value": null, "_confidence": ""},
  "gross_weight_kg": {"value": null, "_confidence": ""},
  "net_weight_kg": {"value": null, "_confidence": ""},
  "measurement_cbm": {"value": null, "_confidence": ""},
  "freight_terms": {"value": null, "_confidence": "", "note": "PREPAID or COLLECT"},
  "incoterms": {"value": null, "_confidence": ""},
  "carrier": {"value": null, "_confidence": ""},
  "carrier_scac": {"value": null, "_confidence": ""},
  "shipper_reference": {"value": null, "_confidence": ""},
  "consignee_reference": {"value": null, "_confidence": ""},
  "on_board_date": {"value": null, "_confidence": "", "format": "YYYY-MM-DD"},
  "issue_date": {"value": null, "_confidence": "", "format": "YYYY-MM-DD"},
  "issue_place": {"value": null, "_confidence": ""},
  "number_of_originals": {"value": null, "_confidence": ""},
  "is_negotiable": {"value": null, "_confidence": ""},
  "marks_and_numbers": {"value": null, "_confidence": ""}
}

CommercialInvoice Commercial Invoice — seller, buyer, line items, totals

▾

{
  "invoice_number": {"value": null, "_confidence": ""},
  "invoice_date": {"value": null, "_confidence": "", "format": "YYYY-MM-DD"},
  "seller": {"value": null, "_confidence": ""},
  "seller_address": {"value": null, "_confidence": ""},
  "buyer": {"value": null, "_confidence": ""},
  "buyer_address": {"value": null, "_confidence": ""},
  "ship_to": {"value": null, "_confidence": ""},
  "po_number": {"value": null, "_confidence": ""},
  "lc_number": {"value": null, "_confidence": ""},
  "payment_terms": {"value": null, "_confidence": ""},
  "currency": {"value": null, "_confidence": ""},
  "incoterms": {"value": null, "_confidence": ""},
  "port_of_loading": {"value": null, "_confidence": ""},
  "port_of_discharge": {"value": null, "_confidence": ""},
  "country_of_origin": {"value": null, "_confidence": ""},
  "country_of_destination": {"value": null, "_confidence": ""},
  "line_items": {"value": [], "_confidence": "", "item_fields": ["line_number", "description", "hs_code", "quantity", "unit", "unit_price", "total_price", "country_of_origin"]},
  "subtotal": {"value": null, "_confidence": ""},
  "freight_amount": {"value": null, "_confidence": ""},
  "insurance_amount": {"value": null, "_confidence": ""},
  "other_charges": {"value": null, "_confidence": ""},
  "total_amount": {"value": null, "_confidence": ""},
  "gross_weight_kg": {"value": null, "_confidence": ""},
  "net_weight_kg": {"value": null, "_confidence": ""},
  "number_of_packages": {"value": null, "_confidence": ""},
  "package_type": {"value": null, "_confidence": ""},
  "marks_and_numbers": {"value": null, "_confidence": ""},
  "bank_details": {"value": null, "_confidence": ""},
  "signatory": {"value": null, "_confidence": ""}
}

PackingList Packing List — carton-level detail, dimensions, weights

▾

{
  "packing_list_number": {"value": null, "_confidence": ""},
  "packing_list_date": {"value": null, "_confidence": "", "format": "YYYY-MM-DD"},
  "invoice_reference": {"value": null, "_confidence": ""},
  "shipper": {"value": null, "_confidence": ""},
  "consignee": {"value": null, "_confidence": ""},
  "po_number": {"value": null, "_confidence": ""},
  "vessel_name": {"value": null, "_confidence": ""},
  "port_of_loading": {"value": null, "_confidence": ""},
  "port_of_discharge": {"value": null, "_confidence": ""},
  "container_numbers": {"value": [], "_confidence": ""},
  "line_items": {"value": [], "_confidence": "", "item_fields": ["carton_number", "description", "hs_code", "quantity_per_carton", "number_of_cartons", "total_quantity", "unit", "gross_weight_kg", "net_weight_kg", "dimensions_cm"]},
  "total_cartons": {"value": null, "_confidence": ""},
  "total_quantity": {"value": null, "_confidence": ""},
  "total_gross_weight_kg": {"value": null, "_confidence": ""},
  "total_net_weight_kg": {"value": null, "_confidence": ""},
  "total_cbm": {"value": null, "_confidence": ""},
  "marks_and_numbers": {"value": null, "_confidence": ""}
}

AirWaybill Air Waybill — MAWB/HAWB, airports, chargeable weight

▾

{
  "mawb_number": {"value": null, "_confidence": ""},
  "hawb_number": {"value": null, "_confidence": ""},
  "shipper": {"value": null, "_confidence": ""},
  "shipper_account_number": {"value": null, "_confidence": ""},
  "consignee": {"value": null, "_confidence": ""},
  "notify_party": {"value": null, "_confidence": ""},
  "issuing_carrier": {"value": null, "_confidence": ""},
  "carrier_code": {"value": null, "_confidence": ""},
  "origin_airport": {"value": null, "_confidence": ""},
  "origin_airport_code": {"value": null, "_confidence": ""},
  "destination_airport": {"value": null, "_confidence": ""},
  "destination_airport_code": {"value": null, "_confidence": ""},
  "routing": {"value": [], "_confidence": ""},
  "issue_date": {"value": null, "_confidence": "", "format": "YYYY-MM-DD"},
  "flight_date": {"value": null, "_confidence": "", "format": "YYYY-MM-DD"},
  "flight_number": {"value": null, "_confidence": ""},
  "number_of_pieces": {"value": null, "_confidence": ""},
  "gross_weight_kg": {"value": null, "_confidence": ""},
  "chargeable_weight_kg": {"value": null, "_confidence": ""},
  "rate_per_kg": {"value": null, "_confidence": ""},
  "nature_of_goods": {"value": null, "_confidence": ""},
  "dimensions_cm": {"value": null, "_confidence": ""},
  "declared_value_for_customs": {"value": null, "_confidence": ""},
  "declared_value_for_carriage": {"value": null, "_confidence": ""},
  "freight_charges": {"value": null, "_confidence": ""},
  "other_charges": {"value": null, "_confidence": ""},
  "total_charges": {"value": null, "_confidence": ""},
  "currency": {"value": null, "_confidence": ""},
  "freight_terms": {"value": null, "_confidence": "", "note": "PREPAID or COLLECT"},
  "shipper_reference": {"value": null, "_confidence": ""},
  "handling_info": {"value": null, "_confidence": ""}
}

CustomsEntry Customs Entry — HTS codes, duty rates, entry details

▾

{
  "entry_number": {"value": null, "_confidence": ""},
  "entry_type": {"value": null, "_confidence": ""},
  "entry_date": {"value": null, "_confidence": "", "format": "YYYY-MM-DD"},
  "import_date": {"value": null, "_confidence": "", "format": "YYYY-MM-DD"},
  "importer_name": {"value": null, "_confidence": ""},
  "importer_id": {"value": null, "_confidence": ""},
  "importer_address": {"value": null, "_confidence": ""},
  "exporter": {"value": null, "_confidence": ""},
  "country_of_export": {"value": null, "_confidence": ""},
  "country_of_origin": {"value": null, "_confidence": ""},
  "port_of_unlading": {"value": null, "_confidence": ""},
  "port_of_entry": {"value": null, "_confidence": ""},
  "carrier": {"value": null, "_confidence": ""},
  "vessel_flight": {"value": null, "_confidence": ""},
  "bill_of_lading_awb": {"value": null, "_confidence": ""},
  "master_bill": {"value": null, "_confidence": ""},
  "line_items": {"value": [], "_confidence": "", "item_fields": ["line_number", "description", "hts_code", "country_of_origin", "quantity", "unit", "gross_weight_kg", "entered_value", "currency", "duty_rate", "duty_amount", "mpf", "hmf"]},
  "total_entered_value": {"value": null, "_confidence": ""},
  "total_duty": {"value": null, "_confidence": ""},
  "total_mpf": {"value": null, "_confidence": ""},
  "total_hmf": {"value": null, "_confidence": ""},
  "total_fees": {"value": null, "_confidence": ""},
  "broker_name": {"value": null, "_confidence": ""},
  "broker_id": {"value": null, "_confidence": ""},
  "bond_type": {"value": null, "_confidence": ""},
  "liquidation_date": {"value": null, "_confidence": "", "format": "YYYY-MM-DD"}
}

Error codes

Status	Meaning
200	Extraction successful
400	Bad request — invalid PDF, payload too large, or extraction failed
401	Missing X-API-Key header
403	Invalid or inactive API key
429	Monthly rate limit exceeded — check Retry-After header
500	Internal server error
503	Service unavailable