API Contract Examples: Tendering & Dispatch for Autonomous Carriers

Hook: Stop wasting hours on brittle integrations — get a battle-tested API contract for autonomous carriers

Integrating autonomous carriers into your TMS or dispatch system in 2026 should not be a guessing game. Teams still face fragmented API designs, inconsistent ETA semantics, and brittle error flows that force repeated manual intervention. This guide gives you concrete, production-ready API contract examples — JSON Schemas, endpoint contracts, and operational guidelines — for tendering, accept/reject flows, dispatch, progressive ETAs, and robust exception handling when working with autonomous carriers.

Why this matters now (2026 context)

Late 2025 and early 2026 accelerated adoption of autonomous truck capacity inside enterprise TMS platforms, driven by high-demand TMS integrations and marketplace pilots. Early integrations showed the same problems: unclear tender payloads, ambiguous accept/reject semantics, and fragile ETA streams. The industry is moving toward contract-first, schema-validated APIs to reduce integration time and operational risk.

What you'll get in this guide

• Concrete JSON Schema examples for tendering, responses, dispatch, ETA events, and exceptions.
• Endpoint contract patterns (synchronous vs. asynchronous, idempotency, and retries).
• Best practices for error handling, security, versioning, and testing.
• Operational advice and a short case study mapping to real-world TMS-autonomy integration.

Core concepts and vocabulary

• Tender: A bid/request to carriers to move a load (includes pickup/delivery windows, constraints, and offer terms).
• Response: Carrier accept, reject, or counter-offer with ETA and constraints.
• Dispatch: Assignment of a specific vehicle and route to an accepted tender.
• ETA: Progressive arrival predictions with confidence and origin (onboard sensors, planner, TMS).
• Exception: Any unplanned event (breakdown, geofence violation, emergency stop) requiring a structured incident flow.

Design principles (brief)

1. Contract-first: publish JSON Schema + OpenAPI 3.1 for each resource.
2. Make status explicit: use enumerated lifecycle states and timestamps.
3. Support asynchronous flows: tendering often returns 202 and uses webhooks or pub/sub for updates.
4. Idempotency keys for write operations to avoid race conditions.
5. Provide confidence and source with every ETA update.

Tendering: JSON Schema and contract

Use a single canonical tender schema that your TMS and carrier integrations agree on. The tender contains constraints (size, hazmat), scheduling, and pricing terms. Keep the schema strict for required fields and permissive for extensions via an extensions map.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/tender.schema.json",
  "title": "Tender",
  "type": "object",
  "required": ["tenderId", "shipperId", "pickup", "delivery", "items"],
  "properties": {
    "tenderId": {"type": "string", "description": "UUID assigned by shipper"},
    "shipperId": {"type": "string"},
    "createdAt": {"type": "string", "format": "date-time"},
    "pickup": {
      "type": "object",
      "required": ["location"],
      "properties": {
        "location": {"type": "object", "required": ["lat","lon"], "properties": {"lat":{"type":"number"},"lon":{"type":"number"}}},
        "windowStart": {"type": "string", "format": "date-time"},
        "windowEnd": {"type": "string", "format": "date-time"}
      }
    },
    "delivery": {"type": "object", "required": ["location"], "properties": {"location": {"type":"object"}}},
    "items": {"type": "array", "minItems": 1, "items": {"type": "object", "properties": {"weightKg":{"type":"number"},"volumeM3":{"type":"number"},"hazmat": {"type":"boolean"}}}},
    "requiredAutonomyLevel": {"type": "string", "enum": ["L2","L3","L4"], "default": "L4"},
    "priceOffer": {"type":"object", "properties": {"currency":{"type":"string"},"amount":{"type":"number"}}},
    "specialInstructions": {"type":"string"},
    "callbackUrl": {"type":"string", "format":"uri"},
    "extensions": {"type":"object", "additionalProperties": true}
  }
}

Endpoint pattern

POST /api/v1/tenders

- Returns 201 with Location header when synchronous acceptance is possible, or 202 Accepted when carrier response will be asynchronous. - Provide Idempotency-Key header for POSTs.

Accept / Reject flow

