API docs by Redocly

TDS OpenAPI binding (0.10.0)

Download OpenAPI specification:

URL: https://github.com/kovirlabs/tds-openapi License: Apache-2.0

Machine-readable binding of the Transactional Data Specification (TCRP Report 210, 2020).

Request/response operations for booking demand-response trips between a requester (broker, coordinator tool or provider) and a provider: the core profile (SPEC.md §6–§8) and the transfer profile's tenders and holds (SPEC.md §10, operations marked x-profile: transfer). Events are delivered by signed webhook; see spec/asyncapi.yaml. Every mutating call requires an Idempotency-Key header.

Trips

Request, confirm, modify, cancel and read trips.

Request a trip

Ask a provider to serve a trip. A provider that decides synchronously returns 201 with the trip OFFERED (or CONFIRMED, skipping the offer step). One that decides later returns 202 with the trip REQUESTED and reports the decision by event. Both are conformant. A synchronous refusal is a 422 whose code says why; the trip is then REJECTED.

Authorizations:
oauth2
header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Client-generated key (e.g. a UUID) making the request safe to retry. A repeat with the same key and body returns the original response; the same key with a different body is rejected with IDEMPOTENCY_KEY_REUSED. Keys are scoped to the authenticated requester and kept for at least 24 hours.

Request Body schema: application/json
required
trip_id
required
string

Identifier assigned by the requester; unique per requester_id. Same as trip.trip_id.

requester_id
required
string

Identifier of the party requesting the trip. Must match the authenticated client.

provider_id
required
string

Identifier of the provider asked to serve the trip.

required
object (rider)

The rider, by reference.

object (party)

Others travelling with the rider.

required
Array of Leg (object) or Leg (object) (Leg) = 1 items

The requested leg. Core requires exactly one.

object (fare-funding)

Fare and funding details for settlement.

notes_to_driver
string <= 500 characters

Free-text operational notes. Must not contain health or diagnosis information.

Responses

Response Schema: application/json
trip_id
required
string

Identifier assigned by the requester; unique per requester_id.

provider_trip_id
string

Identifier assigned by the provider once it accepts the trip.

requester_id
required
string

Identifier of the party requesting the trip.

provider_id
required
string

Identifier of the party asked to serve the trip.

status
required
string (trip-status)
Enum: "REQUESTED" "OFFERED" "CONFIRMED" "SCHEDULED" "IN_PROGRESS" "COMPLETED" "FAILED" "REJECTED" "EXPIRED" "CANCELLED" "NO_SHOW"

Current lifecycle state.

required
object (rider)

The rider, by reference.

object (party)

Others travelling with the rider.

required
Array of Leg (object) or Leg (object) (Leg) = 1 items

The trip's legs. Core requires exactly one.

object (fare-funding)

Fare and funding details for settlement.

notes_to_driver
string <= 500 characters

Free-text operational notes, e.g. "call on arrival". Must not contain health or diagnosis information.

offer_expires_at
string <date-time>

While the trip is OFFERED: the offer lapses (status EXPIRED) unless the requester confirms by then. Absent when offers don't expire.

object (cancellation)

Present when status is CANCELLED.

created_at
required
string <date-time>

When the trip was created, RFC 3339 with offset.

updated_at
required
string <date-time>

When the trip last changed, RFC 3339 with offset.

Response Schema: application/json
trip_id
required
string

Identifier assigned by the requester; unique per requester_id.

provider_trip_id
string

Identifier assigned by the provider once it accepts the trip.

requester_id
required
string

Identifier of the party requesting the trip.

provider_id
required
string

Identifier of the party asked to serve the trip.

status
required
string (trip-status)
Enum: "REQUESTED" "OFFERED" "CONFIRMED" "SCHEDULED" "IN_PROGRESS" "COMPLETED" "FAILED" "REJECTED" "EXPIRED" "CANCELLED" "NO_SHOW"

Current lifecycle state.

required
object (rider)

The rider, by reference.

object (party)

Others travelling with the rider.

required
Array of Leg (object) or Leg (object) (Leg) = 1 items

The trip's legs. Core requires exactly one.

object (fare-funding)

Fare and funding details for settlement.

notes_to_driver
string <= 500 characters

Free-text operational notes, e.g. "call on arrival". Must not contain health or diagnosis information.

offer_expires_at
string <date-time>

While the trip is OFFERED: the offer lapses (status EXPIRED) unless the requester confirms by then. Absent when offers don't expire.

object (cancellation)

Present when status is CANCELLED.

created_at
required
string <date-time>

When the trip was created, RFC 3339 with offset.

updated_at
required
string <date-time>

When the trip last changed, RFC 3339 with offset.

Request samples

Content type
application/json
Example
{
  • "trip_id": "tr-20261103-0001",
  • "requester_id": "throughride-demo",
  • "provider_id": "aaata-a-ride",
  • "rider_ref": {
    • "rider_ref_id": "r-7f3a",
    • "display_name": "Dana K.",
    • "language": "en",
    • "eligibility": [
      ]
    },
  • "party": {
    • "companions": 0,
    • "attendants": 1,
    • "service_animals": 0
    },
  • "legs": [
    • {
      }
    ],
  • "fare_funding": {
    • "fare": {
      },
    • "funding_source": "SPONSOR",
    • "sponsor_ref": "jfs-washtenaw"
    },
  • "notes_to_driver": "Call on arrival."
}

Response samples

Content type
application/json
Example
{
  • "trip_id": "tr-20261103-0001",
  • "provider_trip_id": "AR-558812",
  • "requester_id": "throughride-demo",
  • "provider_id": "aaata-a-ride",
  • "status": "OFFERED",
  • "rider_ref": {
    • "rider_ref_id": "r-7f3a",
    • "display_name": "Dana K.",
    • "language": "en",
    • "eligibility": [
      ]
    },
  • "party": {
    • "companions": 0,
    • "attendants": 1,
    • "service_animals": 0
    },
  • "legs": [
    • {
      }
    ],
  • "fare_funding": {
    • "fare": {
      },
    • "funding_source": "SPONSOR",
    • "sponsor_ref": "jfs-washtenaw"
    },
  • "notes_to_driver": "Call on arrival.",
  • "created_at": "2026-10-30T14:02:11-04:00",
  • "updated_at": "2026-10-30T14:02:12-04:00"
}

Get a trip

Current state of a trip, including scheduled times and vehicle once known.

Authorizations:
oauth2
path Parameters
trip_id
required
string

The requester-assigned trip_id. Scoped to the authenticated requester.

Responses

Response Schema: application/json
trip_id
required
string

Identifier assigned by the requester; unique per requester_id.

provider_trip_id
string

Identifier assigned by the provider once it accepts the trip.

requester_id
required
string

Identifier of the party requesting the trip.

provider_id
required
string

Identifier of the party asked to serve the trip.

status
required
string (trip-status)
Enum: "REQUESTED" "OFFERED" "CONFIRMED" "SCHEDULED" "IN_PROGRESS" "COMPLETED" "FAILED" "REJECTED" "EXPIRED" "CANCELLED" "NO_SHOW"

