Introduction

The KabyTech AWB Intelligence API lets you parse Air Waybill documents (PDF, image, or raw Cargo-IMP text) and receive structured JSON with all 29 FWB sections extracted. The API is built for Thai air freight operations and supports MAWB, HAWB, and FWB/FHL message formats.

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/awb/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 AWB parsed in under 5 minutes. This example uses the Python SDK to upload a PDF and receive structured data.

Python — Quick Start
from kabytech import KabyTechClient
 
# Initialize client with your API key
client = KabyTechClient(api_key="kby_live_a1b2c3d4...")
 
# Parse an AWB document (PDF, PNG, JPG, or raw text)
result = client.awb.parse(
    file="./awb-documents/TG-217-12345678.pdf",
    options={
        "include_confidence": True,
        "validate_iata": True,
        "output_format": "fwb16"
    }
)
 
# Access parsed AWB data
print(f"AWB Number: {result.awb_number}")
print(f"Origin: {result.origin} → Destination: {result.destination}")
print(f"Sections parsed: {result.sections_parsed}/29")
print(f"Confidence: {result.confidence}%")
print(f"Processing time: {result.processing_ms}ms")
 
# Access specific FWB sections
shipper = result.sections.shipper
print(f"Shipper: {shipper.name}, {shipper.address}")
 
consignee = result.sections.consignee
print(f"Consignee: {consignee.name}")
 
# Check for validation errors
if result.validation_errors:
    for err in result.validation_errors:
        print(f"Warning: {err.field} — {err.message}")

POST /awb/parse

Parse a single AWB document and return structured data. Accepts PDF, PNG, JPG, TIFF images, or raw IATA Cargo-IMP text. Returns all 29 FWB sections as structured JSON.

POST /v1/awb/parse

Parses an Air Waybill document and extracts all IATA Cargo-IMP FWB sections. Supports PDF uploads (base64 or multipart), image files, and raw FWB text. 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`, `tiff`, or `text`
`include_confidence` Optional	`boolean`	Include per-field confidence scores (default: `true`)
`validate_iata` Optional	`boolean`	Validate against IATA Cargo-IMP rules (default: `true`)
`output_format` Optional	`string`	Output format: `fwb16` (default), `fwb15`, or `flat`
`webhook_url` Optional	`string`	URL to receive a POST callback when processing completes

Example Request (cURL)

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

Response (200 OK)

JSON Response — 200 OK · 1.43s
{
  "id": "awb_8f3k2j1m9n4p",
  "awb_number": "217-12345678",
  "airline_code": "TG",
  "origin": "BKK",
  "destination": "NRT",
  "sections_parsed": 29,
  "confidence": 97.3,
  "processing_ms": 1430,
  "validation_errors": [],
  "sections": {
    "awb_identification": {
      "prefix": "217",
      "serial_number": "12345678",
      "check_digit": "8",
      "origin": "BKK",
      "destination": "NRT"
    },
    "shipper": {
      "name": "SIAM EXPORT CO LTD",
      "address": "123 SUKHUMVIT RD BANGKOK 10110",
      "account_number": "TG-SHP-0042"
    },
    "consignee": { /* ... */ },
    "routing": { /* ... */ },
    "charges": { /* ... */ },
    // ... all 29 sections
  },
  "created_at": "2026-03-26T09:15:32Z"
}

GET /awb/{id}

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

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

Path Parameters

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

cURL — Get AWB by ID
curl https://api.kabytech.co.th/v1/awb/awb_8f3k2j1m9n4p \
  -H "X-API-Key: kby_live_a1b2c3d4..."

POST /awb/batch

Submit multiple AWB 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 /awb/{id} endpoint for results.

POST /v1/awb/batch

Submits a batch of AWB documents for asynchronous processing. Returns immediately with a batch ID and individual document IDs. Each document is processed independently — one failure won't affect the others. Ideal for processing daily manifests or bulk historical digitization.

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)

Python — Batch Processing
from kabytech import KabyTechClient
import glob
 
client = KabyTechClient(api_key="kby_live_a1b2c3d4...")
 
# Collect all AWB PDFs from a directory
files = glob.glob("./daily-awbs/*.pdf")
 
# Submit batch (max 50 per request)
batch = client.awb.batch(
    files=files,
    webhook_url="https://your-app.com/webhooks/kabytech",
    priority="high"
)
 
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.awb_number}: {r.sections_parsed} sections, {r.confidence}%")

GET /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": 4283,
    "requests_limit": 10000,
    "batch_remaining": 5717
  }
}

FWB Sections Reference

The KabyTech API parses all 29 IATA Cargo-IMP FWB message sections. Below are the primary sections returned in the sections object of every parse response.

#	Section	Key	Description
1	AWB Identification	`awb_identification`	Prefix, serial number, check digit, origin/destination
2	Flight Bookings	`flight_bookings`	Carrier code, flight number, date, allotment code
3	Routing	`routing`	Airport codes, carrier designators per leg
4	Shipper	`shipper`	Name, address, account number, contact details
5	Consignee	`consignee`	Name, address, account number, contact details
6	Agent	`agent`	IATA code, account number, name, place
7	Special Service Request	`ssr`	SSR codes (e.g., SPH, DGR, PER, AVI)
8	Charge Declarations	`charges`	Weight/valuation charges, prepaid/collect indicators
…	All 29 sections are parsed — see the full FWB/16 specification in your dashboard.

Response Field Reference

Every API response includes these top-level fields alongside the sections object.

awb_number string The full AWB number in prefix-serial format (e.g., "217-12345678")

sections_parsed integer Number of FWB sections successfully extracted (max 29)

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 IATA validation warnings. Each object has field, message, and severity properties.

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

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, tiff, or text.
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	`awb_not_found`	No parsed result found for the given ID. Results expire after 90 days.
422	`parse_failed`	Document was read but no AWB data could be extracted. Verify document content.
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 — Quick Example
const { KabyTech } = require('@kabytech/sdk');
 
const client = new KabyTech({ apiKey: 'kby_live_a1b2c3d4...' });
 
const result = await client.awb.parse({
  file: './awb.pdf',
  validateIata: true
});
 
console.log(result.awbNumber); // "217-12345678"
console.log(result.sectionsParsed); // 29
console.log(result.sections.shipper.name); // "SIAM EXPORT CO LTD"

Need help integrating?

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

Contact Support About Us

KabyTech API Reference