# Search for transfers

Search for transfer options that match the specified route, pick-up date and time, and number of passengers.
The response includes vehicle options, estimated prices, cancellation policies, and Booking.com redirect URLs for completing the booking.
**Availability and pricing:** Search results are based on predicted availability and pricing. The actual options and prices may differ when the traveller follows the redirect URL. In some cases, no options may be available on Booking.com.
**Beta endpoint:** This endpoint is part of the Demand API Beta collection. Its request and response structures may change, including breaking changes. See the [Changelog](/demand/docs/whats-new/changelog) for the latest enhancements.

Endpoint: POST /transfers/search
Version: beta
Security: BearerAuth

## Security:

  - `BearerAuth` (unknown)
    http bearer string

## Header parameters:

  - `X-Affiliate-Id` (integer, required)
    Include here your Affiliate identifier number

## Request fields (application/json):

  - `route` (object, required)
    The route for the transfer journey. A route contains one leg for a one-way journey or two legs for a return journey. Every leg must fully specify its own pick-up and drop-off locations, including the return leg. For a return journey, the second leg normally uses the outbound locations in reverse.

  - `route.legs` (array, required)
    The journey legs in travel order. The first leg is the outbound journey. For a return journey, add a second leg whose pick-up location must match the outbound drop-off location, and whose drop-off location must match the outbound pick-up location.

  - `route.legs.pickup` (object, required)
    The pick-up location, date and time for a journey leg.

  - `route.legs.pickup.location` (object, required)
    The pick-up or drop-off location. Specify exactly one of `airport`, `google_place_id` or `coordinates`.

  - `route.legs.pickup.location.airport` (string)
    A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling  common/locations/airports.
    Example: AMS

  - `route.legs.pickup.location.google_place_id` (string)
    A Google Place ID that uniquely identifies a place.
    Example: ChIJ61zLckBTekgR9ZGwIGR3kas

  - `route.legs.pickup.location.coordinates` (object)

  - `route.legs.pickup.location.coordinates.latitude` (number)

  - `route.legs.pickup.location.coordinates.longitude` (number)

  - `route.legs.pickup.datetime` (string, required)
    The local pick-up date and time, in YYYY-MM-DDTHH:mm:ss format. Do not include a time zone or UTC offset. The API interprets the value using the local time zone of the pick-up location. The date and time must not be in the past. For a return journey, the return pick-up must be later than the outbound pick-up.
    Example: 2026-11-12T10:00:00

  - `route.legs.dropoff` (object, required)
    The drop-off location for a journey leg.

  - `passengers` (integer, required)
    The number of passengers travelling, from 1 to 8. The response only includes vehicles with sufficient passenger capacity.
    Example: 3

  - `currency` (string | null, required)
    A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.
    Example: EUR

  - `language` (string)
    A [IETF language tag code](https://en.wikipedia.org/wiki/IETF_language_tag) that uniquely identifies a supported human language or dialect. **Note:** Demand API only accepts lowercase for the language codes. Examples: "nl" for Dutch/Nederlands or "en-us" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint.
    Example: en-us

  - `booker` (object, required)
    Defines the booker context.

  - `booker.country` (string, required)
    A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling the /common/locations/countries endpoint.
    Example: nl

## Request examples:

  - `One-way journey from an airport to coordinates` (unknown)

  - `Return journey between an airport and a Google Place (airport hotel)` (unknown)

  - `One-way journey from coordinates to an airport` (unknown)

  - `One-way journey between two Google Places` (unknown)

  - `Return journey between coordinates` (unknown)

## Response 200:

  - `200` (unknown)
    Successful response.

## Response 200 fields (application/json):

  - `request_id` (string, required)
    Uniquely identifies the request. Please provide this identifier when contacting support.

  - `data` (object, required)
    The transfer details, including the route, available vehicle options, prices and cancellation policy.

  - `data.currency` (string | null, required)
    A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.
    Example: EUR

  - `data.expires_at` (string, required)
    The date and time when the search results expire. After this time, prices and availability may change.
    Example: 2026-11-11T10:30:00Z

  - `data.route` (object, required)
    The route of the journey, containing its journey legs.

  - `data.route.legs` (array, required)
    The journey legs in travel order. A one-way journey has one leg; a return journey has an outbound and return leg.

  - `data.route.legs.pickup` (object, required)
    The pick-up location and scheduled date and time for a journey leg.

  - `data.route.legs.pickup.datetime` (string, required)
    The local pick-up date and time, in YYYY-MM-DDTHH:mm:ss format. The value does not include a time zone or UTC offset and is interpreted using the local time zone of the pick-up location.
    Example: 2026-11-12T10:00:00

  - `data.route.legs.pickup.location` (object, required)
    Details of a resolved pick-up or drop-off location, including its address and geographic coordinates.

  - `data.route.legs.pickup.location.name` (string, required)
    The display name of the location.
    Example: Amsterdam Airport Schiphol (AMS)

  - `data.route.legs.pickup.location.address` (string, required)
    Full street address of the location, suitable for display.
    Example: Evert van de Beekstraat 202, 1118 CP Schiphol, Netherlands

  - `data.route.legs.pickup.location.city` (string | null)
    City where the location is situated. `null` when the resolved location carries no city, which happens for some airports.
    Example: Amsterdam

  - `data.route.legs.pickup.location.country` (string, required)
    A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling the /common/locations/countries endpoint.
    Example: nl

  - `data.route.legs.pickup.location.coordinates` (object, required)

  - `data.route.legs.pickup.location.coordinates.latitude` (number)

  - `data.route.legs.pickup.location.coordinates.longitude` (number)

  - `data.route.legs.pickup.location.iata` (string | null)
    IATA airport code of the location. Returned only when the request specified this location by airport code (`airport`). `null` when the location was specified by `google_place_id` or `coordinates`, even if it resolves to an airport.
    Example: AMS

  - `data.route.legs.dropoff` (object, required)
    The drop-off location for a journey leg. The estimated drop-off time can be derived from the pick-up time and journey duration.

  - `data.route.legs.duration_minutes` (integer | null)
    Estimated travel time for this leg, in minutes. Returns `null` when the transfer search does not provide a time estimate.

  - `data.route.legs.distance_km` (number | null)
    Estimated distance for this leg, in kilometres. Returns `null` when the transfer search does not provide a distance estimate.

  - `data.vehicle_options` (array, required)
    Available vehicle types for the trip, each with pricing and a redirect URL. For round trips, the price is the total for both legs combined. Options are sorted by price, cheapest first.

  - `data.vehicle_options.name` (string, required)
    The display name of the vehicle option.
    Example: Standard

  - `data.vehicle_options.max_passengers` (integer, required)
    Maximum number of passengers this vehicle can accommodate.

  - `data.vehicle_options.max_luggage` (integer, required)
    Maximum number of standard suitcases this vehicle can accommodate.

  - `data.vehicle_options.price` (number, required)

  - `data.vehicle_options.url` (string, required)
    The Booking.com URL for this vehicle option. Redirect the traveller to this URL to complete the booking.

  - `data.cancellation_policy` (object, required)
    The cancellation policy that applies to the available vehicle options. For a return journey, the policy applies to both legs.

  - `data.cancellation_policy.details` (object | null, required)
    The free-cancellation conditions. For example: `duration='PT48H'` and `context=before_pickup` means: free cancellation is available up to 48 hrs before pick up. `null` when free cancellation is not available.

  - `data.cancellation_policy.details.context` (string)
    The context in which the cancellation policy applies.
    Enum: "before_pickup"

  - `data.cancellation_policy.details.duration` (string)
    The free-cancellation window before pick-up, in ISO 8601 duration format. For example, `PT48H` means 48 hours before pick-up.

  - `data.cancellation_policy.type` (string, required)
    The cancellation policy type.
    Enum: "free_cancellation", "non_refundable"

## Response 400:

  - `400` (unknown)
    The request is invalid or missing required parameters. Refer to the [Error handling section](/demand/docs/support/error-handling/about-errors) for more details.

## Response 400 fields (application/json):

  - `request_id` (string, required)
    Uniquely identifies the request. Please provide this identifier when contacting support.

  - `errors` (array, required)

  - `errors.id` (string, required)

  - `errors.message` (string, required)

## Response 500:

  - `500` (unknown)
    Internal server error. Try again later or contact support.

## Response 500 fields (application/json):

  - `request_id` (string, required)
    Uniquely identifies the request. Please provide this identifier when contacting support.

  - `errors` (array, required)

  - `errors.id` (string, required)

  - `errors.message` (string, required)

## Response 200 examples:

  - `One-way journey` (unknown)

  - `Return journey` (unknown)

## Response 400 examples:

  - `Missing parameter` (unknown)

  - `Malformed request` (unknown)

  - `Pick-up date and time in the past` (unknown)

  - `Location could not be resolved` (unknown)

  - `Return pick-up too soon after the outbound pick-up` (unknown)

  - `Pick-up or drop-off location not covered by transfer services` (unknown)

  - `Currency not supported for transfer searches` (unknown)

  - `Return leg without a pick-up location` (unknown)

  - `Return leg without a drop-off` (unknown)

  - `Return leg locations do not mirror the outbound leg` (unknown)

  - `Return pick-up not later than the outbound pick-up` (unknown)

## Response 500 examples:

  - `Generic server error` (unknown)