Conventions
Dates and time zones, IDs, pagination, request IDs and rate limits across the Transferz APIs.
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 asDRIVER_UNDERWAY; the Constants guide explains each value. - IDs such as
journeyIdandbookingIdare 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:
{ "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.
| Parameter | Meaning |
|---|---|
page | Page number, starting at 0. |
size | Results per page. Default 10. At most 100 for journeys; larger fails with MAX_PAGE_SIZE_LIMIT_EXCEEDED. |
sort | Optional, repeatable: a field and a direction joined by a semicolon, such as pickup;asc. |
The response has the results and a pagination object:
/journeysReferencecurl --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'{ "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:
X-Request-ID: 3f6c1a52-8e0b-4d7e-9a61-2b5f0c9d4e17Transferz 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
5xxresponses and network errors with increasing waits, for example 1, 2, 4 and 8 seconds. - Do not retry
4xxresponses unchanged; fix the request first. GETcalls 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.