taxiID Integration API

This is the reference for developers building an integration into a company's taxiID account — quoting, creating and tracking rides, and receiving webhook events. All requests are made to integrations.taxiid.nl; you never call api.taxiid.nl directly. All money is integer cents, all timestamps are ISO-8601 UTC.

Pick the tab that matches what you're building — each only shows the calls you actually need. The Objects section below is shared reference material and always stays visible, whichever tab you pick — it documents the full shape of the data the calls further down (in Administration, Dispatch and Ride creation) send and receive, so it isn't repeated endpoint by endpoint.

Objects

The JSON shown next to each call below is trimmed to what that call is about — this section is the full shape of every object type, so you know what else you can read (and, where noted, write) that isn't shown inline everywhere.

Ride

A ride is the central object; every call above either creates one, reads one, or reports a change to one. Most fields are set by taxiID as the ride progresses (arrival ETA, assigned driver, computed price) — you only send the fields marked input when creating one via POST /v1/rides.

Property	Type	Input?	Description
`id`	string	no	taxiID's ride identifier. Use this in every later call about the ride.
`status`	string enum	no	`requested` → `offered` → `accepted` → `arrived` → `started` → `completed`, or `cancelled`/`rejected` at any point before `completed`. See Verifying a webhook for how you're told about changes.
`requestedDate`	ISO-8601 datetime	yes	When the ride should start. Omit for an immediate/ASAP ride.
`passenger`	Passenger	yes	Who's riding. Required even for a ride you book on someone else's behalf.
`origin` / `destination`	Address	yes	Pickup and drop-off. `destination` is optional for some vehicle types (e.g. a driver-at-disposal booking) — check the quote response.
`price`	Price	no	Computed by taxiID, normally from a prior `POST /v1/quotes`. Never send your own `price` on create.
`paymentMeta`	PaymentMeta	optional	How the ride is paid for. Defaults to invoicing the company's account if omitted.
`vehicleType`	string	optional	e.g. `sedan`, `van`, `wheelchair-accessible`. Defaults to the company's standard vehicle type.
`language`	string (ISO 639-1)	optional	Passenger's language, used for any SMS/driver-app messaging about the ride. Defaults to the account's own language.
`flightNumber`	string	optional	For airport pickups — enables flight-tracked pickup timing.
`note`	string	optional	Free-text instruction shown to the driver (e.g. "call on arrival"). Not shown to the passenger.
`debtorCode`	string	optional	Overrides which of the company's debtors is billed for this ride, if the company bills multiple debtors.
`foreignBookingId`	string	optional, echoed back	Your own booking reference. Not interpreted by taxiID — round-tripped as-is onto every webhook so you can match events back to your system without maintaining a separate id map.
`meta`	object, freeform	optional	Your own key/value data, stored and returned untouched. Not shown to the driver or passenger — use `note` for that.
`foreignMeta`	object, freeform	no	The equivalent bag the other side (driver app / dispatch) attaches; read-only to you.
`driverId` / `vehicleId`	string	no	Set once a driver is assigned (from `status:'offered'` onward). Absent before that.
`eta`	ISO-8601 datetime	no	Live estimate for pickup arrival; only present once a driver is en route.
`events`	array of `{status, at}`	no	Full status history with timestamps — the audit trail behind the current `status`.
`companyId`	string	no	The company account the ride belongs to — always your own; present for completeness.

Response

{
  "id": "rd_8f3ac1",
  "status": "accepted",
  "requestedDate": "2026-09-20T14:30:00Z",
  "passenger": { "name": "J. de Vries", "phone": "+31612345678", "passengerCount": 1 },
  "origin": { "address": "Schiphol Airport, Plaza 1", "lat": 52.3105, "lng": 4.7683, "countryCode": "NL" },
  "destination": { "address": "Damrak 1, Amsterdam", "lat": 52.3762, "lng": 4.8952, "countryCode": "NL" },
  "price": { "total": 4850, "currency": "EUR", "breakdown": { "base": 3500, "distance": 1200, "waiting": 150 } },
  "paymentMeta": { "method": "invoice" },
  "vehicleType": "sedan",
  "language": "nl",
  "flightNumber": "KL1023",
  "note": "Passenger will call on arrival",
  "debtorCode": null,
  "foreignBookingId": "acme-book-99231",
  "meta": { "accountManager": "R. Bakker" },
  "foreignMeta": {},
  "driverId": "drv_44c1",
  "vehicleId": "veh_02a9",
  "eta": "2026-09-20T14:28:00Z",
  "events": [
    { "status": "requested", "at": "2026-09-20T14:10:02Z" },
    { "status": "offered", "at": "2026-09-20T14:10:05Z" },
    { "status": "accepted", "at": "2026-09-20T14:10:41Z" }
  ],
  "companyId": "64f1a2b3c4d5e6f7a8b9c0d1"
}

