API Documentation — CMR Consignment Note

CMR Consignment Note API Reference

Parse CMR road transport documents with Thai-script vehicle registration OCR, GMS/CBTA compliance validation, and ASEAN border checkpoint verification across 30+ fields.

Introduction

The CMR Consignment Note API extracts structured data from CMR (Convention relative au contrat de transport international de Marchandises par Route) road consignment notes using advanced OCR and machine learning. Specifically designed for the Greater Mekong Subregion (GMS) and Cross-Border Transport Agreement (CBTA) compliance, the API handles the unique requirements of ASEAN road freight documentation.

The API features specialized Thai-script OCR for vehicle registration parsing, enabling accurate extraction of Thai license plates written as ทะเบียนรถ in both standard and handwritten formats. It supports all major GMS road corridors: Thailand-Laos (Nong Khai/Mukdahan), Thailand-Cambodia (Aranyaprathet/Poipet), Thailand-Myanmar (Mae Sot/Myawaddy), and Thailand-Vietnam (via Laos transit).

Key capabilities include CBTA permit number verification, ASEAN border checkpoint validation against the official GMS checkpoint database, Thai-script vehicle and trailer registration parsing, driver license extraction, and automated GMS route code identification. The API returns 30+ structured fields with per-field confidence scores.

Supported file formats: PDF, JPEG, PNG, TIFF (max 20 MB per file). Average processing time: 0.9-1.8 seconds. Optimized for mobile-captured images of CMR notes taken at border checkpoints.

Base URL https://api.kabytech.com

Authentication

All API requests must include a valid API key in the Authorization header using the Bearer token scheme. API keys are scoped to your organization and can be created, rotated, and revoked from the dashboard.

Authorization: Bearer YOUR_API_KEY

Obtain your API key from dashboard.kabytech.com → Settings → API Keys. Each key can be assigned granular permissions (read, write, batch) and rate limit tiers. We recommend creating separate keys for development and production environments.

Security best practices:

Quick Start

Parse a CMR road consignment note in seconds. Upload a document image or PDF and receive structured JSON with 30+ extracted fields, including Thai-script vehicle registration and CBTA permit data.

curl -X POST https://api.kabytech.com/v1/cmr/parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/cmr-note.pdf" \
  -F "language=th" \
  -F "validate_checkpoint=true"

The API automatically detects Thai-script text for vehicle registrations and applies ASEAN checkpoint validation. For documents photographed at border checkpoints, the image enhancement pipeline corrects for skew, lighting, and low resolution before OCR processing.

Example response for a Bangkok-Nong Khai-Vientiane agricultural products shipment:

{
  "id": "job_cmr_4a7c1d9e2f5b",
  "status": "completed",
  "document_type": "cmr",
  "data": {
    "cmr_number": "CMRKBT2026012345",
    "date_of_issue": "2026-03-20",
    "sender": {
      "name": "Chiang Mai Organic Farm Cooperative",
      "address": "234 Huay Kaew Road, Muang, Chiang Mai 50200, Thailand",
      "country": "TH",
      "tax_id": "0105563012345"
    },
    "carrier": {
      "name": "GMS Express Transport Co., Ltd.",
      "address": "89 Mittraphap Road, Muang, Nong Khai 43000, Thailand",
      "country": "TH",
      "transport_license": "TH-DLT-2026-04567"
    },
    "consignee": {
      "name": "Vientiane Fresh Market Import Co., Ltd.",
      "address": "45 Lan Xang Avenue, Chanthabouly District, Vientiane, Laos",
      "country": "LA"
    },
    "place_of_loading": "Chiang Mai Cold Storage Facility, Thailand",
    "place_of_delivery": "Vientiane Morning Market Distribution Center, Laos",
    "date_of_loading": "2026-03-20T06:00:00+07:00",
    "goods_description": "Fresh organic longan (600 kg), dried longan (400 kg), organic jasmine rice (2000 kg)",
    "hs_codes": ["0810.90", "0813.40", "1006.30"],
    "gross_weight": "3200 kg",
    "number_of_packages": 180,
    "packaging_type": "Corrugated cartons (longan), woven polypropylene bags (rice)",
    "volume_m3": 14.5,
    "vehicle_registration": "กท 5678 กรุงเทพมหานคร",
    "vehicle_registration_latin": "KT 5678 Bangkok",
    "trailer_registration": "ผส 1234 นนทบุรี",
    "trailer_registration_latin": "PS 1234 Nonthaburi",
    "vehicle_type": "refrigerated_truck",
    "driver_name": "Somchai Prasert",
    "driver_license": "TH-51012345678",
    "driver_nationality": "TH",
    "border_checkpoint": "Nong Khai / Thanaleng",
    "border_checkpoint_code": "GMS-NKI-TNL",
    "customs_reference": "TH-LA-2026-007890",
    "cbta_permit_number": "CBTA-GMS-2026-01234",
    "cbta_permit_valid_until": "2026-12-31",
    "gms_route_code": "R1",
    "gms_corridor": "North-South Economic Corridor",
    "phytosanitary_certificate": "TH-PHYTO-2026-003456",
    "temperature_requirement": "2-8°C (longan), ambient (rice)",
    "insurance_reference": "INS-GMS-2026-005678",
    "special_instructions": "Maintain cold chain. Inspect at border for phytosanitary compliance."
  },
  "confidence": 0.95,
  "field_confidences": {
    "cmr_number": 0.99,
    "sender.name": 0.97,
    "vehicle_registration": 0.94,
    "cbta_permit_number": 0.96,
    "goods_description": 0.93,
    "border_checkpoint": 0.98
  },
  "processing_time_ms": 1340,
  "pages_processed": 2,
  "thai_script_detected": true,
  "checkpoint_validated": true
}

