Introduction

The KabyTech SWB Intelligence API lets you parse Sea Waybill documents (PDF, image, or scanned copies) and receive structured JSON with all shipping details extracted. Sea Waybills are non-negotiable transport documents that do not require surrender of an original — enabling express release of cargo at destination without the delays of traditional B/L processing.

The API supports SWB documents from all major ocean carriers and is optimized for intra-Asia sea freight operations. It automatically detects the express release status, extracts shipper, consignee, vessel/voyage details, port information, container data, and freight terms. The express release flag enables faster cargo clearance workflows.

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/swb/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 Sea Waybill parsed in under 5 minutes. This example uses the Python SDK to upload a PDF and receive structured data with express release detection.

Python — Quick Start
from kabytech import KabyTechClient
 
# Initialize client with your API key
client = KabyTechClient(api_key="kby_live_a1b2c3d4...")
 
# Parse a Sea Waybill document (PDF, PNG, JPG)
result = client.swb.parse(
    file="./shipping-docs/swb-SWBKBT2026001234.pdf",
    options={
        "include_confidence": True,
        "detect_express_release": True,
        "validate_containers": True
    }
)
 
# Access parsed SWB data
print(f"SWB Number: {result.swb_number}")
print(f"Express Release: {result.express_release}")  # True = no original surrender
print(f"Vessel: {result.vessel} / Voyage: {result.voyage}")
print(f"POL: {result.port_of_loading.name} → POD: {result.port_of_discharge.name}")
print(f"Confidence: {result.confidence}%")
 
# Access parties
shipper = result.shipper
print(f"Shipper: {shipper.name}")
 
consignee = result.consignee
print(f"Consignee: {consignee.name}")
 
# Express release enables faster cargo clearance
if result.express_release:
    print("No original document surrender required - proceed to cargo release")

POST /v1/swb/parse

Parse a single Sea Waybill document and return structured data. Accepts PDF, PNG, JPG, and TIFF images. Returns all SWB fields as structured JSON including express release detection and container details.

POST /v1/swb/parse

