# Suggest a pickup time

> Ask Transferz for a suggested pickup time based on the traveller's flight.

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

You will get a pickup time that fits the traveller's flight, and use it to request quotes. You need
the route and the flight's arrival or departure time; the flight number makes the suggestion more
accurate. Call this before [Request quotes](https://developers.test.transferz.com/guides/partners/request-quotes), because the quote
request needs the pickup time.

## Step 1: Ask for a suggestion

Send the route and the flight to [Suggest pickup time](https://developers.test.transferz.com/reference/partners/suggest-pickup-time). For a
traveller landing at Schiphol on flight TZ1234 at 13:40:

**Request:** [`POST /quotes/suggest-pickup-time`](https://developers.test.transferz.com/reference/partners/suggest-pickup-time)

```bash title="cURL"
curl --request POST \
  --url 'https://warpdrive.staging.transferz.com/partners/quotes/suggest-pickup-time' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY' \
  --data '{
  "origin": {
    "iataCode": "AMS"
  },
  "destination": {
    "address": {
      "addressSearchPhrase": "Herengracht 182, Amsterdam",
      "countryCode": "NL"
    }
  },
  "departureOrArrivalTime": "2026-12-01T13:40:00",
  "travelType": "INTERNATIONAL",
  "roundToNearestMinutes": 15,
  "flightNumber": "TZ1234"
}'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/partners/quotes/suggest-pickup-time", {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
  body: JSON.stringify({
    "origin": {
      "iataCode": "AMS"
    },
    "destination": {
      "address": {
        "addressSearchPhrase": "Herengracht 182, Amsterdam",
        "countryCode": "NL"
      }
    },
    "departureOrArrivalTime": "2026-12-01T13:40:00",
    "travelType": "INTERNATIONAL",
    "roundToNearestMinutes": 15,
    "flightNumber": "TZ1234"
  }),
});

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 {
    String body = """
        {
          "origin": {
            "iataCode": "AMS"
          },
          "destination": {
            "address": {
              "addressSearchPhrase": "Herengracht 182, Amsterdam",
              "countryCode": "NL"
            }
          },
          "departureOrArrivalTime": "2026-12-01T13:40:00",
          "travelType": "INTERNATIONAL",
          "roundToNearestMinutes": 15,
          "flightNumber": "TZ1234"
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/partners/quotes/suggest-pickup-time"))
        .header("Accept", "application/json")
        .header("Content-Type", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("POST", HttpRequest.BodyPublishers.ofString(body))
        .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.Post, "https://warpdrive.staging.transferz.com/partners/quotes/suggest-pickup-time");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

var json = """
    {
      "origin": {
        "iataCode": "AMS"
      },
      "destination": {
        "address": {
          "addressSearchPhrase": "Herengracht 182, Amsterdam",
          "countryCode": "NL"
        }
      },
      "departureOrArrivalTime": "2026-12-01T13:40:00",
      "travelType": "INTERNATIONAL",
      "roundToNearestMinutes": 15,
      "flightNumber": "TZ1234"
    }
    """;
request.Content = new StringContent(json, Encoding.UTF8, "application/json");

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

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

$body = <<<'JSON'
{
  "origin": {
    "iataCode": "AMS"
  },
  "destination": {
    "address": {
      "addressSearchPhrase": "Herengracht 182, Amsterdam",
      "countryCode": "NL"
    }
  },
  "departureOrArrivalTime": "2026-12-01T13:40:00",
  "travelType": "INTERNATIONAL",
  "roundToNearestMinutes": 15,
  "flightNumber": "TZ1234"
}
JSON;

$ch = curl_init('https://warpdrive.staging.transferz.com/partners/quotes/suggest-pickup-time');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Content-Type: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

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

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

**Response (200):**

```json
{
  "directionality": "ARRIVAL",
  "suggestedPickupTime": "2026-12-01T14:30:00",
  "distanceInMeters": 19800,
  "durationInMinutes": 26,
  "bufferTime": 50
}
```

What to send:

- **`origin` and `destination`** (required), in the same format as a quote request. One of them must
  be a hub.
- **`departureOrArrivalTime`** (required): the flight's local arrival time when the journey starts
  at the airport, or its local departure time when the journey ends there.
- **`flightNumber`**: when given, Transferz looks the flight up and uses its scheduled time instead
  of `departureOrArrivalTime`, as long as the two are close. Otherwise your time is used.
- **`travelType`**: `INTERNATIONAL` or `DOMESTIC`. It changes the buffer time. If you leave it out,
  Transferz takes it from the flight it found; without a flight a default buffer applies.
- **`roundToNearestMinutes`**: rounds the result down to a multiple of this many minutes, for
  example 15. Leave it out for no rounding.
- **`onlyCarryOnLuggage`**: accepted, but it does not change the result today.

## Step 2: Use the suggested time in the quote request

Send `suggestedPickupTime` as `pickupDateTime` when you
[request quotes](https://developers.test.transferz.com/guides/partners/request-quotes). It is a local time at the pickup location, like
every pickup time. Show it to the traveller so they can change it if they want more or less time.

## How the time is calculated

`directionality` is `ARRIVAL` when the journey starts at the hub and `DEPARTURE` when it ends there.

| Directionality | Suggested pickup time                               | `bufferTime` covers                                              |
| -------------- | --------------------------------------------------- | ---------------------------------------------------------------- |
| `ARRIVAL`      | arrival time + `bufferTime`                         | Getting from the gate to the exit, including baggage and customs |
| `DEPARTURE`    | departure time − `durationInMinutes` − `bufferTime` | Check-in, security and walking to the gate                       |

`bufferTime` and `durationInMinutes` are in minutes; `durationInMinutes` is the expected drive
time. The result is then rounded down to `roundToNearestMinutes`.

For the traveller's return flight, departing from Schiphol at 11:05 with a buffer of 180 minutes and a
26-minute drive, the calculation is 11:05 − 26 − 180 = 07:39, rounded down to 07:30:

**Request:** [`POST /quotes/suggest-pickup-time`](https://developers.test.transferz.com/reference/partners/suggest-pickup-time)

```bash title="cURL"
curl --request POST \
  --url 'https://warpdrive.staging.transferz.com/partners/quotes/suggest-pickup-time' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY' \
  --data '{
  "origin": {
    "address": {
      "addressSearchPhrase": "Herengracht 182, Amsterdam",
      "countryCode": "NL"
    }
  },
  "destination": {
    "iataCode": "AMS"
  },
  "departureOrArrivalTime": "2026-12-08T11:05:00",
  "travelType": "INTERNATIONAL",
  "roundToNearestMinutes": 15,
  "flightNumber": "TZ1235"
}'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/partners/quotes/suggest-pickup-time", {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
  body: JSON.stringify({
    "origin": {
      "address": {
        "addressSearchPhrase": "Herengracht 182, Amsterdam",
        "countryCode": "NL"
      }
    },
    "destination": {
      "iataCode": "AMS"
    },
    "departureOrArrivalTime": "2026-12-08T11:05:00",
    "travelType": "INTERNATIONAL",
    "roundToNearestMinutes": 15,
    "flightNumber": "TZ1235"
  }),
});

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 {
    String body = """
        {
          "origin": {
            "address": {
              "addressSearchPhrase": "Herengracht 182, Amsterdam",
              "countryCode": "NL"
            }
          },
          "destination": {
            "iataCode": "AMS"
          },
          "departureOrArrivalTime": "2026-12-08T11:05:00",
          "travelType": "INTERNATIONAL",
          "roundToNearestMinutes": 15,
          "flightNumber": "TZ1235"
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/partners/quotes/suggest-pickup-time"))
        .header("Accept", "application/json")
        .header("Content-Type", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("POST", HttpRequest.BodyPublishers.ofString(body))
        .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.Post, "https://warpdrive.staging.transferz.com/partners/quotes/suggest-pickup-time");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

var json = """
    {
      "origin": {
        "address": {
          "addressSearchPhrase": "Herengracht 182, Amsterdam",
          "countryCode": "NL"
        }
      },
      "destination": {
        "iataCode": "AMS"
      },
      "departureOrArrivalTime": "2026-12-08T11:05:00",
      "travelType": "INTERNATIONAL",
      "roundToNearestMinutes": 15,
      "flightNumber": "TZ1235"
    }
    """;
request.Content = new StringContent(json, Encoding.UTF8, "application/json");

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

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

$body = <<<'JSON'
{
  "origin": {
    "address": {
      "addressSearchPhrase": "Herengracht 182, Amsterdam",
      "countryCode": "NL"
    }
  },
  "destination": {
    "iataCode": "AMS"
  },
  "departureOrArrivalTime": "2026-12-08T11:05:00",
  "travelType": "INTERNATIONAL",
  "roundToNearestMinutes": 15,
  "flightNumber": "TZ1235"
}
JSON;

$ch = curl_init('https://warpdrive.staging.transferz.com/partners/quotes/suggest-pickup-time');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Content-Type: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

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

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

**Response (200):**

```json
{
  "directionality": "DEPARTURE",
  "suggestedPickupTime": "2026-12-08T07:30:00",
  "distanceInMeters": 19800,
  "durationInMinutes": 26,
  "bufferTime": 180
}
```

The buffer and drive times in these examples are illustrations. The real values depend on the
airport, the travel type and the route.

## Errors

| Problem                                                                                                    | Cause                                                                         | What to do                                                            |
| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `400` with [NO_HUB_SELECTED](https://developers.test.transferz.com/reference/errors/no-hub-selected)       | Neither location is a hub.                                                    | Make the origin or the destination an airport, port or station.       |
| `400` with [LOCATION_NOT_FOUND](https://developers.test.transferz.com/reference/errors/location-not-found) | A location could not be resolved.                                             | Send a fuller address, coordinates or an IATA code.                   |
| `400` with [UNKNOWN](https://developers.test.transferz.com/reference/errors/unknown)                       | The route to the airport could not be calculated.                             | Check the address; if it persists, let the traveller choose the time. |
| `durationInMinutes` and `distanceInMeters` are `0`                                                         | For an arrival, the route could not be calculated; only the buffer was added. | Treat the suggestion as a minimum and let the traveller adjust it.    |
| `400` with a `field`, such as `departureOrArrivalTime`                                                     | A required field is missing.                                                  | Send the field.                                                       |

## Next steps

- [Request quotes](https://developers.test.transferz.com/guides/partners/request-quotes) with the suggested time.
- [Look up the traveller's flight](https://developers.test.transferz.com/guides/partners/request-quotes#look-up-the-travellers-flight)
  to get its scheduled time and flight number.

## Related

### Endpoints

- [POST Suggest pickup time](https://developers.test.transferz.com/reference/partners/suggest-pickup-time) (`POST /quotes/suggest-pickup-time`)
- [POST Request quotes](https://developers.test.transferz.com/reference/partners/request-quotes) (`POST /quotes`)
