Introduction

The KabyTech B/L Intelligence API lets you parse ocean Bills of Lading documents (PDF, image, or scanned copies) and receive structured JSON with all shipping details extracted. The API supports B/L documents from all major ocean carriers including Evergreen, ONE, MSC, Maersk, COSCO, Hapag-Lloyd, Yang Ming, and HMM.

Extract shipper, consignee, notify party, vessel/voyage details, port information, container details with ISO 6346 validation, goods descriptions, freight terms, and more. The API handles both Master and House B/L formats, original and telex release copies, and supports multi-container shipments with individual container-level extraction.

All API requests are made over HTTPS. Responses are returned in JSON format. The API follows RESTful conventions and uses standard HTTP status codes.

Base URL

Base https://api.kabytech.co.th/v1

All endpoints described in this documentation are relative to this base URL. For example, the parse endpoint is available at https://api.kabytech.co.th/v1/bl/parse.

Authentication

All API requests require authentication via an API key. Include your API key in the X-API-Key header with every request. You can obtain your API key from the KabyTech Dashboard after creating an account.

Authentication Header
X-API-Key: kby_live_a1b2c3d4e5f6g7h8i9j0...

API keys are prefixed with kby_live_ for production and kby_test_ for sandbox. Test keys process documents but return synthetic data — they're free to use during development.

Header	Value	Required
`X-API-Key`	Your API key (`kby_live_...` or `kby_test_...`)	Required
`Content-Type`	`application/json` or `multipart/form-data`	Required
`Accept`	`application/json`	Optional

Quick Start

Get your first Bill of Lading parsed in under 5 minutes. This example uses the Python SDK to upload a PDF and receive structured data with container details.

Python — Quick Start
from kabytech import KabyTechClient
 
# Initialize client with your API key
client = KabyTechClient(api_key="kby_live_a1b2c3d4...")
 
# Parse a Bill of Lading document (PDF, PNG, JPG)
result = client.bl.parse(
    file="./shipping-docs/evergreen-bl-EGLV123456789.pdf",
    options={
        "include_confidence": True,
        "validate_containers": True,
        "extract_all_containers": True
    }
)
 
# Access parsed B/L data
print(f"B/L Number: {result.bl_number}")
print(f"Vessel: {result.vessel} / Voyage: {result.voyage}")
print(f"POL: {result.port_of_loading.name} → POD: {result.port_of_discharge.name}")
print(f"Containers: {len(result.containers)}")
print(f"Confidence: {result.confidence}%")
 
# Access parties
shipper = result.shipper
print(f"Shipper: {shipper.name}, {shipper.address}")
 
# Iterate container details (ISO 6346 validated)
for ctr in result.containers:
    print(f"  {ctr.number} | {ctr.type} | {ctr.weight} kg | Seal: {ctr.seal}")

POST /v1/bl/parse

Parse a single Bill of Lading document and return structured data. Accepts PDF, PNG, JPG, and TIFF images. Returns all B/L fields as structured JSON including multi-container extraction with ISO 6346 container number validation.

POST /v1/bl/parse

Parses an ocean Bill of Lading document and extracts all shipping data fields. Supports documents from Evergreen, ONE, MSC, Maersk, COSCO, Hapag-Lloyd, Yang Ming, HMM, and other carriers. Average processing time is 1.4–2.2 seconds per document depending on container count.

Request Body (JSON)

Parameter	Type	Description
`document` Required	`string`	Base64-encoded document content (PDF, PNG, JPG, TIFF)
`format` Required	`string`	Document format: `pdf`, `png`, `jpg`, or `tiff`
`include_confidence` Optional	`boolean`	Include per-field confidence scores (default: `true`)
`validate_containers` Optional	`boolean`	Validate container numbers against ISO 6346 check digit (default: `true`)
`extract_all_containers` Optional	`boolean`	Extract all containers from multi-page B/L (default: `true`)
`webhook_url` Optional	`string`	URL to receive a POST callback when processing completes
`carrier_hint` Optional	`string`	Carrier SCAC code hint for improved accuracy (e.g., `EGLV`, `MAEU`)

Example Request (cURL)

cURL — Parse B/L
curl -X POST https://api.kabytech.co.th/v1/bl/parse \
  -H "X-API-Key: kby_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "document": "JVBERi0xLjQKMS...",
    "format": "pdf",
    "include_confidence": true,
    "validate_containers": true
  }'

Response (200 OK)