Parses a Sea Waybill document and extracts all shipping data fields. Automatically detects express release status. Supports documents from all major carriers for intra-Asia and global sea freight. Average processing time is 1.2–1.8 seconds per document.

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`)
`detect_express_release` Optional	`boolean`	Detect express release / no-surrender clauses (default: `true`)
`validate_containers` Optional	`boolean`	Validate container numbers against ISO 6346 (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 SWB
curl -X POST https://api.kabytech.co.th/v1/swb/parse \
  -H "X-API-Key: kby_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "document": "JVBERi0xLjQKMS...",
    "format": "pdf",
    "include_confidence": true,
    "detect_express_release": true
  }'

Response (200 OK)

JSON Response — 200 OK · 1.34s
{
  "id": "swb_3m8k1p7n2j6x",
  "swb_number": "SWBKBT2026001234",
  "document_type": "sea_waybill",
  "express_release": true,
  "carrier": "COSCO Shipping Lines",
  "carrier_scac": "COSU",
  "shipper": {
    "name": "THAI GLOBAL EXPORTS CO., LTD.",
    "address": "123 Sukhumvit Road, Klongtoey, Bangkok 10110, Thailand",
    "contact": "+66-2-391-5678"
  },
  "consignee": {
    "name": "ROTTERDAM IMPORT BV",
    "address": "Europaweg 50, 3199 LC Rotterdam, Netherlands"
  },
  "notify_party": {
    "name": "AMSTERDAM FREIGHT BROKERS B.V.",
    "address": "Keizersgracht 100, 1015 AA Amsterdam, Netherlands"
  },
  "vessel": "COSCO SHIPPING ARIES",
  "voyage": "068W",
  "port_of_loading": { "name": "Laem Chabang", "code": "THLCH" },
  "port_of_discharge": { "name": "Rotterdam", "code": "NLRTM" },
  "containers": [
    {
      "number": "TCLU1234567",
      "iso6346_valid": true,
      "seal": "TH20260088",
      "type": "40RF",
      "size_type_code": "42R1",
      "weight_kg": 18400,
      "packages": 1200,
      "package_type": "CARTONS",
      "description": "CANNED PINEAPPLE IN SYRUP, HS 2008.20",
      "temperature_c": null
    }
  ],
  "goods_description": "1,200 CARTONS CANNED PINEAPPLE IN SYRUP",
  "hs_codes": ["2008.20"],
  "freight_terms": "Prepaid",
  "total_packages": 1200,
  "total_weight_kg": 18400,
  "date_of_issue": "2026-03-18",
  "surrender_required": false,
  "confidence": 97.1,
  "processing_ms": 1340,
  "validation_errors": [],
  "created_at": "2026-03-26T08:45:22Z"
}

GET /v1/swb/{id}

Retrieve a previously parsed SWB 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/swb/{id}

Returns the full parsed result for a specific Sea Waybill document. The {id} is the unique identifier returned by the /swb/parse endpoint (e.g., swb_3m8k1p7n2j6x). Returns the same response schema as the parse endpoint.

Path Parameters

Parameter	Type	Description
`id` Required	`string`	The unique SWB result ID (e.g., `swb_3m8k1p7n2j6x`)

Query Parameters

Parameter	Type	Description
`include_raw` Optional	`boolean`	Include raw OCR text alongside structured data (default: `false`)
`include_release_status` Optional	`boolean`	Include detailed express release analysis (default: `true`)

cURL — Get SWB by ID
curl https://api.kabytech.co.th/v1/swb/swb_3m8k1p7n2j6x \
  -H "X-API-Key: kby_live_a1b2c3d4..."

POST /v1/swb/batch

Submit multiple SWB 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 /swb/{id} endpoint for results. Ideal for intra-Asia express release shipments where fast processing is critical.

POST /v1/swb/batch

Submits a batch of Sea Waybill 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. Express release status is detected for every document in the 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)
`detect_express_release` Optional	`boolean`	Detect express release for all documents (default: `true`)

Python — Batch Processing
from kabytech import KabyTechClient
import glob
 
client = KabyTechClient(api_key="kby_live_a1b2c3d4...")
 
# Collect all SWB PDFs from a directory
files = glob.glob("./shipping-docs/swb-*.pdf")
 
# Submit batch (max 50 per request)
batch = client.swb.batch(
    files=files,
    webhook_url="https://your-app.com/webhooks/kabytech",
    priority="high",
    detect_express_release=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:
    release = "EXPRESS" if r.express_release else "STANDARD"
    print(f"{r.swb_number}: {release}, {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": 2156,
    "requests_limit": 10000,
    "batch_remaining": 7844
  }
}

SWB Sections Reference

The KabyTech API parses all standard sections of a Sea Waybill document. Below are the primary section groups returned in the response. Unlike a Bill of Lading, the SWB is non-negotiable and always includes express release status.

#	Section Group	Key	Description
1	Header	`header`	SWB number, date of issue, document type, carrier name and SCAC code. Unlike B/L, there are no "originals" — the SWB is a single non-negotiable document
2	Shipper	`shipper`	Full shipper/exporter name, registered address, contact phone/fax, email, tax ID
3	Consignee	`consignee`	Named consignee (never "To Order" as SWB is non-negotiable). Name, address, contact details
4	Notify Party	`notify_party`	Notify party name, address, contact. Typically the consignee's freight agent at destination
5	Vessel & Voyage	`vessel_voyage`	Vessel name, voyage number, pre-carriage vessel (if feeder service), expected arrival date
6	Ports	`ports`	Port of Loading (POL), Port of Discharge (POD) — all with UN/LOCODE. SWB is common for direct port-to-port intra-Asia routes
7	Cargo Details	`cargo`	Container numbers (ISO 6346 validated), packages, gross weight, measurement (CBM), goods description, HS codes, marks and numbers
8	Freight Terms	`freight`	Freight terms (Prepaid/Collect), freight amount, currency, additional charges
9	Express Release	`express_release`	Express release flag (`true`/`false`), surrender requirements, release clause text. The key differentiator from B/L — no original document surrender required for cargo release

Response Field Reference

Every API response includes these top-level fields alongside the detailed section data. The SWB parser extracts 35+ fields from each document.

swb_number string The full Sea Waybill number as printed on the document (e.g., "SWBKBT2026001234")

document_type string Always sea_waybill for SWB documents

express_release boolean Express release flag. true = no original document surrender required at destination. This is the key advantage of SWB over B/L.

surrender_required boolean Inverse of express release. false for SWB (always no surrender required).

carrier string Full carrier/shipping line name (e.g., "COSCO Shipping Lines")

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

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

consignee object Consignee details: name, address, contact. Always named (never "To Order")

notify_party object Notify party: name, address, contact

vessel string Carrying vessel name (e.g., "COSCO SHIPPING ARIES")

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

port_of_loading object Loading port with name and UN/LOCODE code

port_of_discharge object Discharge port with name and UN/LOCODE code

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

goods_description string Combined goods description text from all containers

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

freight_terms string Freight payment terms: Prepaid or Collect

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

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

date_of_issue string SWB issue date in ISO 8601 format

carrier_booking_ref string Carrier booking reference number

release_clause string Full text of the express release / waybill clause from the document

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,200–1,800ms for single documents.

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

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

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	`swb_not_found`	No parsed result found for the given ID. Results expire after 90 days.
422	`parse_failed`	Document was read but no SWB data could be extracted. Verify document content.
422	`not_a_waybill`	Document appears to be a B/L rather than a Sea Waybill. Use the B/L endpoint instead.
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 — 422
{
  "error": "not_a_waybill",
  "message": "The document appears to be a negotiable Bill of Lading, not a Sea Waybill. Use POST /v1/bl/parse instead.",
  "code": 422
}

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 — SWB Parsing with Express Release Detection
const { KabyTech } = require('@kabytech/sdk');
 
const client = new KabyTech({ apiKey: 'kby_live_a1b2c3d4...' });
 
const result = await client.swb.parse({
  file: './sea-waybill.pdf',
  detectExpressRelease: true
});
 
console.log(result.swbNumber); // "SWBKBT2026001234"
console.log(result.expressRelease); // true
console.log(result.vessel); // "COSCO SHIPPING ARIES"
console.log(result.portOfLoading.name); // "Laem Chabang"
 
// Check express release status for cargo clearance
if (result.expressRelease) {
  console.log('No original surrender needed - proceed to release');
  // Trigger cargo release workflow
  await triggerCargoRelease(result.swbNumber, result.consignee);
}

Java — SWB Parsing
import co.th.kabytech.KabyTechClient;
import co.th.kabytech.model.SwbResult;
 
KabyTechClient client = KabyTechClient.builder()
    .apiKey("kby_live_a1b2c3d4...")
    .build();
 
SwbResult result = client.swb().parse(
    SwbParseRequest.builder()
        .file(Paths.get("./sea-waybill.pdf"))
        .detectExpressRelease(true)
        .build()
);
 
System.out.println("SWB: " + result.getSwbNumber());
System.out.println("Express Release: " + result.isExpressRelease());
System.out.println("Vessel: " + result.getVessel());
System.out.println("Freight: " + result.getFreightTerms());
 
for (Container ctr : result.getContainers()) {
    System.out.printf("  %s | %s | %d kg%n",
        ctr.getNumber(), ctr.getType(), ctr.getWeightKg());
}

Need help integrating?

Our integration team can help you connect the KabyTech SWB API to CargoWise, SAP, Oracle TMS, or your custom freight management system. Express release workflows can be automated end-to-end.

Contact Support About Us

Sea Waybill API Reference

Introduction

Base URL

Authentication

Quick Start

POST /v1/swb/parse

Request Body (JSON)

Example Request (cURL)

Response (200 OK)

GET /v1/swb/{id}

Path Parameters

Query Parameters

POST /v1/swb/batch

Request Body

GET /v1/status

SWB 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?