Introduction
The KabyTech Freight Manifest (MFT) Intelligence API lets you parse and compile freight manifests for Thai Customs National Single Window (NSW) filing. The API accepts PDF, image, or EDI formats and returns structured JSON with 50+ fields extracted, including a detailed per-shipment items[] array.
The API supports air manifests (FHL/FWB message formats), sea manifests (cargo declarations), and multimodal manifests. It auto-flags dangerous goods (DG) cargo per IMDG and ICAO classification codes, pre-validates HS codes against the Thai Customs tariff schedule, and provides direct EDI submission to the Thai Customs Department via NSW integration.
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
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/mft/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.
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 Freight Manifest parsed in under 5 minutes. This example uses the Python SDK to upload a manifest document and receive structured data with DG flagging and HS validation.
POST /v1/mft/parse
Parse a single Freight Manifest document and return structured data. Accepts PDF, PNG, JPG, TIFF images, or raw EDI messages (FHL, FWB, CUSCAR). Returns 50+ fields including a detailed items[] array with per-shipment breakdowns, DG auto-flagging per IMDG/ICAO codes, and HS pre-validation against the Thai Customs tariff.
Parses a Freight Manifest document and extracts all structured fields. Dangerous goods are automatically classified per IMDG (sea) and ICAO TI (air) codes. HS codes across all items are pre-validated against the Thai Customs tariff schedule. Average processing time is 2.0–4.5 seconds depending on item count.
Request Body (JSON)
| Parameter | Type | Description |
|---|---|---|
document Required | string | Base64-encoded document content (PDF, PNG, JPG, TIFF) or raw EDI text |
format Required | string | Document format: pdf, png, jpg, tiff, edi, or text |
manifest_type Optional | string | Hint: air, sea, or multimodal. Auto-detected if omitted. |
include_confidence Optional | boolean | Include per-field confidence scores (default: true) |
validate_hs Optional | boolean | Pre-validate HS codes against Thai Customs tariff (default: true) |
flag_dg Optional | boolean | Auto-flag dangerous goods per IMDG/ICAO codes (default: true) |
nsw_submit Optional | boolean | Automatically submit to Thai Customs NSW after parsing (default: false) |
webhook_url Optional | string | URL to receive a POST callback when processing completes |
Example Request (cURL)
Response (200 OK)
GET /v1/mft/{id}
Retrieve a previously parsed Freight Manifest 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 manifests. The NSW filing status is refreshed on each retrieval.
Returns the full parsed result for a specific Freight Manifest. The {id} is the unique identifier returned by the /mft/parse endpoint (e.g., mft_9p4q7k2m3f1n). Returns the same response schema as the parse endpoint with updated NSW filing status.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id Required | string | The unique manifest result ID (e.g., mft_9p4q7k2m3f1n) |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
include_raw Optional | boolean | Include raw OCR text or EDI source in the response (default: false) |
refresh_nsw Optional | boolean | Re-check NSW filing status from Thai Customs (default: false) |
items_offset Optional | integer | Pagination offset for items[] array (default: 0) |
items_limit Optional | integer | Max items to return per page (default: 100, max: 500) |
POST /v1/mft/batch
Submit multiple Freight Manifest documents for batch processing. The API accepts up to 50 documents per batch request and processes them asynchronously. Ideal for processing daily flight/vessel manifests or bulk pre-filing with Thai Customs NSW.
Submits a batch of manifest documents for asynchronous processing. Returns immediately with a batch ID and individual document IDs. Each manifest is processed independently — one failure won't affect the others. DG flagging and HS validation are applied to every item across all manifests.
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_hs Optional | boolean | Pre-validate HS codes across all items (default: true) |
flag_dg Optional | boolean | Auto-flag dangerous goods per IMDG/ICAO (default: true) |
nsw_submit Optional | boolean | Auto-submit each manifest to NSW after parsing (default: false) |
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.
Returns API health status, your account plan information, and current usage statistics. Also reports NSW gateway connectivity status for manifest filing.
MFT Sections Reference
The KabyTech API parses all standard Freight Manifest sections. Below are the primary sections returned in the response for every parsed manifest. Each section groups related fields for integration with customs filing systems, airline cargo systems (CHAMP, IBS), or freight management platforms.
| # | Section | Key | Description |
|---|---|---|---|
| 1 | Header | header | Manifest number, type (air/sea/multimodal), carrier name and code |
| 2 | Voyage/Flight | voyage | Flight number or voyage, ETD/ETA, aircraft or vessel type |
| 3 | Port Details | ports | Port of loading (UN/LOCODE), port of discharge, transshipment ports |
| 4 | Cargo Summary | summary | Total bills, total packages, total gross weight, total volume |
| 5 | Item-Level Details | items[] | Per-shipment breakdown: AWB/B/L, shipper, consignee, goods, weight, HS code |
| 6 | DG Flagging | dg_summary | Dangerous goods overview: IMDG classes (sea), ICAO TI codes (air), UN numbers, counts |
| 7 | HS Validation | hs_validation | Per-item HS code validation results against Thai Customs tariff schedule |
| 8 | NSW Filing Status | nsw | Thai Customs NSW submission status, reference number, filing timestamp, errors |
| 9 | Charges Summary | charges | Handling fees, customs processing charges, carrier surcharges |
The items[] array is the core of the manifest response. Each item represents a single shipment (AWB or B/L) within the manifest. Items include individual DG classification and HS validation results. Use items_offset and items_limit on the GET endpoint to paginate large manifests.
Response Field Reference
Every API response includes these top-level fields alongside the section objects. The items[] array contains per-shipment details with 50+ total fields across the response.
Top-Level Fields
air, sea, or multimodal
name and code (UN/LOCODE)
name and code (UN/LOCODE)
pending, submitted, accepted, rejected
field, message, severity.
Item-Level Fields (items[])
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, edi, or text. |
| 400 | invalid_edi | EDI message format is malformed or incomplete. Check FHL/FWB/CUSCAR syntax. |
| 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. |
| 403 | nsw_not_enabled | NSW direct submission requires Professional or Enterprise plan. |
| 404 | mft_not_found | No parsed result found for the given ID. Results expire after 90 days. |
| 422 | parse_failed | Document was read but no manifest data could be extracted. Verify document content. |
| 422 | hs_validation_failed | One or more HS codes could not be validated. Check validation_errors for details. |
| 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. |
| 502 | nsw_gateway_error | Thai Customs NSW gateway is unreachable. Manifest is parsed; NSW submission queued. |
| 503 | service_unavailable | API is temporarily unavailable for maintenance. Typically under 5 minutes. |
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. Manifest parsing counts as one request per document regardless of item count.
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
Need help integrating?
Our integration team can help you connect the KabyTech Manifest API to CHAMP Cargosystems, IBS iCargo, Thai Customs NSW, or your custom freight management platform.