JSON Response — 200 OK · 1.87s
{
  "id": "bl_7k4m9p2n6j1x",
  "bl_number": "EGLV123456789012",
  "bl_type": "original",
  "carrier": "Evergreen Line",
  "carrier_scac": "EGLV",
  "shipper": {
    "name": "SIAM SILK EXPORT CO., LTD.",
    "address": "88 Silom Road, Bangrak, Bangkok 10500, Thailand",
    "contact": "+66-2-234-5678"
  },
  "consignee": {
    "name": "TOKYO TEXTILE IMPORTS K.K.",
    "address": "3-14-2 Nihonbashi, Chuo-ku, Tokyo 103-0027, Japan"
  },
  "notify_party": {
    "name": "KANSAI FREIGHT BROKERS LTD.",
    "address": "2-8-1 Nanko-kita, Suminoe-ku, Osaka 559-0034"
  },
  "vessel": "EVER GLORY",
  "voyage": "0288W",
  "port_of_loading": { "name": "Laem Chabang", "code": "THLCH" },
  "port_of_discharge": { "name": "Tokyo", "code": "JPTYO" },
  "place_of_receipt": { "name": "Bangkok ICD Lat Krabang", "code": "THBKK" },
  "place_of_delivery": { "name": "Tokyo CY", "code": "JPTYO" },
  "containers": [
    {
      "number": "EGHU9012345",
      "iso6346_valid": true,
      "seal": "TH20260142",
      "type": "40HC",
      "size_type_code": "45G1",
      "weight_kg": 18450,
      "packages": 520,
      "package_type": "CARTONS",
      "description": "THAI SILK FABRIC, 100% MULBERRY, HS 5007.20"
    },
    {
      "number": "EGHU7654321",
      "iso6346_valid": true,
      "seal": "TH20260143",
      "type": "40HC",
      "size_type_code": "45G1",
      "weight_kg": 16280,
      "packages": 480,
      "package_type": "CARTONS",
      "description": "THAI SILK ACCESSORIES, HS 6214.10"
    }
  ],
  "goods_description": "1,000 CARTONS THAI SILK FABRIC AND ACCESSORIES",
  "freight_terms": "Prepaid",
  "number_of_originals": 3,
  "date_of_issue": "2026-03-20",
  "total_containers": 2,
  "total_packages": 1000,
  "total_weight_kg": 34730,
  "confidence": 96.8,
  "processing_ms": 1870,
  "validation_errors": [],
  "created_at": "2026-03-26T10:22:14Z"
}

GET /v1/bl/{id}

Retrieve a previously parsed B/L result by its unique ID. Results are stored for 90 days. Use this endpoint to fetch results asynchronously when using webhooks, or to re-access previously parsed documents.

GET /v1/bl/{id}

Returns the full parsed result for a specific Bill of Lading document. The {id} is the unique identifier returned by the /bl/parse endpoint (e.g., bl_7k4m9p2n6j1x). Returns the same response schema as the parse endpoint.

Path Parameters

Parameter	Type	Description
`id` Required	`string`	The unique B/L result ID (e.g., `bl_7k4m9p2n6j1x`)

Query Parameters

Parameter	Type	Description
`include_raw` Optional	`boolean`	Include raw OCR text alongside structured data (default: `false`)
`container_filter` Optional	`string`	Filter containers by number prefix (e.g., `EGHU`)

cURL — Get B/L by ID
curl https://api.kabytech.co.th/v1/bl/bl_7k4m9p2n6j1x \
  -H "X-API-Key: kby_live_a1b2c3d4..."

POST /v1/bl/batch

Submit multiple B/L documents for batch processing. The API accepts up to 50 documents per batch request and processes them asynchronously. Use the webhook_url parameter or poll the GET /bl/{id} endpoint for results. Ideal for processing shipment manifests or digitizing archived B/L records.

POST /v1/bl/batch

Submits a batch of Bill of Lading documents for asynchronous processing. Returns immediately with a batch ID and individual document IDs. Each document is processed independently — one failure will not affect the others. Supports mixed carrier documents in a single batch.

Request Body

Parameter	Type	Description
`documents` Required	`array`	Array of document objects (max 50). Each object has `document` and `format` fields.
`webhook_url` Optional	`string`	URL to receive a POST callback when the entire batch is complete
`priority` Optional	`string`	`normal` (default) or `high` (Professional/Enterprise plans only)
`validate_containers` Optional	`boolean`	Validate all container numbers against ISO 6346 (default: `true`)

Python — Batch Processing
from kabytech import KabyTechClient
import glob
 
client = KabyTechClient(api_key="kby_live_a1b2c3d4...")
 
# Collect all B/L PDFs from a directory
files = glob.glob("./shipping-docs/bl-*.pdf")
 