POST /v1/cmr/parse

POST /v1/cmr/parse

Upload a CMR road consignment note for parsing. The API accepts PDF, JPEG, PNG, and TIFF files up to 20 MB. Optimized for both clean scans and mobile-captured photos taken at ASEAN border checkpoints — the image pipeline automatically corrects for skew, uneven lighting, and partial occlusion.

Thai-script OCR is enabled by default. The parser identifies Thai vehicle registration patterns (ทะเบียนรถ) and transliterates them to Latin characters in a parallel field for integration with international logistics systems.

Request Parameters

filefileRequired. The CMR document file to parse. Accepted formats: PDF, JPEG, PNG, TIFF. Maximum size: 20 MB.
languagestringPrimary language hint for OCR. Values: th (Thai), en (English), lo (Lao), km (Khmer), my (Myanmar). Default: auto.
webhook_urlstringURL to receive a POST callback when parsing completes. Must be HTTPS.
prioritystringProcessing priority: normal or high. High priority costs 2x credits. Default: normal.
validate_checkpointbooleanValidate the border checkpoint name against the official GMS checkpoint database. Default: true.
validate_cbtabooleanVerify the CBTA permit number format and expiration against known patterns. Default: true.
include_raw_ocrbooleanInclude raw OCR text in the response for debugging. Default: false.
transliterate_thaibooleanInclude Latin transliteration of Thai-script fields (vehicle_registration_latin, etc.). Default: true.
enhance_imagebooleanApply image enhancement for low-quality photos (skew correction, brightness normalization). Default: true.

Response Fields

idstringUnique job identifier for result retrieval.
statusstringJob status: completed, processing, or failed.
document_typestringAlways cmr for road consignment notes.
dataobjectExtracted fields object. See Field Reference for full schema.
confidencenumberOverall extraction confidence (0.0 to 1.0).
field_confidencesobjectPer-field confidence scores.
processing_time_msintegerProcessing time in milliseconds.
thai_script_detectedbooleanWhether Thai script was detected and processed.
checkpoint_validatedbooleanWhether the border checkpoint was validated against the GMS database.

GET /v1/cmr/{id}

GET /v1/cmr/{id}

Retrieve the parsed results for a previously submitted CMR consignment note by its job ID. Use this endpoint when the initial parse returned a "processing" status or to re-fetch results at any time within the retention period.

Results are retained for 30 days after parsing. After this period, the job ID expires and a 404 error is returned.

Path Parameters

idstringRequired. The job ID returned from the parse endpoint (e.g., job_cmr_4a7c1d9e2f5b).

Query Parameters