Address

Used for both origin and destination. lat/lng is what taxiID actually routes on; address is a display string shown to the driver and is not geocoded by taxiID — resolve it to coordinates yourself before sending.

Property	Type	Input?	Description
`address`	string	yes	Free-text display address shown to the driver/passenger.
`lat` / `lng`	number	yes	WGS-84 coordinates. This is what's actually used for routing and pricing.
`countryCode`	string (ISO 3166-1 alpha-2)	optional	Used for local address-format rules (e.g. Dutch postal formatting) and duty/VAT handling.
`airportCode`	string (IATA)	optional	Set instead of a street address for an airport pickup, alongside `flightNumber` on the ride.

Passenger

Property	Type	Input?	Description
`name`	string	yes	Shown to the driver.
`phone`	string (E.164)	yes	Used for driver-arrival SMS and driver contact. Always include the country code.
`email`	string	optional	Used only if you enable passenger email receipts on the account.
`passengerCount`	integer	optional	Defaults to `1`. Affects vehicle-type eligibility for larger groups.

Price

Always computed by taxiID (from POST /v1/quotes or on ride completion) — never sent by you.

Property	Type	Description
`total`	integer	Total price, in cents (matches the workspace-wide money convention).
`currency`	string (ISO 4217)	Almost always `EUR`.
`breakdown`	object	Optional itemisation (`base`, `distance`, `waiting`, …) — present on completed rides, may be absent on a fresh quote.

PaymentMeta

Property	Type	Input?	Description
`method`	string enum	optional	`invoice` (bill the company, default), `cash`, or `card`.
`reference`	string	optional	Your own payment/reference note, echoed back untouched — same pattern as `foreignBookingId`.

Webhook envelope

Every webhook delivery (see Dispatch → Verifying a webhook) shares this outer shape; data's contents depend on event.

Property	Type	Description
`event`	string enum	`ride.created`, `ride.status_changed`, or `ride.updated` (opt-in).
`data`	object	For `ride.created`/`ride.updated`, the Ride fields that changed plus `id`. For `ride.status_changed`, `{id, status, previousStatus}`.

Administration

Setup and account calls. Every integration needs these first, regardless of what it does.

Authentication

Subject: send Authorization: Bearer <api-key> on every request. Get your key from the portal under Booking channels → Developer API; it is shown once at creation/rotation time.

GET /v1/me

Subject: your account's status — company name, entitlement, enabled webhook events, and your current rate limit.

cURL

curl https://integrations.taxiid.nl/v1/me \
  -H "Authorization: Bearer $TAXIID_API_KEY"

Response

{
  "companyId": "64f1a2b3c4d5e6f7a8b9c0d1",
  "companyName": "Acme Taxis B.V.",
  "entitled": true,
  "rateLimitPerMinute": 120,
  "webhookEvents": ["ride.created", "ride.status_changed"]
}

Rate limits

Subject: 120 requests/minute per API key by default. A 429 response carries Retry-After in seconds; back off and retry.

Errors

Subject: every error is {"error":{"statusCode","code","message"}}. 401 unknown/rotated-out key, 402 not entitled (contract product not attached), 429 rate limited.

Webhooks setup

Subject: webhook URL, secret, and subscribed events are configured in the portal, not via the API. Each delivery is signed — see Dispatch for verifying the signature.

Dispatch

Calls for integrations that monitor or hand off rides to drivers/fleets, rather than creating them.

GET /v1/rides

Subject: list your rides, filterable by status and date range.

cURL

curl "https://integrations.taxiid.nl/v1/rides?status=accepted&limit=20" \
  -H "Authorization: Bearer $TAXIID_API_KEY"

Response

{
  "data": [
    {
      "id": "rd_8f3ac1",
      "status": "accepted",
      "requestedDate": "2026-09-20T14:30:00Z",
      "origin": { "address": "Schiphol Airport, Plaza 1", "lat": 52.3105, "lng": 4.7683 },
      "destination": { "address": "Damrak 1, Amsterdam", "lat": 52.3762, "lng": 4.8952 },
      "price": { "total": 4850, "currency": "EUR" }
    }
  ],
  "nextCursor": "rd_8f3ab0"
}

GET /v1/rides/{id}

Subject: retrieve a single ride's current state.

cURL

curl https://integrations.taxiid.nl/v1/rides/rd_8f3ac1 \
  -H "Authorization: Bearer $TAXIID_API_KEY"

Response

