OrcaTMS API Documentation

01Overview

The OrcaTMS Integration API connects a WMS or ERP to transport operations automatically — create jobs from orders, track status through delivery, and receive POD back in the source system.

• All requests and responses are JSON
• Authenticated with an API key (no user login) — bound to a tenant by the key itself
• Job creation is idempotent via external_ref — safe to retry with no duplicates

02Base URL

Examples below use {BASE} for the base URL above

03Authentication

Send the API key with every request via a header (either form):

X-API-Key: tmsk_xxxxxxxx_yyyyyyyyyyyyyyyy
# or
Authorization: Bearer tmsk_xxxxxxxx_yyyyyyyyyyyyyyyy

Creating an API key

Admins create keys at Dashboard → Settings → System Usage → “External API” tab

• Pick a scope for the key
• The full key is shown only once at creation — store it safely (only a hash is kept)
• Revoke a key at any time

04Scopes

05Rate limit

• Read (public.read): 120 req/min per key
• Write (jobs.write): 120 req/min per key
• GPS ingest: 600 req/min per key
• Over quota → 429 with Retry-After, X-RateLimit-Remaining

06Response format

// success
{ "status": "success", "data": { ... } }
// error
{ "status": "error", "message": "..." }

07Create a job

Create a new job from a WMS order · idempotent via external_ref

Request body

{
  "external_ref": "WMS-ORD-100245",
  "customer": { "name": "Acme Co., Ltd.", "phone": "0891234567" },
  "pickup": { "name": "Warehouse A, Laem Chabang", "latitude": 13.0827, "longitude": 100.8836 },
  "deliveries": [
    { "name": "Central Chonburi", "latitude": 13.3611, "longitude": 100.9847 },
    { "name": "Lotus Rayong", "latitude": 12.6807, "longitude": 101.2812 }
  ],
  "dest_province": "Chonburi",
  "booking_no": "BK-778", "requested_date": "2026-07-20"
}

Response 201

{ "status": "success", "data": { "id": 251, "job_number": "J26070001", "status": "confirmed" } }

08List / search jobs

Fetch jobs, filter via query string e.g. ?status=on_trip, ?external_ref=WMS-ORD-100245, ?page=1

09Job detail / status

Returns job details with current status, pickup/drops, assigned driver/vehicle and progress.

10Proof of delivery (POD)

Fetch delivery evidence — signatures, photos, SHA-256, timestamps and per-drop recipients (multi-drop).

11Cancel a job

Cancel a job that is not yet closed · a completed job returns 409

{ "reason": "Customer cancelled the order" }

12Vehicles & location

Your organization’s vehicles and each vehicle’s latest position (lat/long, speed, updated time).

13Push GPS positions

Ingest positions from an external GPS provider (e.g. Cartrack) into tracking — tenant-bound by the key, high-throughput.

14Job statuses

15Webhooks — push updates back to WMS

Configure a webhook URL at Dashboard → Settings → Webhooks · the system sends POST to your URL when a job status changes

POST <your-webhook-url>
X-TMS-Signature: sha256=...
{
  "event": "job.status_changed",
  "job_number": "J26070001",
  "external_ref": "WMS-ORD-100245",
  "status": "completed",
  "occurred_at": "2026-07-20T15:22:01Z"
}