include_rawbooleanInclude raw OCR text alongside structured data. Default: false.
fieldsstringComma-separated field list to return. Returns all fields if omitted. Example: cmr_number,sender,vehicle_registration,border_checkpoint.
curl https://api.kabytech.com/v1/cmr/job_cmr_4a7c1d9e2f5b \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G -d "fields=cmr_number,sender,carrier,consignee,vehicle_registration,border_checkpoint,cbta_permit_number"
{
  "id": "job_cmr_4a7c1d9e2f5b",
  "status": "completed",
  "document_type": "cmr",
  "data": {
    "cmr_number": "CMRKBT2026012345",
    "sender": {
      "name": "Chiang Mai Organic Farm Cooperative",
      "address": "234 Huay Kaew Road, Muang, Chiang Mai 50200, Thailand",
      "country": "TH"
    },
    "carrier": {
      "name": "GMS Express Transport Co., Ltd.",
      "address": "89 Mittraphap Road, Muang, Nong Khai 43000, Thailand",
      "country": "TH"
    },
    "consignee": {
      "name": "Vientiane Fresh Market Import Co., Ltd.",
      "address": "45 Lan Xang Avenue, Chanthabouly District, Vientiane, Laos",
      "country": "LA"
    },
    "vehicle_registration": "กท 5678 กรุงเทพมหานคร",
    "vehicle_registration_latin": "KT 5678 Bangkok",
    "border_checkpoint": "Nong Khai / Thanaleng",
    "cbta_permit_number": "CBTA-GMS-2026-01234"
  },
  "confidence": 0.95,
  "processing_time_ms": 1340
}

POST /v1/cmr/batch

POST /v1/cmr/batch

Submit up to 50 CMR consignment notes for batch processing. Ideal for processing daily border crossing manifests, fleet compliance audits, or digitizing historical CBTA documentation. Each file is processed independently and results are aggregated.

Batch jobs always run asynchronously. Use the returned batch_id to poll for results or provide a webhook_url to receive a callback when all documents are complete.

Request Parameters

files[]file[]Required. Array of CMR document files. Maximum 50 files, 20 MB each. Total batch size limit: 500 MB.
languagestringDefault language hint for all files. Default: auto.
webhook_urlstringURL for batch completion callback (HTTPS required).
validate_checkpointbooleanValidate border checkpoints for all files. Default: true.
parallelintegerConcurrent processing workers (1-10). Higher values are faster but cost more. Default: 3.
curl -X POST https://api.kabytech.com/v1/cmr/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files[]=@cmr-bangkok-vientiane.pdf" \
  -F "files[]=@cmr-aranyaprathet-poipet.pdf" \
  -F "files[]=@cmr-mae-sot-myawaddy.jpg" \
  -F "language=th" \
  -F "validate_checkpoint=true" \
  -F "webhook_url=https://your-server.com/webhooks/cmr-batch"
{
  "batch_id": "batch_cmr_3n8k5w2j",
  "status": "processing",
  "total_files": 3,
  "completed": 0,
  "failed": 0,
  "estimated_completion_seconds": 8,
  "results_url": "https://api.kabytech.com/v1/cmr/batch/batch_cmr_3n8k5w2j"
}

GET /v1/status

GET /v1/status

Health check endpoint for the CMR parsing service. Returns current operational status, API version, and queue depth. This endpoint does not require authentication and can be used for monitoring and uptime checks.

curl https://api.kabytech.com/v1/status
{
  "service": "cmr-parser",
  "status": "operational",
  "version": "2.4.1",
  "queue_depth": 3,
  "avg_processing_time_ms": 1280,
  "supported_corridors": ["TH-LA", "TH-KH", "TH-MM", "TH-VN"],
  "thai_ocr_engine": "active",
  "cbta_database_updated": "2026-03-15T00:00:00Z",
  "checkpoint_database_updated": "2026-03-20T00:00:00Z",
  "uptime_percent": 99.98,
  "last_incident": "2026-01-22T08:15:00Z"
}

CMR Sections Reference

CMR consignment notes follow a standardized layout defined by the CMR Convention, adapted for ASEAN/GMS cross-border transport. The API maps extracted data to these logical sections corresponding to the standard CMR box numbers. Each section groups related fields for easy access.

Header Section

Core identification fields from the top of the CMR note.

cmr_numberstringUnique CMR consignment note number.
date_of_issuestringDate the CMR was issued (ISO 8601).
place_of_issuestringCity/location where the CMR was issued.
copies_countintegerNumber of CMR copies issued (typically 3: sender, carrier, consignee).

Parties Section (Sender / Carrier / Consignee)

The three parties to the CMR contract. Corresponds to CMR Boxes 1 (Sender), 2 (Consignee), and 16 (Carrier).