Carrier responses must be explicit: accepted, rejected, countered, or pending. Include the earliest feasible ETA and constraints that cause rejection or partial acceptance.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/tender-response.schema.json",
  "title": "TenderResponse",
  "type": "object",
  "required": ["tenderId", "carrierId", "status"],
  "properties": {
    "tenderId": {"type": "string"},
    "carrierId": {"type": "string"},
    "status": {"type": "string", "enum": ["accepted","rejected","countered","pending"]},
    "reason": {"type": "string"},
    "eta": {"type": "string", "format": "date-time"},
    "etaConfidence": {"type": "number", "minimum": 0, "maximum": 1},
    "counterOffer": {"type": "object", "properties": {"price":{"type":"number"},"currency":{"type":"string"}}},
    "capacity": {"type": "object", "properties": {"availableTractors":{"type":"integer"}}}
  }
}

Recommended HTTP behaviour

• POST /tenders/{tenderId}/responses — idempotent write (Idempotency-Key).
• Return 409 Conflict if another accept already progressed to dispatch.
• Publish response events to a webhook or pub/sub topic configured on tender creation.

Dispatch contract (assignment)

When a tender is accepted and operationally assigned, issue a dispatch that includes the assigned vehicle, route plan, and mission metadata.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/dispatch.schema.json",
  "title": "Dispatch",
  "type": "object",
  "required": ["dispatchId","tenderId","vehicleId","assignedAt"],
  "properties": {
    "dispatchId": {"type": "string"},
    "tenderId": {"type": "string"},
    "vehicleId": {"type": "string"},
    "assignedAt": {"type": "string", "format": "date-time"},
    "routePlan": {"type": "array", "items": {"type": "object", "properties": {"seq":{"type":"integer"},"lat":{"type":"number"},"lon":{"type":"number"},"eta":{"type":"string","format":"date-time"}}}},
    "instructions": {"type": "string"},
    "contact": {"type": "object", "properties": {"systemContactId":{"type":"string"}}}
  }
}

ETA updates: schema and strategies

ETAs for autonomous vehicles are inherently probabilistic and should include a confidence value and an explicit source. Treat ETA updates as events — frequent, small updates that can be downsampled by consumers.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "EtaUpdate",
  "type": "object",
  "required": ["dispatchId","timestamp","eta","source"],
  "properties": {
    "dispatchId": {"type": "string"},
    "timestamp": {"type": "string","format":"date-time"},
    "eta": {"type": "string","format":"date-time"},
    "etaConfidence": {"type": "number","minimum":0,"maximum":1},
    "source": {"type": "string","enum":["onboard_sensors","planner","tms_estimate","third_party"]},
    "deltaSeconds": {"type": "integer"},
    "predictedPoints": {"type":"array","items":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"eta":{"type":"string","format":"date-time"}}}}
  }
}

Streaming vs. webhooks vs. polling

• Prefer pub/sub streams (Kafka/Google Pub/Sub/AMQP) for high-frequency ETA updates.
• Offer webhooks for lower frequency consumers, with exponential backoff and retry headers.
• Support conditional polling with ETag/Last-Event-ID headers.

Exception & incident handling

Build a structured incident schema that supports human handover, recommended next steps, and attachments (logs, photos). Include a severity score and estimated impact duration so orchestration can auto-escalate when needed.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Incident",
  "type": "object",
  "required": ["incidentId","dispatchId","type","occurredAt"],
  "properties": {
    "incidentId": {"type":"string"},
    "dispatchId": {"type":"string"},
    "type": {"type":"string","enum":["breakdown","geofence_violation","obstacle","emergency_stop","reroute","handover_required"]},
    "severity": {"type":"string","enum":["low","medium","high","critical"]},
    "description": {"type":"string"},
    "occurredAt": {"type":"string","format":"date-time"},
    "estimatedImpactMinutes": {"type":"integer"},
    "recommendedActions": {"type":"array","items":{"type":"string"}},
    "attachments": {"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":"string","format":"uri"}}}}
  }
}

Operational flows

• POST /incidents — immediate 202 with incidentId; publish to incident management and optionally open a human ticket.
• /incidents/{id}/acknowledge — for human operators to claim responsibility.
• Include escalation rules in your orchestration: critical incidents auto-escalate to operations within X minutes.

Error handling and standard error schema

Use a consistent error payload across endpoints so clients can implement deterministic retries and user-facing messages.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ErrorResponse",
  "type": "object",
  "required": ["code","message"],
  "properties": {
    "code": {"type":"string"},
    "message": {"type":"string"},
    "details": {"type":"object","additionalProperties": true},
    "retryAfterSeconds": {"type":"integer"}
  }
}

HTTP semantics cheat-sheet

• 200 OK — synchronous success
• 201 Created — resource created
• 202 Accepted — async processing started
• 400/422 — validation errors (return ErrorResponse with field details)
• 401/403 — auth/authorization failures
• 409 — conflict (race condition)
• 429 — rate limit (include retryAfterSeconds)