Current lifecycle state.

required
object (rider)

The rider, by reference.

object (party)

Others travelling with the rider.

required
Array of Leg (object) or Leg (object) (Leg) = 1 items

The trip's legs. Core requires exactly one.

object (fare-funding)

Fare and funding details for settlement.

notes_to_driver
string <= 500 characters

Free-text operational notes, e.g. "call on arrival". Must not contain health or diagnosis information.

offer_expires_at
string <date-time>

While the trip is OFFERED: the offer lapses (status EXPIRED) unless the requester confirms by then. Absent when offers don't expire.

object (cancellation)

Present when status is CANCELLED.

created_at
required
string <date-time>

When the trip was created, RFC 3339 with offset.

updated_at
required
string <date-time>

When the trip last changed, RFC 3339 with offset.

Response samples

Content type
application/json
{
  • "trip_id": "tr-20261103-0001",
  • "provider_trip_id": "AR-558812",
  • "requester_id": "throughride-demo",
  • "provider_id": "aaata-a-ride",
  • "status": "SCHEDULED",
  • "rider_ref": {
    • "rider_ref_id": "r-7f3a",
    • "display_name": "Dana K.",
    • "language": "en",
    • "eligibility": [
      ]
    },
  • "party": {
    • "companions": 0,
    • "attendants": 1,
    • "service_animals": 0
    },
  • "legs": [
    • {
      }
    ],
  • "fare_funding": {
    • "fare": {
      },
    • "funding_source": "SPONSOR",
    • "sponsor_ref": "jfs-washtenaw"
    },
  • "notes_to_driver": "Call on arrival.",
  • "created_at": "2026-10-30T14:02:11-04:00",
  • "updated_at": "2026-11-02T16:40:05-05:00"
}

Modify a trip

Change windows, party or driver notes. The provider may accept (200, status unchanged or CONFIRMED), re-offer (200, status OFFERED), or decide later (202). If it refuses, the trip keeps its previous terms and the response is 422.

Authorizations:
oauth2
path Parameters
trip_id
required
string

The requester-assigned trip_id. Scoped to the authenticated requester.

header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Client-generated key (e.g. a UUID) making the request safe to retry. A repeat with the same key and body returns the original response; the same key with a different body is rejected with IDEMPOTENCY_KEY_REUSED. Keys are scoped to the authenticated requester and kept for at least 24 hours.

Request Body schema: application/json
required
non-empty
object (time-window)

New requested pickup window.

object (time-window)

New requested dropoff window.

object (party)

New party counts; replaces the previous party object.

notes_to_driver
string <= 500 characters

Replacement driver notes. Must not contain health or diagnosis information.

Responses

Response Schema: application/json
trip_id
required
string

Identifier assigned by the requester; unique per requester_id.

provider_trip_id
string

Identifier assigned by the provider once it accepts the trip.

requester_id
required
string

Identifier of the party requesting the trip.

provider_id
required
string

Identifier of the party asked to serve the trip.

status
required
string (trip-status)
Enum: "REQUESTED" "OFFERED" "CONFIRMED" "SCHEDULED" "IN_PROGRESS" "COMPLETED" "FAILED" "REJECTED" "EXPIRED" "CANCELLED" "NO_SHOW"

Current lifecycle state.

required
object (rider)

The rider, by reference.

object (party)

Others travelling with the rider.

required
Array of Leg (object) or Leg (object) (Leg) = 1 items

The trip's legs. Core requires exactly one.

object (fare-funding)

Fare and funding details for settlement.

notes_to_driver
string <= 500 characters

Free-text operational notes, e.g. "call on arrival". Must not contain health or diagnosis information.

offer_expires_at
string <date-time>

While the trip is OFFERED: the offer lapses (status EXPIRED) unless the requester confirms by then. Absent when offers don't expire.

object (cancellation)

Present when status is CANCELLED.

created_at
required
string <date-time>

When the trip was created, RFC 3339 with offset.

updated_at
required
string <date-time>

When the trip last changed, RFC 3339 with offset.

Response Schema: application/json
trip_id
required
string

Identifier assigned by the requester; unique per requester_id.

provider_trip_id
string

Identifier assigned by the provider once it accepts the trip.

requester_id
required
string

Identifier of the party requesting the trip.

provider_id
required
string

Identifier of the party asked to serve the trip.

status
required
string (trip-status)
Enum: "REQUESTED" "OFFERED" "CONFIRMED" "SCHEDULED" "IN_PROGRESS" "COMPLETED" "FAILED" "REJECTED" "EXPIRED" "CANCELLED" "NO_SHOW"

Current lifecycle state.

required
object (rider)

The rider, by reference.

object (party)

Others travelling with the rider.

required
Array of Leg (object) or Leg (object) (Leg) = 1 items

The trip's legs. Core requires exactly one.

object (fare-funding)

Fare and funding details for settlement.

notes_to_driver
string <= 500 characters

Free-text operational notes, e.g. "call on arrival". Must not contain health or diagnosis information.

offer_expires_at
string <date-time>

While the trip is OFFERED: the offer lapses (status EXPIRED) unless the requester confirms by then. Absent when offers don't expire.

object (cancellation)

Present when status is CANCELLED.

created_at
required
string <date-time>

When the trip was created, RFC 3339 with offset.

updated_at
required
string <date-time>

When the trip last changed, RFC 3339 with offset.

Request samples

Content type
application/json
{
  • "pickup_window": {
    • "earliest": "2019-08-24T14:15:22Z",
    • "latest": "2019-08-24T14:15:22Z",
    • "preferred": "2019-08-24T14:15:22Z"
    },
  • "dropoff_window": {
    • "earliest": "2019-08-24T14:15:22Z",
    • "latest": "2019-08-24T14:15:22Z",
    • "preferred": "2019-08-24T14:15:22Z"
    },
  • "party": {
    • "companions": 0,
    • "attendants": 0,
    • "service_animals": 0
    },
  • "notes_to_driver": "string"
}

Response samples

