Skip to content

Conventions

Dates and time zones, IDs, pagination, request IDs and rate limits across the Transferz APIs.

Updated · 3 min read

These rules apply to every Transferz API. Read them once before you write your client.

Requests and responses

  • Send and expect JSON (Content-Type: application/json, Accept: application/json), over HTTPS.
  • Field names are in camelCase, such as pickupDateTime. Enum values are in upper case with underscores, such as DRIVER_UNDERWAY; the Constants guide explains each value.
  • IDs such as journeyId and bookingId are 64-bit integers. Store them in a 64-bit type.
  • Ignore fields you do not know. Transferz adds fields to responses and events without notice; your client must not break when it meets one. See Versioning.

Dates and time zones

Date-times have no time-zone offset, for example 2026-12-14T10:30:00 or 2026-11-02T09:14:27.512. Fractional seconds may or may not be present; accept both.

Pickup times are local. A pickup time is the local time at the pickup location. Where an API returns a pickup time, it comes with the time zone of that location. The field is pickupTime on Transfer Companies API journeys and pickup on Partners API journeys:

JSON
{ "pickupTime": { "localTime": "2026-12-14T10:30:00", "timeZone": "Europe/Amsterdam" } }

When you send a pickup time, such as pickupDateTime in a quote request, send the local time at the pickup location. Do not convert it to UTC or to your own time zone. Show it to travellers and drivers as it is.

Other timestamps, such as created in webhook events or expires on a quote, also have no offset.

Pagination

Two Transfer Companies API searches return results in pages: Search journeys and Search actions. Partners API calls are not paginated.

ParameterMeaning
pagePage number, starting at 0.
sizeResults per page. Default 10. At most 100 for journeys; larger fails with MAX_PAGE_SIZE_LIMIT_EXCEEDED.
sortOptional, repeatable: a field and a direction joined by a semicolon, such as pickup;asc.

The response has the results and a pagination object:

GET/journeysReference
Sign in to fill in your staging key. Sign in
curl --request GET \  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys?page=1&size=50&sort=pickup;asc' \  --header 'Accept: application/json' \  --header 'X-API-Key: YOUR_STAGING_API_KEY'
Response 200
{  "pagination": { "currentPage": 1, "pageSize": 50, "totalPages": 3, "totalResults": 128 },  "results": []}

Request pages until currentPage is totalPages - 1. Results can change between two pages; to pick up changes since your last run, filter journeys on updatedAfter instead of paging through everything again.

Request IDs

Every operation accepts an optional X-Request-ID header. Generate a unique value per request, such as a UUID, send it, and log it next to your own request:

HTTP
X-Request-ID: 3f6c1a52-8e0b-4d7e-9a61-2b5f0c9d4e17

Transferz records it with the request. When you report a problem, give the request ID so Transferz can find the call. The header is not echoed in the response.

Rate limits

Transferz does not publish a rate limit. Be considerate anyway: prefer webhooks over polling, and when you poll, keep it to what you need.

Retrying requests

Retry only when it is safe:

  • Retry 5xx responses and network errors with increasing waits, for example 1, 2, 4 and 8 seconds.
  • Do not retry 4xx responses unchanged; fix the request first.
  • GET calls are safe to retry. Before retrying a call that creates something, such as a booking, check whether the first attempt succeeded, so you do not create it twice.

Was this helpful?

Back to your build path →