Security and privacy

For autonomous carriers you must design for strong authentication and auditable telemetry. Recommended stack:

• mTLS for service-to-service connections with short-lived certs.
• OAuth2 client credentials for TMS and carrier integrations, with fine-grained scopes (tender:create, tender:respond, dispatch:read, incident:write).
• JWTs with aud/iss claims and rotation policies.
• End-to-end encryption for attachments and telemetry, and retention rules for PII/GDPR compliance.

Versioning and contract evolution

Use semantic versioning and API version in headers rather than URLs where possible. Provide a clear deprecation policy and a compatibility matrix. Examples:

• Accept: application/vnd.company.tender.v1+json
• Deprecation: Sunsetting header with date and migration instructions.

Testing and CI: contract-first approach

Automate schema validation and contract tests in CI. Recommended tools: Ajv or similar for JSON Schema validation, OpenAPI 3.1 for endpoint docs, and Pact for consumer-driven contract tests.

1. Publish JSON Schemas to a central registry (internal or public).
2. Run consumer tests that assert the producer's mock satisfies the consumer's expectations.
3. Run provider tests against staged carrier endpoints or simulator sandboxes (hardware-in-loop when needed).

Real-world mapping: TMS tender → autonomous carrier flow

Example: A shipper creates a tender in the TMS (POST /tenders). The TMS returns 202 and registers a webhook. Carrier responds with accepted + eta via a response event. The TMS then issues dispatch to the carrier's fleet system. ETAs stream in via pub/sub; if an incident occurs the carrier posts an incident event and the TMS autoescalates. This mirrors 2024–2026 integrations where vendors connected TMS platforms to autonomous fleets and reduced manual handoffs.

"By contracting clearly at the API level, you reduce operations noise and speed up adoption — especially important for high-stakes autonomous fleet operations."

Advanced strategies & 2026 predictions

Expect the following trends through 2026:

• Standardized tender and ETA schemas across TMS and autonomy vendors as marketplaces mature.
• More confidence-aware ETAs: downstream systems will consume probabilistic arrival windows and use them for SLA computation.
• Regulatory logging requirements will force richer incident schemas and long-term telemetry retention APIs.
• Dynamic bidding markets where carriers programmatically counter tender prices via the contract-defined counterOffer object.

Actionable takeaways

• Start contract-first: publish JSON Schemas and OpenAPI specs before coding integrations.
• Design all state transitions explicitly (tender → accepted → dispatched → completed → archived).
• Emit structured ETA updates with a confidence field and source so consumers can filter and aggregate.
• Use idempotency keys and 409 semantics to avoid race conditions during accept/dispatch handoffs.
• Automate contract tests (Ajv, Pact) and maintain a simulator sandbox for carriers and TMS teams.

Appendix: Minimal working example — tender + response flow (HTTP sketch)

Example sequence:

1. Shipper: POST /api/v1/tenders {tender payload} with Idempotency-Key
2. API: 202 Accepted + Location: /api/v1/tenders/{tenderId}
3. Carrier: POST /api/v1/tenders/{tenderId}/responses {status: "accepted", eta: "2026-01-20T15:00:00Z"}
4. API: 200 OK — publishes event to webhook: /webhooks/tender-updates
5. When assigned: POST /api/v1/dispatches {dispatch payload}

Getting started — checklist for your next integration

• Publish/agree JSON Schemas with the carrier before engineering work begins.
• Provision sandbox credentials and a pub/sub topic or webhook URL.
• Implement idempotency, 202/409 semantics, and a clear error schema.
• Set up contract tests in CI and run against the carrier sandbox every PR.

Call to action

Want a ready-to-use OpenAPI + JSON Schema bundle for tendering and dispatch that you can import into your TMS or carrier integration? Download the reference spec and example simulator on our GitHub (link in the distribution) and run your first tender in a sandbox in under an hour. If you need a custom contract review, reach out for a 30-minute API design consultation tailored to autonomous carrier integrations.

Related Reading

• Mitigating AI Supply Chain Risk with Quantum-Resilient Scheduling
• How to Host Live Auctions Using Bluesky and Twitch: A Step-by-Step Guide for Collectors
• Jenny McCoy AMA Recap: The Most Actionable Fitness Tips From the Live Q&A
• Keep Streaming Without Interruptions: Scheduling Robot Vacuums Around Your Broadcasts
• Getting Kids Into Collecting: A Parent’s Starter Kit for Card Games and LEGO