# Submit batch (max 50 per request)
batch = client.bl.batch(
    files=files,
    webhook_url="https://your-app.com/webhooks/kabytech",
    priority="high",
    validate_containers=True
)
 
print(f"Batch ID: {batch.batch_id}")
print(f"Documents submitted: {batch.total_documents}")
 
# Or poll for results
results = batch.wait()  # Blocks until complete
for r in results:
    print(f"{r.bl_number}: {len(r.containers)} containers, {r.confidence}%")

GET /v1/status

Check the API health and your account usage. Returns current API status, your plan details, and remaining request quota for the current billing period.

GET /v1/status

Returns API health status, your account plan information, and current usage statistics. Use this to monitor your quota or verify connectivity.

JSON Response — GET /status
{
  "status": "operational",
  "version": "v1.8.2",
  "plan": "professional",
  "usage": {
    "period": "2026-03",
    "requests_used": 3841,
    "requests_limit": 10000,
    "batch_remaining": 6159
  }
}

B/L Sections Reference

The KabyTech API parses all standard sections of an ocean Bill of Lading. Below are the primary section groups returned in the response, each containing multiple structured fields.

#	Section Group	Key	Description
1	Header	`header`	B/L number, date of issue, B/L type (original, copy, telex release), number of originals, carrier name and SCAC code
2	Shipper	`shipper`	Full shipper/exporter name, registered address, contact phone/fax, email, tax ID
3	Consignee	`consignee`	Consignee name, full address, contact details. Supports "To Order" and "To Order of" clauses
4	Notify Party	`notify_party`	Notify party name, address, contact. Multiple notify parties supported with `also_notify` field
5	Vessel & Voyage	`vessel_voyage`	Vessel name, Lloyd's IMO number, voyage number, flag state, pre-carriage vessel (if feeder)
6	Ports	`ports`	Port of Loading (POL), Port of Discharge (POD), Place of Receipt (POR), Place of Delivery (POD) — all with UN/LOCODE
7	Containers	`containers`	Container number (ISO 6346 validated), seal number, size/type (20GP, 40HC, etc.), tare weight, gross weight, packages, marks & numbers, goods description per container
8	Goods Description	`goods`	Combined goods description, HS codes, marks and numbers, total packages, package type, gross weight, measurement (CBM)
9	Freight & Charges	`freight`	Freight terms (Prepaid/Collect), freight amount, currency, additional charges, exchange rate, total charges
10	Terms & Conditions	`terms`	Applicable law jurisdiction, clause paramount, Hague-Visby rules indicator, additional clauses

Response Field Reference

Every API response includes these top-level fields alongside the detailed section data. The B/L parser extracts 45+ fields from each document.

bl_number string The full B/L number as printed on the document (e.g., "EGLV123456789012")

bl_type string Document type: original, copy, telex_release, express, or switch

carrier string Full carrier/shipping line name (e.g., "Evergreen Line")

carrier_scac string Standard Carrier Alpha Code (e.g., "EGLV", "MAEU", "MSCU", "ONEY")

shipper object Shipper/exporter details: name, address, contact, tax_id

consignee object Consignee details: name, address, contact. May contain to_order flag

notify_party object Notify party: name, address, contact

also_notify object Additional notify party (if present on document)

vessel string Carrying vessel name (e.g., "EVER GLORY")

voyage string Voyage number (e.g., "0288W")

imo_number string Lloyd's IMO vessel identification number

port_of_loading object Loading port with name and UN/LOCODE code

port_of_discharge object Discharge port with name and UN/LOCODE code

place_of_receipt object Place of receipt (inland origin) with name and code

place_of_delivery object Final delivery place with name and code

containers array Array of container objects. Each has: number, iso6346_valid, seal, type, size_type_code, weight_kg, packages, package_type, description

goods_description string Combined goods description text from all containers

hs_codes string[] Array of extracted HS commodity codes (e.g., ["5007.20", "6214.10"])

marks_and_numbers string Shipping marks and numbers as printed on the B/L

freight_terms string Freight payment terms: Prepaid or Collect

freight_amount object Freight amount: value (number), currency (ISO 4217)

number_of_originals integer Number of original B/L copies issued (typically 3)

date_of_issue string B/L issue date in ISO 8601 format

shipped_on_board_date string Date cargo was loaded on vessel (ISO 8601)

total_containers integer Total number of containers on this B/L

total_packages integer Total number of packages across all containers

total_weight_kg number Total gross weight in kilograms

total_measurement_cbm number Total measurement in cubic meters