senderobjectSender (Box 1): name, address, country, tax_id.
consigneeobjectConsignee (Box 2): name, address, country.
carrierobjectCarrier (Box 16): name, address, country, transport_license.
successive_carriersobject[]Additional carriers for multi-leg journeys (Box 17), each with name and segment.

Vehicle Details Section

Vehicle and driver information from Box 18. The API's Thai-script OCR engine parses Thai vehicle registrations (ทะเบียนรถ) and provides both original Thai and Latin transliterations.

vehicle_registrationstringVehicle registration in original script (Thai: กท 5678 กรุงเทพฯ).
vehicle_registration_latinstringLatin transliteration of vehicle registration.
trailer_registrationstringTrailer registration in original script, if applicable.
trailer_registration_latinstringLatin transliteration of trailer registration.
vehicle_typestringVehicle type: truck, refrigerated_truck, tanker, flatbed, container_truck.
driver_namestringDriver's full name.
driver_licensestringDriver's license number.
driver_nationalitystringDriver's nationality (ISO 3166-1 alpha-2).

Route Section

Loading/delivery locations and border crossing details. ASEAN checkpoint names are validated against the official GMS database when validate_checkpoint is enabled.

place_of_loadingstringPlace and country of loading (Box 4).
place_of_deliverystringPlace and country of delivery (Box 3).
date_of_loadingstringDate and time of loading (ISO 8601).
border_checkpointstringBorder checkpoint pair (e.g., "Nong Khai / Thanaleng").
border_checkpoint_codestringGMS checkpoint code (e.g., GMS-NKI-TNL).
gms_route_codestringGMS Economic Corridor route code: R1 (North-South), R2 (East-West), R3 (Southern), etc.
gms_corridorstringFull corridor name (e.g., "North-South Economic Corridor").

Goods Section

Cargo details from CMR Boxes 6-12.

goods_descriptionstringFull description of goods (Box 6).
hs_codesstring[]Harmonized System commodity codes extracted from the description.
gross_weightstringTotal gross weight in kg (Box 11).
number_of_packagesintegerTotal number of packages (Box 7-8).
packaging_typestringType of packaging (Box 7).
volume_m3numberVolume in cubic meters (Box 12).
dangerous_goods_classstringADR/UN dangerous goods class, if applicable.
temperature_requirementstringTemperature control requirement for perishable goods.
special_instructionsstringSpecial handling or delivery instructions (Box 13).

Customs and Border Section

CBTA compliance data, customs references, and border clearance documentation specific to GMS cross-border transport.

customs_referencestringCustoms declaration reference number.
cbta_permit_numberstringGMS Cross-Border Transport Agreement permit number.
cbta_permit_valid_untilstringCBTA permit expiration date (ISO 8601).
phytosanitary_certificatestringPhytosanitary/health certificate number for agricultural goods.
insurance_referencestringCargo insurance policy reference.
transit_customs_officesstring[]Customs offices in transit countries where clearance is required.

Response Field Reference

Complete reference of all 30+ fields extracted from CMR road consignment notes. Each field includes a confidence score (0.0 to 1.0) in the field_confidences object. Fields not present on the source document are returned as null.

cmr_numberstringUnique CMR consignment note number.
date_of_issuestringCMR issue date (ISO 8601).
place_of_issuestringLocation where the CMR was issued.
senderobjectSender with name, address, country, tax_id.
carrierobjectCarrier with name, address, country, transport_license.
consigneeobjectConsignee with name, address, country.
successive_carriersobject[]Additional carriers for multi-leg journeys.
place_of_loadingstringLoading location and country.
place_of_deliverystringDelivery location and country.
date_of_loadingstringLoading date and time (ISO 8601).
goods_descriptionstringFull goods description.
hs_codesstring[]Harmonized System codes.
gross_weightstringTotal gross weight in kg.
number_of_packagesintegerTotal package count.
packaging_typestringType of packaging used.
volume_m3numberCargo volume in cubic meters.
dangerous_goods_classstringADR/UN dangerous goods class.
temperature_requirementstringTemperature control requirement.
special_instructionsstringSpecial handling instructions.
vehicle_registrationstringVehicle registration in original script (Thai/Khmer/Myanmar).
vehicle_registration_latinstringLatin transliteration of vehicle registration.
trailer_registrationstringTrailer registration in original script.
trailer_registration_latinstringLatin transliteration of trailer registration.
vehicle_typestringVehicle type classification.
driver_namestringDriver's full name.
driver_licensestringDriver's license number.
driver_nationalitystringDriver nationality (ISO 3166-1 alpha-2).
border_checkpointstringBorder checkpoint pair name.
border_checkpoint_codestringGMS checkpoint code.
gms_route_codestringGMS Economic Corridor route code.
gms_corridorstringFull GMS corridor name.
customs_referencestringCustoms declaration reference.
cbta_permit_numberstringGMS/CBTA permit number.
cbta_permit_valid_untilstringCBTA permit expiration date.
phytosanitary_certificatestringPhytosanitary certificate number.
insurance_referencestringCargo insurance reference.
transit_customs_officesstring[]Customs offices in transit countries.
freight_chargesobjectFreight cost with currency, amount, terms.
payment_methodstringPayment terms: prepaid, collect, third_party.

