API reference — Documentation

Authentication

All API requests require a Bearer token. Generate API keys in Settings → Developers. Keys are scoped to your workspace and inherit the creating user's permissions unless using a service account with explicit role assignment.

curl https://api.orbexdata.com/v1/shipments \
  -H "Authorization: Bearer orb_live_sk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Protect your keys

Never expose live keys in client-side code or public repositories. Rotate keys immediately if compromised.

Base URL and versioning

The current API version is v1. All endpoints are prefixed with https://api.orbexdata.com/v1. Breaking changes require a new major version with advance notice to registered developers.

Response conventions
HTTP code	Meaning
200	Success
201	Resource created
400	Invalid request body or parameters
401	Missing or invalid API key
404	Resource not found
429	Rate limit exceeded
500	Server error—retry with backoff

Shipments

Create and retrieve shipments with house bill references, legs, containers, and party assignments. Use external_id for idempotent upserts from your TMS.

curl -X POST https://api.orbexdata.com/v1/shipments \
  -H "Authorization: Bearer orb_live_sk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "tms-booking-88421",
    "mode": "ocean_fcl",
    "house_bill": "ORB-HBL-2026-00421",
    "container_numbers": ["MSCU1234567"],
    "carrier_scac": "MAEU",
    "origin_port": "CNSHA",
    "destination_port": "USLAX",
    "etd": "2026-02-15T00:00:00Z",
    "eta": "2026-03-22T00:00:00Z",
    "shipper": { "name": "Shanghai Exports Co.", "external_id": "shipper-102" },
    "consignee": { "name": "West Coast Retail LLC", "external_id": "consignee-445" }
  }'

{
  "id": "shp_7Kx9mN2pQ8vR",
  "external_id": "tms-booking-88421",
  "status": "in_transit",
  "house_bill": "ORB-HBL-2026-00421",
  "created_at": "2026-01-10T14:32:00Z",
  "url": "https://app.orbexdata.com/shipments/shp_7Kx9mN2pQ8vR"
}

Milestones

List milestones for a shipment or post manual milestones when carrier feeds are unavailable. Milestone codes use Orbex Data canonical names—see the milestones reference endpoint for the full catalog.

curl https://api.orbexdata.com/v1/shipments/shp_7Kx9mN2pQ8vR/milestones \
  -H "Authorization: Bearer orb_live_sk_xxxxxxxxxxxx"

curl -X POST https://api.orbexdata.com/v1/shipments/shp_7Kx9mN2pQ8vR/milestones \
  -H "Authorization: Bearer orb_live_sk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "delivered",
    "occurred_at": "2026-03-21T16:45:00Z",
    "source": "manual",
    "reason_code": "customer_confirmed",
    "location": "Los Angeles, CA"
  }'

Pagination and rate limits

List endpoints return paginated results with cursor-based navigation. Default page size is 50; maximum is 200. Standard plans allow 1,000 requests per minute per API key.

curl "https://api.orbexdata.com/v1/shipments?status=in_transit&limit=50" \
  -H "Authorization: Bearer orb_live_sk_xxxxxxxxxxxx"

# Follow next cursor from response
curl "https://api.orbexdata.com/v1/shipments?cursor=eyJpZCI6InNocF8..." \
  -H "Authorization: Bearer orb_live_sk_xxxxxxxxxxxx"

Prefer webhooks

For real-time updates, subscribe to webhooks instead of polling shipment endpoints.

Documents

Upload documents via multipart request or presigned URL flow for large files. Document metadata is available as JSON; binary content requires a separate download request.

curl -X POST https://api.orbexdata.com/v1/shipments/shp_7Kx9mN2pQ8vR/documents \
  -H "Authorization: Bearer orb_live_sk_xxxxxxxxxxxx" \
  -F "type=commercial_invoice" \
  -F "file=@/path/to/invoice.pdf"

PreviousERP & finance NextWebhooks