# Conventions

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

Section: Essentials · Last updated: 2026-11-15

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](https://developers.test.transferz.com/guides/essentials/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](https://developers.test.transferz.com/guides/essentials/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.

> **To be confirmed by Transferz:** The time zone of timestamps such as `created` and `expires` is still to be confirmed by Transferz.

## Pagination

Two Transfer Companies API searches return results in pages:
[Search journeys](https://developers.test.transferz.com/reference/transfer-companies/search-journeys) and [Search actions](https://developers.test.transferz.com/reference/transfer-companies/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:

**Request:** [`GET /journeys`](https://developers.test.transferz.com/reference/transfer-companies/search-journeys)

```bash title="cURL"
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'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys?page=1&size=50&sort=pickup;asc", {
  method: "GET",
  headers: {
    Accept: "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
});

const data = await response.json();
console.log(response.status, data);
```

```java title="Java"
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("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")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}
```

```csharp title="C#"
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://warpdrive.staging.transferz.com/transfercompanies/journeys?page=1&size=50&sort=pickup;asc");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```php title="PHP"
<?php

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/journeys?page=1&size=50&sort=pickup;asc');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

echo $status, PHP_EOL, $response, PHP_EOL;
```

**Response (200):**

```json
{
  "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.

> **To be confirmed by Transferz:** Whether there are rate limits, and their values, is still to be confirmed by Transferz.

## 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.

## Related

### Endpoints

- [GET Search journeys](https://developers.test.transferz.com/reference/transfer-companies/search-journeys) (`GET /journeys`)
- [GET Search actions](https://developers.test.transferz.com/reference/transfer-companies/search-actions) (`GET /actions`)