Error Codes

The API returns standard HTTP status codes along with a JSON error body containing a machine-readable code and a human-readable message. Use the code field for programmatic error handling.

400INVALID_FILE_TYPEThe uploaded file is not a supported format (PDF, JPEG, PNG, TIFF).
400FILE_TOO_LARGEFile exceeds the 20 MB size limit.
400INVALID_CHECKPOINTThe specified checkpoint is not recognized in the GMS database.
401UNAUTHORIZEDMissing or invalid API key in the Authorization header.
403FORBIDDENAPI key does not have permission for this operation.
404JOB_NOT_FOUNDThe specified job ID does not exist or has expired (30-day retention).
409DUPLICATE_SUBMISSIONThis exact file was already submitted within the last 5 minutes.
422UNPROCESSABLE_DOCUMENTThe document could not be parsed. It may be corrupted, blank, or not a CMR note.
422LOW_QUALITY_IMAGEImage resolution is too low for reliable OCR (minimum 150 DPI recommended).
422CBTA_PERMIT_INVALIDThe CBTA permit number format is invalid or the permit has expired.
429RATE_LIMITEDRequest rate exceeds your plan's limits. Retry after the Retry-After header interval.
500INTERNAL_ERRORAn unexpected server error occurred. Contact support if this persists.
503SERVICE_UNAVAILABLEThe CMR parser is temporarily unavailable due to maintenance or high load.

Rate Limits

Rate limits are applied per API key and vary by plan tier. Limits are enforced using a sliding window algorithm. The API returns rate limit headers with every response:

Free10 req/min100 documents/month. Single file processing only (no batch). Community support.
Starter60 req/min2,000 documents/month. Batch processing up to 10 files. Email support.
Professional300 req/min20,000 documents/month. Batch up to 50 files. Priority support with 4-hour SLA.
EnterpriseCustomUnlimited documents. Dedicated infrastructure. 24/7 support with 1-hour SLA. Custom SLA.

Official SDKs

KabyTech provides official SDKs for popular languages to simplify integration with the CMR API. All SDKs handle authentication, retries, file uploads, and response parsing automatically.

# Python
pip install kabytech
from kabytech import KabyTech
client = KabyTech(api_key="YOUR_API_KEY")
result = client.cmr.parse("cmr-note.pdf", language="th", validate_checkpoint=True)
print(result.data.cmr_number)
print(result.data.vehicle_registration)  # Thai script
print(result.data.vehicle_registration_latin)  # Latin transliteration
print(result.data.cbta_permit_number)
// Node.js
npm install @kabytech/sdk
const { KabyTech } = require("@kabytech/sdk");
const client = new KabyTech({ apiKey: "YOUR_API_KEY" });
const result = await client.cmr.parse("cmr-note.pdf", {
  language: "th",
  validateCheckpoint: true,
  validateCbta: true,
  transliterateThai: true
});
console.log(result.data.cmrNumber);
console.log(result.data.vehicleRegistration);
console.log(result.data.borderCheckpoint);
console.log(result.data.cbtaPermitNumber);

Additional SDKs available: Go (go get github.com/kabytech/kabytech-go), Java (Maven Central: com.kabytech:kabytech-sdk), PHP (composer require kabytech/sdk). Full SDK documentation is available at docs.kabytech.com/sdks.

Ready to integrate?

Start your free 30-day trial with 50 API calls. No credit card required.

Start Free TrialView Pricing