{
  "id": "rd_8f3ac1",
  "status": "accepted",
  "requestedDate": "2026-09-20T14:30:00Z",
  "passenger": { "name": "J. de Vries", "phone": "+31612345678" },
  "origin": { "address": "Schiphol Airport, Plaza 1", "lat": 52.3105, "lng": 4.7683 },
  "destination": { "address": "Damrak 1, Amsterdam", "lat": 52.3762, "lng": 4.8952 },
  "price": { "total": 4850, "currency": "EUR" }
}

POST /v1/rides/{id}/offer

Subject: offer a ride to a driver or company for dispatch.

cURL

curl -X POST https://integrations.taxiid.nl/v1/rides/rd_8f3ac1/offer \
  -H "Authorization: Bearer $TAXIID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"driverId": "drv_44c1"}'

Request

{ "driverId": "drv_44c1" }

Response

{ "id": "rd_8f3ac1", "status": "offered", "offeredTo": "drv_44c1" }

Webhook: ride.status_changed

Subject: delivered whenever a ride you created or were offered changes status.

Verifying a webhook

Subject: header X-TaxiID-Signature: t=<unix>,v1=<hex hmac> — HMAC-SHA256 over ${t}.${rawBody} using your webhook secret. Reject stale timestamps.

Ride creation

Calls for integrations that book rides on behalf of a passenger or company.

POST /v1/quotes

Subject: get a price quote for a route before booking.

cURL

curl -X POST https://integrations.taxiid.nl/v1/quotes \
  -H "Authorization: Bearer $TAXIID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "origin": {"lat": 52.3105, "lng": 4.7683},
        "destination": {"lat": 52.3762, "lng": 4.8952},
        "requestedDate": "2026-09-20T14:30:00Z"
      }'

Request

{
  "origin": { "lat": 52.3105, "lng": 4.7683 },
  "destination": { "lat": 52.3762, "lng": 4.8952 },
  "requestedDate": "2026-09-20T14:30:00Z"
}

Response

{ "quoteId": "qt_2a91f", "price": { "total": 4850, "currency": "EUR" }, "expiresAt": "2026-09-20T14:45:00Z" }

POST /v1/rides

Subject: create a new ride booking.

cURL

curl -X POST https://integrations.taxiid.nl/v1/rides \
  -H "Authorization: Bearer $TAXIID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "quoteId": "qt_2a91f",
        "requestedDate": "2026-09-20T14:30:00Z",
        "passenger": {"name": "J. de Vries", "phone": "+31612345678"},
        "origin": {"address": "Schiphol Airport, Plaza 1", "lat": 52.3105, "lng": 4.7683},
        "destination": {"address": "Damrak 1, Amsterdam", "lat": 52.3762, "lng": 4.8952}
      }'

Request

{
  "quoteId": "qt_2a91f",
  "requestedDate": "2026-09-20T14:30:00Z",
  "passenger": { "name": "J. de Vries", "phone": "+31612345678" },
  "origin": { "address": "Schiphol Airport, Plaza 1", "lat": 52.3105, "lng": 4.7683 },
  "destination": { "address": "Damrak 1, Amsterdam", "lat": 52.3762, "lng": 4.8952 }
}

Response

{
  "id": "rd_8f3ac1",
  "status": "requested",
  "requestedDate": "2026-09-20T14:30:00Z",
  "price": { "total": 4850, "currency": "EUR" }
}

POST /v1/rides/{id}/cancel

Subject: cancel an existing ride.

Webhook: ride.created

Subject: delivered when a ride you created is accepted into the system.

Webhook: ride.updated

Subject: delivered on other ride field changes. Off by default — enable it in the portal if you need it; it is noisier than ride.status_changed.

Generated from the source Markdown · run ./generate.sh to rebuild.

#taxiID Integration API

#Objects

#Ride

#Address

#Passenger

#Price

#PaymentMeta

#Webhook envelope

#Administration

#Authentication

#GET /v1/me

#Rate limits

#Errors

#Webhooks setup

#Dispatch

#GET /v1/rides

#GET /v1/rides/{id}

#POST /v1/rides/{id}/offer

#Webhook: ride.status_changed

#Verifying a webhook

#Ride creation

#POST /v1/quotes

#POST /v1/rides

#POST /v1/rides/{id}/cancel

#Webhook: ride.created

#Webhook: ride.updated

taxiID Integration API

Objects

Ride

Address

Passenger

Price

PaymentMeta

Webhook envelope

Administration

Authentication

GET /v1/me

Rate limits

Errors

Webhooks setup

Dispatch

GET /v1/rides

GET /v1/rides/{id}

POST /v1/rides/{id}/offer

Webhook: ride.status_changed

Verifying a webhook

Ride creation

POST /v1/quotes

POST /v1/rides

POST /v1/rides/{id}/cancel

Webhook: ride.created

Webhook: ride.updated