Content type
application/json
{
  • "trip_id": "string",
  • "provider_trip_id": "string",
  • "requester_id": "string",
  • "provider_id": "string",
  • "status": "REQUESTED",
  • "rider_ref": {
    • "rider_ref_id": "string",
    • "display_name": "string",
    • "contact": {
      },
    • "contact_consent": false,
    • "language": "string",
    • "eligibility": [
      ]
    },
  • "party": {
    • "companions": 0,
    • "attendants": 0,
    • "service_animals": 0
    },
  • "legs": [
    • {
      }
    ],
  • "fare_funding": {
    • "fare": {
      },
    • "funding_source": "RIDER",
    • "sponsor_ref": "string",
    • "authorization_ref": "string"
    },
  • "notes_to_driver": "string",
  • "offer_expires_at": "2019-08-24T14:15:22Z",
  • "cancellation": {
    • "reason": "RIDER_REQUEST",
    • "cancelled_by": "REQUESTER",
    • "detail": "string",
    • "cancelled_at": "2019-08-24T14:15:22Z"
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Confirm an offered trip

Accept the provider's offer. Only valid while the trip is OFFERED.

Authorizations:
oauth2
path Parameters
trip_id
required
string

The requester-assigned trip_id. Scoped to the authenticated requester.

header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Client-generated key (e.g. a UUID) making the request safe to retry. A repeat with the same key and body returns the original response; the same key with a different body is rejected with IDEMPOTENCY_KEY_REUSED. Keys are scoped to the authenticated requester and kept for at least 24 hours.

Responses

Response Schema: application/json
trip_id
required
string

Identifier assigned by the requester; unique per requester_id.

provider_trip_id
string

Identifier assigned by the provider once it accepts the trip.

requester_id
required
string

Identifier of the party requesting the trip.

provider_id
required
string

Identifier of the party asked to serve the trip.

status
required
string (trip-status)
Enum: "REQUESTED" "OFFERED" "CONFIRMED" "SCHEDULED" "IN_PROGRESS" "COMPLETED" "FAILED" "REJECTED" "EXPIRED" "CANCELLED" "NO_SHOW"

Current lifecycle state.

required
object (rider)

The rider, by reference.

object (party)

Others travelling with the rider.

required
Array of Leg (object) or Leg (object) (Leg) = 1 items

The trip's legs. Core requires exactly one.

object (fare-funding)

Fare and funding details for settlement.

notes_to_driver
string <= 500 characters

Free-text operational notes, e.g. "call on arrival". Must not contain health or diagnosis information.

offer_expires_at
string <date-time>

While the trip is OFFERED: the offer lapses (status EXPIRED) unless the requester confirms by then. Absent when offers don't expire.

object (cancellation)

Present when status is CANCELLED.

created_at
required
string <date-time>

When the trip was created, RFC 3339 with offset.

updated_at
required
string <date-time>

When the trip last changed, RFC 3339 with offset.

Response samples

Content type
application/json
{
  • "trip_id": "tr-20261103-0001",
  • "provider_trip_id": "AR-558812",
  • "requester_id": "throughride-demo",
  • "provider_id": "aaata-a-ride",
  • "status": "CONFIRMED",
  • "rider_ref": {
    • "rider_ref_id": "r-7f3a",
    • "display_name": "Dana K.",
    • "language": "en",
    • "eligibility": [
      ]
    },
  • "party": {
    • "companions": 0,
    • "attendants": 1,
    • "service_animals": 0
    },
  • "legs": [
    • {
      }
    ],
  • "fare_funding": {
    • "fare": {
      },
    • "funding_source": "SPONSOR",
    • "sponsor_ref": "jfs-washtenaw"
    },
  • "notes_to_driver": "Call on arrival.",
  • "created_at": "2026-10-30T14:02:11-04:00",
  • "updated_at": "2026-10-30T14:05:40-04:00"
}

Cancel a trip

Cancel a trip that has not reached a terminal state. The response carries the trip with status CANCELLED and a cancellation record.

Authorizations:
oauth2
path Parameters
trip_id
required
string

The requester-assigned trip_id. Scoped to the authenticated requester.

header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Client-generated key (e.g. a UUID) making the request safe to retry. A repeat with the same key and body returns the original response; the same key with a different body is rejected with IDEMPOTENCY_KEY_REUSED. Keys are scoped to the authenticated requester and kept for at least 24 hours.

Request Body schema: application/json
required
reason
required
string (cancel-reason)
Enum: "RIDER_REQUEST" "PROVIDER_UNABLE" "DUPLICATE" "MISSED_CONNECTION" "OTHER"

Why the trip is cancelled.

detail
string <= 500 characters

Optional free-text explanation. Must not contain health or diagnosis information.

Responses

Response Schema: application/json
trip_id
required
string

Identifier assigned by the requester; unique per requester_id.

provider_trip_id
string

Identifier assigned by the provider once it accepts the trip.

requester_id
required
string

Identifier of the party requesting the trip.

provider_id
required
string

Identifier of the party asked to serve the trip.

status
required
string (trip-status)
Enum: "REQUESTED" "OFFERED" "CONFIRMED" "SCHEDULED" "IN_PROGRESS" "COMPLETED" "FAILED" "REJECTED" "EXPIRED" "CANCELLED" "NO_SHOW"

Current lifecycle state.

required
object (rider)

The rider, by reference.

object (party)

Others travelling with the rider.

required
Array of Leg (object) or Leg (object) (Leg) = 1 items

The trip's legs. Core requires exactly one.

object (fare-funding)

Fare and funding details for settlement.

notes_to_driver
string <= 500 characters

Free-text operational notes, e.g. "call on arrival". Must not contain health or diagnosis information.

offer_expires_at
string <date-time>

While the trip is OFFERED: the offer lapses (status EXPIRED) unless the requester confirms by then. Absent when offers don't expire.

object (cancellation)

Present when status is CANCELLED.

created_at
required
string <date-time>

When the trip was created, RFC 3339 with offset.

updated_at
required
string <date-time>

When the trip last changed, RFC 3339 with offset.

Request samples

Content type
application/json
Example
{
  • "reason": "RIDER_REQUEST"
}

Response samples

Content type
application/json
Example
{
  • "trip_id": "tr-20261105-0007",
  • "requester_id": "throughride-demo",
  • "provider_id": "aaata-a-ride",
  • "rider_ref": {
    • "rider_ref_id": "r-91c2",
    • "display_name": "Luis",
    • "contact": {
      },
    • "contact_consent": true,
    • "language": "es"
    },
  • "legs": [
    • {
      }
    ],
  • "fare_funding": {
    • "fare": {
      },
    • "funding_source": "RIDER"
    },
  • "status": "CANCELLED",
  • "created_at": "2026-11-02T17:40:00-05:00",
  • "updated_at": "2026-11-02T18:05:00-05:00",
  • "cancellation": {
    • "reason": "RIDER_REQUEST",
    • "cancelled_by": "REQUESTER",
    • "cancelled_at": "2026-11-02T18:05:00-05:00"
    }
}

Events

Webhook subscriptions (create, read, change, end) and their signing secrets.

List your subscriptions

The authenticated requester's current subscriptions, oldest first, without signing secrets (SPEC.md §9.3). Use it to find subscriptions to change or end, e.g. duplicates made before PATCH was available. Optional for providers: those that implement it declare subscription_management: true on /health.

Authorizations:
oauth2

Responses

Response Schema: application/json
required
Array of objects (Subscription)

The requester's current subscriptions, oldest first; empty if it has none.

Response samples

Content type
application/json
{
  • "subscriptions": [
    • {
      }
    ]
}

Register a webhook

Register a callback URL for trip events. The response carries the signing secret once; events are signed with Standard Webhooks headers (webhook-signature) and the deprecated X-TDS-Signature (SPEC.md §9, §12). With cloudevents: true, deliveries also carry CloudEvents binary-mode ce-* headers (SPEC.md §9.1). Providers that declare secret_rotation: true on /health also return signing_secret_id and mint later secrets with POST /subscriptions/{subscription_id}/secrets (SPEC.md §12.1). Providers that declare subscription_management: true let the subscriber change the event types or callback later with PATCH /subscriptions/{subscription_id} instead of subscribing again (SPEC.md §9.3).

Authorizations:
oauth2
header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Client-generated key (e.g. a UUID) making the request safe to retry. A repeat with the same key and body returns the original response; the same key with a different body is rejected with IDEMPOTENCY_KEY_REUSED. Keys are scoped to the authenticated requester and kept for at least 24 hours.

Request Body schema: application/json
required
callback_url
required
string <uri> ^(https://|http://(localhost|127\.0\.0\.1)(:[...

HTTPS URL the provider POSTs events to. Plain http is allowed only for loopback addresses (localhost, 127.0.0.1), for development and the conformance kit's local receiver.

event_types
required
Array of strings (event-types) non-empty unique
Items Enum: "TRIP_STATUS_CHANGED" "TRIP_SCHEDULED" "TRIP_CANCELLED" "TENDER_RESPONSE" "HOLD_RESPONSE" "MILESTONE" "ETA_UPDATE" "CUSTODY_HANDOFF" "EXCEPTION_RAISED" "EXCEPTION_RESOLVED"

Event types to deliver.

cloudevents
boolean
Default: false

Ask for CloudEvents 1.0 binary-mode ce-* headers on every delivery (SPEC.md §9.1). The body stays the TDS event. A provider that cannot add them still creates the subscription and returns cloudevents: false.

Responses

Response Schema: application/json
subscription_id
required
string

Provider-assigned identifier of the subscription.

callback_url
required
string <uri>

HTTPS URL the provider POSTs events to.

event_types
required
Array of strings (event-types) non-empty unique
Items Enum: "TRIP_STATUS_CHANGED" "TRIP_SCHEDULED" "TRIP_CANCELLED" "TENDER_RESPONSE" "HOLD_RESPONSE" "MILESTONE" "ETA_UPDATE" "CUSTODY_HANDOFF" "EXCEPTION_RAISED" "EXCEPTION_RESOLVED"

Event types delivered to this subscription.

signing_secret
string >= 32 characters

Shared secret for the webhook signatures (SPEC.md §12). Returned only in the response that creates the subscription (and its replay under the same Idempotency-Key), never by GET, PATCH or DELETE (SPEC.md §9.3). Providers SHOULD issue it as a Standard Webhooks secret: whsec_ followed by the standard base64 of 24 to 64 random bytes. webhook-signature is keyed with those decoded bytes; the deprecated X-TDS-Signature is keyed with the UTF-8 bytes of the whole string. A secret in any other form gets X-TDS-Signature only.

signing_secret_id
string non-empty

Identifier of signing_secret among the subscription's secrets (SPEC.md §12.1), for providers that support rotating secrets with POST /subscriptions/{subscription_id}/secrets. Use it to retire this secret early once a newer one is in use.

cloudevents
boolean
Default: false

True if every delivery carries CloudEvents 1.0 binary-mode ce-* headers (SPEC.md §9.1). Absent or false: the provider may still add them, but the subscriber must not rely on them.

created_at
required
string <date-time>

When the subscription was created, RFC 3339 with offset.

updated_at
string <date-time>

When the subscription was last changed with PATCH /subscriptions/{subscription_id} (SPEC.md §9.3), RFC 3339 with offset. Absent if it has never been changed.

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
Example
{
  • "subscription_id": "sub-01",
  • "callback_url": "https://broker.example.org/tds/events",
  • "event_types": [
    • "TRIP_STATUS_CHANGED",
    • "TRIP_SCHEDULED",
    • "TRIP_CANCELLED"
    ],
  • "signing_secret": "whsec_demo_9f8b2c4e1a7d6f3b5c0e8a2d4f6b1c3e",
  • "created_at": "2026-10-30T13:00:00-04:00"
}

Read a subscription

The subscription's callback, event types and settings (SPEC.md §9.3), without its signing secret. Optional for providers: those that implement it declare subscription_management: true on /health.

Authorizations:
oauth2
path Parameters
subscription_id
required
string

The provider-assigned subscription_id. Scoped to the authenticated requester: another client's subscription is NOT_FOUND.

Responses

Response Schema: application/json
subscription_id
required
string

Provider-assigned identifier of the subscription.

callback_url
required
string <uri>

HTTPS URL the provider POSTs events to.

event_types
required
Array of strings (event-types) non-empty unique
Items Enum: "TRIP_STATUS_CHANGED" "TRIP_SCHEDULED" "TRIP_CANCELLED" "TENDER_RESPONSE" "HOLD_RESPONSE" "MILESTONE" "ETA_UPDATE" "CUSTODY_HANDOFF" "EXCEPTION_RAISED" "EXCEPTION_RESOLVED"

Event types delivered to this subscription.

signing_secret
string >= 32 characters

Shared secret for the webhook signatures (SPEC.md §12). Returned only in the response that creates the subscription (and its replay under the same Idempotency-Key), never by GET, PATCH or DELETE (SPEC.md §9.3). Providers SHOULD issue it as a Standard Webhooks secret: whsec_ followed by the standard base64 of 24 to 64 random bytes. webhook-signature is keyed with those decoded bytes; the deprecated X-TDS-Signature is keyed with the UTF-8 bytes of the whole string. A secret in any other form gets X-TDS-Signature only.

signing_secret_id
string non-empty

Identifier of signing_secret among the subscription's secrets (SPEC.md §12.1), for providers that support rotating secrets with POST /subscriptions/{subscription_id}/secrets. Use it to retire this secret early once a newer one is in use.

cloudevents
boolean
Default: false

True if every delivery carries CloudEvents 1.0 binary-mode ce-* headers (SPEC.md §9.1). Absent or false: the provider may still add them, but the subscriber must not rely on them.

created_at
required
string <date-time>

When the subscription was created, RFC 3339 with offset.

updated_at
string <date-time>

When the subscription was last changed with PATCH /subscriptions/{subscription_id} (SPEC.md §9.3), RFC 3339 with offset. Absent if it has never been changed.

Response samples

Content type
application/json
{
  • "subscription_id": "sub-12",
  • "callback_url": "https://broker.example.org/tds/events",
  • "event_types": [
    • "TRIP_STATUS_CHANGED",
    • "TRIP_SCHEDULED",
    • "TRIP_CANCELLED",
    • "TENDER_RESPONSE",
    • "HOLD_RESPONSE",
    • "MILESTONE"
    ],
  • "signing_secret_id": "sec-1",
  • "created_at": "2026-10-30T13:00:00-04:00"
}

Change a subscription

Replace the subscription's event types, callback URL or CloudEvents setting (SPEC.md §9.3); fields left out keep their values, and event_types is replaced as a whole. The subscription_id, signing secrets and secret ids do not change, so deliveries keep verifying with the secret the subscriber already holds. Events raised after the response follow the new settings. A retry with the same Idempotency-Key returns the same answer. Optional for providers: those that implement it declare subscription_management: true on /health.

Authorizations:
oauth2
path Parameters
subscription_id
required
string

The provider-assigned subscription_id. Scoped to the authenticated requester: another client's subscription is NOT_FOUND.

header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Client-generated key (e.g. a UUID) making the request safe to retry. A repeat with the same key and body returns the original response; the same key with a different body is rejected with IDEMPOTENCY_KEY_REUSED. Keys are scoped to the authenticated requester and kept for at least 24 hours.

Request Body schema: application/json
required
Any of
callback_url
required
string <uri> ^(https://|http://(localhost|127\.0\.0\.1)(:[...

New HTTPS URL to POST events to, with the same rules as on POST /subscriptions (plain http only for loopback addresses).

event_types
Array of strings (event-types) non-empty unique
Items Enum: "TRIP_STATUS_CHANGED" "TRIP_SCHEDULED" "TRIP_CANCELLED" "TENDER_RESPONSE" "HOLD_RESPONSE" "MILESTONE" "ETA_UPDATE" "CUSTODY_HANDOFF" "EXCEPTION_RAISED" "EXCEPTION_RESOLVED"

The complete new set of event types to deliver. It replaces the current set as a whole, so to add one type send the current types plus the new one (read them with GET /subscriptions/{subscription_id}).

cloudevents
boolean

Ask for (true) or stop asking for (false) CloudEvents binary-mode ce-* headers (SPEC.md §9.1). As on creation, a provider that cannot add them still applies the rest of the change and answers cloudevents: false.

Responses

Response Schema: application/json
subscription_id
required
string

Provider-assigned identifier of the subscription.

callback_url
required
string <uri>

HTTPS URL the provider POSTs events to.

event_types
required
Array of strings (event-types) non-empty unique
Items Enum: "TRIP_STATUS_CHANGED" "TRIP_SCHEDULED" "TRIP_CANCELLED" "TENDER_RESPONSE" "HOLD_RESPONSE" "MILESTONE" "ETA_UPDATE" "CUSTODY_HANDOFF" "EXCEPTION_RAISED" "EXCEPTION_RESOLVED"

Event types delivered to this subscription.

signing_secret
string >= 32 characters

Shared secret for the webhook signatures (SPEC.md §12). Returned only in the response that creates the subscription (and its replay under the same Idempotency-Key), never by GET, PATCH or DELETE (SPEC.md §9.3). Providers SHOULD issue it as a Standard Webhooks secret: whsec_ followed by the standard base64 of 24 to 64 random bytes. webhook-signature is keyed with those decoded bytes; the deprecated X-TDS-Signature is keyed with the UTF-8 bytes of the whole string. A secret in any other form gets X-TDS-Signature only.

signing_secret_id
string non-empty

Identifier of signing_secret among the subscription's secrets (SPEC.md §12.1), for providers that support rotating secrets with POST /subscriptions/{subscription_id}/secrets. Use it to retire this secret early once a newer one is in use.

cloudevents
boolean
Default: false

True if every delivery carries CloudEvents 1.0 binary-mode ce-* headers (SPEC.md §9.1). Absent or false: the provider may still add them, but the subscriber must not rely on them.

created_at
required
string <date-time>

When the subscription was created, RFC 3339 with offset.

updated_at
string <date-time>

When the subscription was last changed with PATCH /subscriptions/{subscription_id} (SPEC.md §9.3), RFC 3339 with offset. Absent if it has never been changed.

Request samples

Content type
application/json
{
  • "event_types": [
    • "TRIP_STATUS_CHANGED",
    • "TRIP_SCHEDULED",
    • "TRIP_CANCELLED",
    • "TENDER_RESPONSE",
    • "HOLD_RESPONSE",
    • "MILESTONE",
    • "ETA_UPDATE"
    ]
}

Response samples

Content type
application/json
{
  • "subscription_id": "sub-12",
  • "callback_url": "https://broker.example.org/tds/events",
  • "event_types": [
    • "TRIP_STATUS_CHANGED",
    • "TRIP_SCHEDULED",
    • "TRIP_CANCELLED",
    • "TENDER_RESPONSE",
    • "HOLD_RESPONSE",
    • "MILESTONE",
    • "ETA_UPDATE"
    ],
  • "signing_secret_id": "sec-1",
  • "created_at": "2026-10-30T13:00:00-04:00",
  • "updated_at": "2026-11-09T09:00:00-05:00"
}

End a subscription

End the subscription (SPEC.md §9.3): no delivery attempt to it starts after the response, retries of earlier events included, and its signing secrets stop being used. Reading, changing or ending it again is NOT_FOUND; a retry with the same Idempotency-Key returns the same answer. Optional for providers: those that implement it declare subscription_management: true on /health.

Authorizations:
oauth2
path Parameters
subscription_id
required
string

The provider-assigned subscription_id. Scoped to the authenticated requester: another client's subscription is NOT_FOUND.

header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Client-generated key (e.g. a UUID) making the request safe to retry. A repeat with the same key and body returns the original response; the same key with a different body is rejected with IDEMPOTENCY_KEY_REUSED. Keys are scoped to the authenticated requester and kept for at least 24 hours.

Responses

Response Schema: application/json
subscription_id
required
string

Provider-assigned identifier of the subscription.

callback_url
required
string <uri>

HTTPS URL the provider POSTs events to.

event_types
required
Array of strings (event-types) non-empty unique
Items Enum: "TRIP_STATUS_CHANGED" "TRIP_SCHEDULED" "TRIP_CANCELLED" "TENDER_RESPONSE" "HOLD_RESPONSE" "MILESTONE" "ETA_UPDATE" "CUSTODY_HANDOFF" "EXCEPTION_RAISED" "EXCEPTION_RESOLVED"

Event types delivered to this subscription.

signing_secret
string >= 32 characters

Shared secret for the webhook signatures (SPEC.md §12). Returned only in the response that creates the subscription (and its replay under the same Idempotency-Key), never by GET, PATCH or DELETE (SPEC.md §9.3). Providers SHOULD issue it as a Standard Webhooks secret: whsec_ followed by the standard base64 of 24 to 64 random bytes. webhook-signature is keyed with those decoded bytes; the deprecated X-TDS-Signature is keyed with the UTF-8 bytes of the whole string. A secret in any other form gets X-TDS-Signature only.

signing_secret_id
string non-empty

Identifier of signing_secret among the subscription's secrets (SPEC.md §12.1), for providers that support rotating secrets with POST /subscriptions/{subscription_id}/secrets. Use it to retire this secret early once a newer one is in use.

cloudevents
boolean
Default: false

True if every delivery carries CloudEvents 1.0 binary-mode ce-* headers (SPEC.md §9.1). Absent or false: the provider may still add them, but the subscriber must not rely on them.

created_at
required
string <date-time>

When the subscription was created, RFC 3339 with offset.

updated_at
string <date-time>

When the subscription was last changed with PATCH /subscriptions/{subscription_id} (SPEC.md §9.3), RFC 3339 with offset. Absent if it has never been changed.

Response samples

Content type
application/json
{
  • "subscription_id": "sub-12",
  • "callback_url": "https://broker.example.org/tds/events",
  • "event_types": [
    • "TRIP_STATUS_CHANGED",
    • "TRIP_SCHEDULED",
    • "TRIP_CANCELLED",
    • "TENDER_RESPONSE",
    • "HOLD_RESPONSE",
    • "MILESTONE",
    • "ETA_UPDATE"
    ],
  • "signing_secret_id": "sec-1",
  • "created_at": "2026-10-30T13:00:00-04:00",
  • "updated_at": "2026-11-09T09:00:00-05:00"
}

Rotate a subscription's signing secret

Mint a new signing secret for the subscription (SPEC.md §12.1). The response carries the new value once, as the first entry; older secrets stay valid until their expires_at (now + overlap_s, or the provider's default overlap), and until then every delivery carries a webhook-signature entry for each active secret, newest first, while X-TDS-Signature uses the newest. A retry with the same Idempotency-Key returns the same new secret. Optional for providers: those that implement it declare secret_rotation: true on /health.

Authorizations:
oauth2
path Parameters
subscription_id
required
string

The provider-assigned subscription_id. Scoped to the authenticated requester: another client's subscription is NOT_FOUND.

header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Client-generated key (e.g. a UUID) making the request safe to retry. A repeat with the same key and body returns the original response; the same key with a different body is rejected with IDEMPOTENCY_KEY_REUSED. Keys are scoped to the authenticated requester and kept for at least 24 hours.

Request Body schema: application/json
optional
overlap_s
integer [ 0 .. 2592000 ]

How long, in seconds from now, the subscription's older secrets stay valid alongside the new one. 0 retires them at once (for a leaked secret). Absent: the provider's default, which SHOULD be 86400 (24 hours). A provider MAY shorten it to its own maximum, which SHOULD be at least 86400; it never lengthens it, and never extends an older secret's existing expires_at. The response's expires_at values say what applies.

Responses

Response Schema: application/json
subscription_id
required
string

The subscription these secrets sign for.

required
Array of objects (SubscriptionSecret) non-empty

Active secrets, newest first. The first has no expires_at; every other one has. The sender signs each delivery with all of them.

Request samples

Content type
application/json
{
  • "overlap_s": 86400
}

Response samples

Content type
application/json
{
  • "subscription_id": "sub-07",
  • "secrets": [
    • {
      },
    • {
      }
    ]
}

List a subscription's active signing secrets

The subscription's active secrets, newest first, with ids and expiry times but never their values (SPEC.md §12.1).

Authorizations:
oauth2
path Parameters
subscription_id
required
string

The provider-assigned subscription_id. Scoped to the authenticated requester: another client's subscription is NOT_FOUND.

Responses

Response Schema: application/json
subscription_id
required
string

The subscription these secrets sign for.

required
Array of objects (SubscriptionSecret) non-empty

Active secrets, newest first. The first has no expires_at; every other one has. The sender signs each delivery with all of them.

Response samples

Content type
application/json
{
  • "subscription_id": "sub-07",
  • "secrets": [
    • {
      },
    • {
      }
    ]
}

Retire a signing secret early

Stop signing with an older secret now, before its expires_at, once the receiver verifies with the newer one (SPEC.md §12.1). The newest secret cannot be retired; rotate first. Retiring a secret that has already expired changes nothing and returns it.

Authorizations:
oauth2
path Parameters
subscription_id
required
string

The provider-assigned subscription_id. Scoped to the authenticated requester: another client's subscription is NOT_FOUND.

secret_id
required
string

The provider-assigned secret_id of one of the subscription's signing secrets.

header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Client-generated key (e.g. a UUID) making the request safe to retry. A repeat with the same key and body returns the original response; the same key with a different body is rejected with IDEMPOTENCY_KEY_REUSED. Keys are scoped to the authenticated requester and kept for at least 24 hours.

Responses

Response Schema: application/json
secret_id
required
string non-empty

Provider-assigned identifier of the secret, unique within the subscription. Not secret; use it to retire the secret early.

signing_secret
string >= 32 characters

The secret value, in the same form as the subscription's signing_secret (whsec_ + standard base64 of 24 to 64 random bytes, SHOULD). Present only in the response that creates the secret (and in a replay of that response with the same Idempotency-Key); never in listings.

created_at
required
string <date-time>

When the secret was created, RFC 3339 with offset.

expires_at
string <date-time>

When the sender stops signing with this secret, RFC 3339 with offset. Absent on the newest secret, which does not expire until another one replaces it. Deliveries sent at or after this moment carry no signature made with this secret.

Response samples

Content type
application/json
{
  • "secret_id": "sec-01",
  • "created_at": "2026-10-30T13:00:00-04:00",
  • "expires_at": "2026-11-02T12:00:00-05:00"
}

Transfer

Transfer profile: tenders and hold requests for protected cross-provider connections.

Ask the outbound vehicle to hold or retime

Sent to the outbound provider when the inbound leg's ETA threatens the connection (SPEC.md §10.5). Answered at once (201: GRANTED, PARTIAL or DENIED) or later (202 PENDING, then a HOLD_RESPONSE event); unanswered by respond_by, the hold is EXPIRED. GRANTED and PARTIAL also update the trip's scheduled_pickup and emit TRIP_SCHEDULED.

Authorizations:
oauth2
path Parameters
trip_id
required
string

The requester-assigned trip_id. Scoped to the authenticated requester.

header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Client-generated key (e.g. a UUID) making the request safe to retry. A repeat with the same key and body returns the original response; the same key with a different body is rejected with IDEMPOTENCY_KEY_REUSED. Keys are scoped to the authenticated requester and kept for at least 24 hours.

Request Body schema: application/json
required
hold_id
required
string

Broker-assigned identifier, unique per requester.

interchange_id
required
string

The interchange whose outbound leg is this trip.

action
required
string
Enum: "HOLD" "RETIME"

HOLD (wait) or RETIME (move the pickup).

requested_until
required
string <date-time>

HOLD: wait until this time. RETIME: the proposed new pickup time.

respond_by
required
string <date-time>

Deadline for an answer. Unanswered by then, the hold is EXPIRED.

object (eta-band)

The inbound leg's latest ETA band, so the provider can judge the request.

Responses

Response Schema: application/json
hold_id
required
string

Broker-assigned hold identifier.

trip_id
required
string

The outbound trip.

interchange_id
required
string

The interchange being protected.

action
required
string
Enum: "HOLD" "RETIME"

What was asked.

requested_until
required
string <date-time>

As in the request.

respond_by
required
string <date-time>

As in the request.

status
required
string
Enum: "PENDING" "GRANTED" "PARTIAL" "DENIED" "EXPIRED"

Hold lifecycle state.

scheduled_pickup
string <date-time>

Outbound pickup time after the decision (GRANTED or PARTIAL).

held_until
string <date-time>

Latest time the vehicle will wait at the transfer point, if different from scheduled_pickup.

reason
string
Enum: "EXCEEDS_MAX_HOLD" "DOWNSTREAM_COMMITMENT" "DRIVER_HOURS" "OTHER"

Why the hold was denied or only partly granted.

created_at
required
string <date-time>

When the provider received the request.

responded_at
string <date-time>

When the provider answered or the hold expired.

Response Schema: application/json
hold_id
required
string

Broker-assigned hold identifier.

trip_id
required
string

The outbound trip.

interchange_id
required
string

The interchange being protected.

action
required
string
Enum: "HOLD" "RETIME"

What was asked.

requested_until
required
string <date-time>

As in the request.

respond_by
required
string <date-time>

As in the request.

status
required
string
Enum: "PENDING" "GRANTED" "PARTIAL" "DENIED" "EXPIRED"

Hold lifecycle state.

scheduled_pickup
string <date-time>

Outbound pickup time after the decision (GRANTED or PARTIAL).

held_until
string <date-time>

Latest time the vehicle will wait at the transfer point, if different from scheduled_pickup.

reason
string
Enum: "EXCEEDS_MAX_HOLD" "DOWNSTREAM_COMMITMENT" "DRIVER_HOURS" "OTHER"

Why the hold was denied or only partly granted.

created_at
required
string <date-time>

When the provider received the request.

responded_at
string <date-time>

When the provider answered or the hold expired.

Request samples

Content type
application/json
Example
{
  • "hold_id": "hd-hold-1",
  • "interchange_id": "ix-hold",
  • "action": "HOLD",
  • "requested_until": "2026-11-10T09:50:00-05:00",
  • "respond_by": "2026-11-10T09:11:00-05:00",
  • "inbound_eta": {
    • "target": "DROPOFF",
    • "earliest": "2026-11-10T09:42:00-05:00",
    • "likely": "2026-11-10T09:45:00-05:00",
    • "latest": "2026-11-10T09:57:30-05:00",
    • "confidence": 0.7,
    • "computed_at": "2026-11-10T09:05:00-05:00",
    • "source": "VEHICLE_POSITION",
    • "delay_cause": "TRAFFIC"
    }
}

Response samples

Content type
application/json
Example
{
  • "hold_id": "hd-hold-1",
  • "trip_id": "tr-hold-b",
  • "interchange_id": "ix-hold",
  • "action": "HOLD",
  • "requested_until": "2026-11-10T09:50:00-05:00",
  • "respond_by": "2026-11-10T09:11:00-05:00",
  • "status": "GRANTED",
  • "created_at": "2026-11-10T09:06:00-05:00",
  • "scheduled_pickup": "2026-11-10T09:50:00-05:00",
  • "held_until": "2026-11-10T09:50:00-05:00",
  • "responded_at": "2026-11-10T09:06:00-05:00"
}

Get a hold request

Current state of a hold request.

Authorizations:
oauth2
path Parameters
trip_id
required
string

The requester-assigned trip_id. Scoped to the authenticated requester.

hold_id
required
string

The broker-assigned hold_id. Scoped to the authenticated requester.

Responses

Response Schema: application/json
hold_id
required
string

Broker-assigned hold identifier.

trip_id
required
string

The outbound trip.

interchange_id
required
string

The interchange being protected.

action
required
string
Enum: "HOLD" "RETIME"

What was asked.

requested_until
required
string <date-time>

As in the request.

respond_by
required
string <date-time>

As in the request.

status
required
string
Enum: "PENDING" "GRANTED" "PARTIAL" "DENIED" "EXPIRED"

Hold lifecycle state.

scheduled_pickup
string <date-time>

Outbound pickup time after the decision (GRANTED or PARTIAL).

held_until
string <date-time>

Latest time the vehicle will wait at the transfer point, if different from scheduled_pickup.

reason
string
Enum: "EXCEEDS_MAX_HOLD" "DOWNSTREAM_COMMITMENT" "DRIVER_HOURS" "OTHER"

Why the hold was denied or only partly granted.

created_at
required
string <date-time>

When the provider received the request.

responded_at
string <date-time>

When the provider answered or the hold expired.

Response samples

Content type
application/json
Example
{
  • "hold_id": "hd-hold-1",
  • "trip_id": "tr-hold-b",
  • "interchange_id": "ix-hold",
  • "action": "HOLD",
  • "requested_until": "2026-11-10T09:50:00-05:00",
  • "respond_by": "2026-11-10T09:11:00-05:00",
  • "status": "GRANTED",
  • "created_at": "2026-11-10T09:06:00-05:00",
  • "scheduled_pickup": "2026-11-10T09:50:00-05:00",
  • "held_until": "2026-11-10T09:50:00-05:00",
  • "responded_at": "2026-11-10T09:06:00-05:00"
}

Tender a leg

Offer this provider one leg of a linked journey with the interchange terms and a deadline (SPEC.md §10.2). A provider that decides at once returns 201 with the tender ACCEPTED (the trip now exists, CONFIRMED, under trip.trip_id) or REJECTED. One that decides later returns 202 OFFERED and reports the answer in a TENDER_RESPONSE event; unanswered by respond_by, the tender becomes EXPIRED. Both are conformant.

Authorizations:
oauth2
header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Client-generated key (e.g. a UUID) making the request safe to retry. A repeat with the same key and body returns the original response; the same key with a different body is rejected with IDEMPOTENCY_KEY_REUSED. Keys are scoped to the authenticated requester and kept for at least 24 hours.

Request Body schema: application/json
required
tender_id
required
string

Broker-assigned identifier, unique per requester.

required
object (trip-request)

The trip being offered. Its leg must be the interchange's from or to leg for this provider.

required
object (interchange)

The connection this leg is part of, including the terms the provider is asked to commit to.

respond_by
required
string <date-time>

Deadline for the provider's answer. Unanswered by then, the tender is EXPIRED.

Responses

Response Schema: application/json
tender_id
required
string

Broker-assigned tender identifier.

trip_id
required
string

The offered trip's trip_id; on ACCEPTED, the trip exists under this id.

interchange_id
required
string

The interchange the leg belongs to.

respond_by
required
string <date-time>

Deadline for the provider's answer.

status
required
string
Enum: "OFFERED" "ACCEPTED" "REJECTED" "EXPIRED"

Tender lifecycle state.

reason
string (refusal-reason)
Enum: "NO_CAPACITY" "OUTSIDE_SERVICE_AREA" "OUTSIDE_SERVICE_HOURS" "ELIGIBILITY_REQUIRED" "ELIGIBILITY_NOT_ACCEPTED" "OUTSIDE_BOOKING_WINDOW" "INVALID_WINDOW" "UNSUPPORTED_REQUIREMENT"

Why the tender was rejected.

object (accepted-terms)

Present when ACCEPTED.

provider_trip_id
string

Provider's own id for the created trip, when ACCEPTED.

created_at
required
string <date-time>

When the provider received the tender.

responded_at
string <date-time>

When the provider answered or the tender expired.

Response Schema: application/json
tender_id
required
string

Broker-assigned tender identifier.

trip_id
required
string

The offered trip's trip_id; on ACCEPTED, the trip exists under this id.

interchange_id
required
string

The interchange the leg belongs to.

respond_by
required
string <date-time>

Deadline for the provider's answer.

status
required
string
Enum: "OFFERED" "ACCEPTED" "REJECTED" "EXPIRED"

Tender lifecycle state.

reason
string (refusal-reason)
Enum: "NO_CAPACITY" "OUTSIDE_SERVICE_AREA" "OUTSIDE_SERVICE_HOURS" "ELIGIBILITY_REQUIRED" "ELIGIBILITY_NOT_ACCEPTED" "OUTSIDE_BOOKING_WINDOW" "INVALID_WINDOW" "UNSUPPORTED_REQUIREMENT"

Why the tender was rejected.

object (accepted-terms)

Present when ACCEPTED.

provider_trip_id
string

Provider's own id for the created trip, when ACCEPTED.

created_at
required
string <date-time>

When the provider received the tender.

responded_at
string <date-time>

When the provider answered or the tender expired.

Request samples

Content type
application/json
Example
{
  • "tender_id": "tn-tpt-a",
  • "trip": {
    • "trip_id": "tr-tpt-a",
    • "requester_id": "throughride-demo",
    • "provider_id": "aaata-a-ride",
    • "rider_ref": {
      },
    • "legs": [
      ]
    },
  • "interchange": {
    • "interchange_id": "ix-tpt",
    • "from": {
      },
    • "to": {
      },
    • "transfer_location": {
      },
    • "min_connection_s": 300,
    • "max_hold_s": 900,
    • "auto_hold_s": 300,
    • "accessibility_buffer_s": 300,
    • "protection": "PROTECTED",
    • "supervision_required": false,
    • "heartbeat_s": 300
    },
  • "respond_by": "2026-11-10T08:10:00-05:00"
}

Response samples

Content type
application/json
Example
{
  • "tender_id": "tn-tpt-a",
  • "trip_id": "tr-tpt-a",
  • "interchange_id": "ix-tpt",
  • "respond_by": "2026-11-10T08:10:00-05:00",
  • "status": "ACCEPTED",
  • "created_at": "2026-11-10T07:55:00-05:00",
  • "accepted_terms": {
    • "auto_hold_s": 300,
    • "max_hold_s": 900
    },
  • "provider_trip_id": "aaata-a-ride-0004",
  • "responded_at": "2026-11-10T07:55:00-05:00"
}

Get a tender

Current state of a tender, for brokers that poll instead of (or as well as) receiving events.

Authorizations:
oauth2
path Parameters
tender_id
required
string

The broker-assigned tender_id. Scoped to the authenticated requester.

Responses

Response Schema: application/json
tender_id
required
string

Broker-assigned tender identifier.

trip_id
required
string

The offered trip's trip_id; on ACCEPTED, the trip exists under this id.

interchange_id
required
string

The interchange the leg belongs to.

respond_by
required
string <date-time>

Deadline for the provider's answer.

status
required
string
Enum: "OFFERED" "ACCEPTED" "REJECTED" "EXPIRED"

Tender lifecycle state.

reason
string (refusal-reason)
Enum: "NO_CAPACITY" "OUTSIDE_SERVICE_AREA" "OUTSIDE_SERVICE_HOURS" "ELIGIBILITY_REQUIRED" "ELIGIBILITY_NOT_ACCEPTED" "OUTSIDE_BOOKING_WINDOW" "INVALID_WINDOW" "UNSUPPORTED_REQUIREMENT"

Why the tender was rejected.

object (accepted-terms)

Present when ACCEPTED.

provider_trip_id
string

Provider's own id for the created trip, when ACCEPTED.

created_at
required
string <date-time>

When the provider received the tender.

responded_at
string <date-time>

When the provider answered or the tender expired.

Response samples

Content type
application/json
{
  • "tender_id": "tn-rt-b",
  • "trip_id": "tr-rt-b",
  • "interchange_id": "ix-rt",
  • "respond_by": "2026-11-10T08:00:00-05:00",
  • "status": "EXPIRED",
  • "created_at": "2026-11-10T07:55:00-05:00",
  • "responded_at": "2026-11-10T08:01:00-05:00"
}

Meta

Health and capabilities.

Health and capabilities

Liveness, supported spec versions and profiles, how the endpoint is operated, and the booking windows within which it accepts requests (SPEC.md §7.1). No authentication required.

Responses

Response Schema: application/json
status
required
string
Enum: "OK" "DEGRADED"

OK when accepting requests normally; DEGRADED when up but slow or partially available.

spec_versions
required
Array of strings non-empty [ items^[0-9]+\.[0-9]+\.[0-9]+$ ]

Versions of this binding the endpoint implements (SemVer).

profiles
required
Array of strings non-empty unique
Items Enum: "CORE" "TRANSFER" "PARATRANSIT" "NEMT"

Profiles implemented. CORE is always present.

operated_via
required
string
Enum: "DIRECT" "BROKER_PROXY"

DIRECT when the provider runs this endpoint itself; BROKER_PROXY when a broker exposes it on the provider's behalf and relays requests to staff.

typical_response_s
integer >= 0

Typical seconds from a request to an asynchronous decision. 0 or absent means decisions are synchronous.

object (booking-window)

When this provider accepts requests, relative to the trip time (SPEC.md §7.1). Applies to every request unless booking_window_by_profile has an entry for the request's profile. Absent: the provider states no limit (it may still refuse with OUTSIDE_BOOKING_WINDOW, but SHOULD advertise it).

object

Booking windows that replace booking_window (not merged with it) for requests of one profile: paratransit or nemt when the trip request carries that object, otherwise transfer for a tender. For a provider running services with different rules, e.g. same-day dial-a-ride and next-day ADA paratransit.

secret_rotation
boolean
Default: false

True if this endpoint implements the subscription secret operations (POST/GET /subscriptions/{subscription_id}/secrets, DELETE /subscriptions/{subscription_id}/secrets/{secret_id}, SPEC.md §12.1). Absent or false: a new secret is arranged out of band.

subscription_management
boolean
Default: false

True if this endpoint implements reading, changing and ending webhook subscriptions (GET /subscriptions, GET/PATCH/DELETE /subscriptions/{subscription_id}, SPEC.md §9.3). Absent or false: a subscription's event types or callback cannot be changed over the API.

Response samples

Content type
application/json
Example
{
  • "status": "OK",
  • "spec_versions": [
    • "0.4.0"
    ],
  • "profiles": [
    • "CORE"
    ],
  • "operated_via": "DIRECT"
}