confidence float Overall extraction confidence as a percentage (0–100). Scores above 95% indicate high reliability.

processing_ms integer Processing time in milliseconds. Average: 1,400–2,200ms depending on container count.

validation_errors array Array of validation warnings. Each has field, message, and severity properties.

id string Unique result identifier for retrieval via GET /bl/{id}. Prefixed with "bl_".

created_at string ISO 8601 timestamp of when the document was processed (UTC).

Error Codes

The API uses standard HTTP status codes. All error responses include a JSON body with error, message, and code fields.

Status	Code	Description
400	`invalid_document`	The document could not be read. Check encoding and format parameter.
400	`unsupported_format`	Document format not supported. Use pdf, png, jpg, or tiff.
401	`invalid_api_key`	API key is missing, invalid, or expired.
403	`plan_limit_exceeded`	Monthly request quota exceeded. Upgrade your plan or wait for reset.
404	`bl_not_found`	No parsed result found for the given ID. Results expire after 90 days.
422	`parse_failed`	Document was read but no B/L data could be extracted. Verify document content.
422	`container_validation_failed`	One or more container numbers failed ISO 6346 check digit validation.
429	`rate_limited`	Too many requests. Respect the rate limits for your plan tier.
500	`internal_error`	Unexpected server error. Retry the request. If persistent, contact support.
503	`service_unavailable`	API is temporarily unavailable for maintenance. Typically under 5 minutes.

Error Response Example — 401
{
  "error": "invalid_api_key",
  "message": "The API key provided is invalid or has been revoked.",
  "code": 401
}

Rate Limits

Rate limits vary by plan tier. All limits are applied per API key on a per-minute and per-month basis. Rate limit headers are included in every response.

60

requests/min
Starter Plan

300

requests/min
Professional Plan

1,000

requests/min
Enterprise Plan

Response Header	Description
`X-RateLimit-Limit`	Maximum requests per minute for your plan
`X-RateLimit-Remaining`	Remaining requests in the current minute window
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets

Official SDKs

We provide official SDKs for the most popular languages in the Thai logistics tech ecosystem. All SDKs are open source and available on GitHub.

🐍

Python

Python 3.8+

pip install kabytech

⚪

Node.js

Node 16+

npm i @kabytech/sdk

🔮

PHP

PHP 8.0+

composer require kabytech/sdk

☕

Java

Java 11+

co.th.kabytech:sdk:1.4.0

Node.js — B/L Parsing with Container Extraction
const { KabyTech } = require('@kabytech/sdk');
 
const client = new KabyTech({ apiKey: 'kby_live_a1b2c3d4...' });
 
const result = await client.bl.parse({
  file: './evergreen-bl.pdf',
  validateContainers: true
});
 
console.log(result.blNumber); // "EGLV123456789012"
console.log(result.vessel); // "EVER GLORY"
console.log(result.portOfLoading.name); // "Laem Chabang"
 
// Extract container details
for (const ctr of result.containers) {
  console.log(`${ctr.number} | ${ctr.type} | ${ctr.weightKg} kg`);
  console.log(`  ISO 6346 valid: ${ctr.iso6346Valid}`);
  console.log(`  Seal: ${ctr.seal}`);
  console.log(`  ${ctr.packages} ${ctr.packageType}: ${ctr.description}`);
}

PHP — B/L Parsing
use KabyTech\KabyTechClient;
 
$client = new KabyTechClient('kby_live_a1b2c3d4...');
 
$result = $client->bl->parse([
  'file' => './bl-document.pdf',
  'validate_containers' => true,
]);
 
echo "B/L: " . $result->blNumber . "\n";
echo "Vessel: " . $result->vessel . " / " . $result->voyage . "\n";
echo "Containers: " . count($result->containers) . "\n";
 
foreach ($result->containers as $ctr) {
  echo "  {$ctr->number} ({$ctr->type}) - {$ctr->weightKg} kg\n";
}

Need help integrating?

Our integration team can help you connect the KabyTech B/L API to CargoWise, SAP, Oracle TMS, or your custom freight management system.

Contact Support About Us

Bill of Lading API Reference

Introduction

Base URL

Authentication

Quick Start

POST /v1/bl/parse

Request Body (JSON)

Example Request (cURL)

Response (200 OK)

GET /v1/bl/{id}

Path Parameters

Query Parameters

POST /v1/bl/batch

Request Body

GET /v1/status

B/L Sections Reference

Response Field Reference

Error Codes

Rate Limits

60

300

1,000

Official SDKs

Python

Node.js

PHP

Java

Need help integrating?

Ready to integrate?