POST/v1/transfers/search
API console
Try it
Send a real request to the sandbox API and inspect the response.
Credentials
Log in to pick from your saved API keys instead of pasting them.
Request body
cURL request
bash
curl -X POST 'https://api.sandbox.travelandz.com/v1/transfers/search' \
-H 'Authorization: Bearer YOUR_SECRET_KEY' \
-H 'X-Travelandz-Id: YOUR_PUBLIC_KEY:YOUR_PROFILE_CODE' \
-H 'Content-Type: application/json' \
-d '{"mode":"one_way","startAddress":"433 Park Ave","startCity":"New York","startZipcode":"10022","endAddress":"JFK","pickupDatetime":"2026-08-16 15:30","numPassengers":2,"currency":"USD","responseMode":"complete"}'Add your credentials to send a request.
Response
Click "Try it!" to send a request and see the response here.
Search transfer offers and receive a complete JSON response or progressive stream events.
Authentication and headers
| Header | Description |
|---|---|
Authorization | Bearer <secret_key>. Keep the secret on the server and never write it to client logs. |
X-Travelandz-Id | <public_key>:<profile_code>, where the persisted profile code has the form dp_<12 alphanumeric>. |
LANG | Preferred locale header. Accept-Language is also supported. |
Content-Type | application/json for requests with a JSON body. |
Request
Send mode and numPassengers. Origin and destination each need an address, a place ID, or a latitude/longitude pair. Set responseMode to stream to receive offers as they arrive instead of one final response. A round_trip search also requires returnPickupDatetime or returnFlightDatetime.
Request Body Schema
moderesponseModeDefaults to
complete.numPassengersInteger from 1 to 99.
startAddressSend an address, a place ID, or a latitude/longitude pair for the origin.
startCityAppended to the address to improve resolution.
startZipcodeAppended to the address to improve resolution.
startLatMust be sent together with
startLng.startLngMust be sent together with
startLat.startPlaceIdAlternative to an address or coordinates.
endAddressSend an address, a place ID, or a latitude/longitude pair for the destination.
endCityAppended to the address to improve resolution.
endZipcodeAppended to the address to improve resolution.
endLatMust be sent together with
endLng.endLngMust be sent together with
endLat.endPlaceIdAlternative to an address or coordinates.
pickupDatetimeLocal date and time at the origin.
flightDatetimeflightTypereturnPickupDatetimeA
round_trip search requires this field or returnFlightDatetime.returnFlightDatetimeA
round_trip search requires this field or returnPickupDatetime.amenitiesamenities[]Amenity keys to bias the search. Also accepted as a CSV string.
currencyLowercase values are accepted and normalized. Defaults to
USD on a new search and is inherited afterwards.campaignYour own campaign context.
branchRequires
campaign when sent.languageLegacy field. Prefer the
LANG or Accept-Language header.Request example
Complete response
json
{
"mode": "one_way",
"startAddress": "433 Park Ave",
"startCity": "New York",
"startZipcode": "10022",
"endAddress": "JFK",
"pickupDatetime": "2026-08-16 15:30",
"numPassengers": 2,
"currency": "USD",
"responseMode": "complete"
}Stream response
json
{
"mode": "one_way",
"startAddress": "433 Park Ave, New York",
"endAddress": "JFK",
"pickupDatetime": "2026-08-16 15:30",
"numPassengers": 2,
"currency": "USD",
"responseMode": "stream"
}Success response
Returns transfers[] with the offers that can be priced and booked, plus metadata describing the resolved locations and whether the result set is final. Each offer carries an opaque bookingToken that you copy into pricing.
A search can return 200 with metadata.timedOut: true. That is not an error: the offers already present are valid and bookable.
Response Body Schema
transferstransfers[]searchIdSend this value in pricing, booking and reservation reads.
transfers[]gdsprovidertransfers[]resultIdIdentifies the selected offer.
transfers[]bookingTokenOpaque value. Copy it into pricing and booking; never decode or modify it.
transfers[]expiresAtThe offer and its token stop being usable after this moment.
transfers[]vehicleIdtransfers[]totalAmountIndicative total for the offer in
currency.transfers[]currencytransfers[]bookableFalse when the offer cannot be booked.
transfers[]flightInfoRequiredWhen true,
airline and flightNumber are required to book.transfers[]extraPaxRequiredWhen true,
extraPaxInfo is required to book.transfers[]goodToKnowInfotransfers[]goodToKnowInfo[]Localized operational notes to show the traveller.
transfers[]supportstransfers[]cancellationPoliciestransfers[]cancellationPolicies[]noticeHours of notice the policy requires.
transfers[]cancellationPolicies[]refundPercenttransfers[]cancellationPolicies[]refundableUntilDatetimetransfers[]cancellationPolicies[]refundAmountRefundable amount in the offer currency.
transfers[]cancellationPolicies[]currencytransfers[]stepstransfers[]steps[]stepTypeLeg type, for example
car.transfers[]steps[]mainTrue for the primary leg of the transfer.
transfers[]steps[]descriptiontransfers[]steps[]departureDatetimetransfers[]steps[]durationMinutestransfers[]steps[]durationSecondstransfers[]steps[]distanceMeterstransfers[]steps[]distanceMilestransfers[]steps[]lineNamePresent for scheduled line transport.
transfers[]steps[]lineColortransfers[]steps[]providertransfers[]steps[]providernametransfers[]steps[]providerratingtransfers[]steps[]vehicletransfers[]steps[]vehicletypeVehicle name, for example
Shared Ride Van.transfers[]steps[]vehiclecategoryVehicle grouping, for example
Shared or Private.transfers[]steps[]vehiclemaxBagstransfers[]steps[]vehiclemaxPassengerstransfers[]steps[]vehiclenumVehiclestransfers[]steps[]vehicleimageUrltransfers[]steps[]waitTimetransfers[]steps[]waitTimeincludedtransfers[]steps[]waitTimeminutesIncludedtransfers[]steps[]waitTimeextraWaitTimeChargeabletransfers[]steps[]amenitiestransfers[]steps[]amenities[]keyValue to send in
selectedAmenities.transfers[]steps[]amenities[]nameLocalized name.
transfers[]steps[]amenities[]descriptiontransfers[]steps[]amenities[]imageUrltransfers[]steps[]amenities[]pngImageUrltransfers[]steps[]amenities[]inputTypetransfers[]steps[]amenities[]includedTrue when the amenity is already part of the offer.
transfers[]steps[]amenities[]selectableTrue when the amenity can be added to this offer.
transfers[]steps[]amenities[]selectedTrue when the amenity is part of the priced selection.
transfers[]steps[]startLocationtransfers[]steps[]startLocationformattedAddresstransfers[]steps[]startLocationfullAddresstransfers[]steps[]startLocationiataCodePresent for airport locations.
transfers[]steps[]startLocationicaoCodetransfers[]steps[]startLocationplaceIdReusable place identifier; send it back to skip geocoding.
transfers[]steps[]startLocationlatitudetransfers[]steps[]startLocationlongitudetransfers[]steps[]startLocationtimezoneIANA timezone of the location.
transfers[]steps[]endLocationtransfers[]steps[]endLocationformattedAddresstransfers[]steps[]endLocationfullAddresstransfers[]steps[]endLocationiataCodePresent for airport locations.
transfers[]steps[]endLocationicaoCodetransfers[]steps[]endLocationplaceIdReusable place identifier; send it back to skip geocoding.
transfers[]steps[]endLocationlatitudetransfers[]steps[]endLocationlongitudetransfers[]steps[]endLocationtimezoneIANA timezone of the location.
transfers[]ticketTypestransfers[]ticketTypes[]idSend this value in
ticketTypes[].id when booking.transfers[]ticketTypes[]nametransfers[]ticketTypes[]departureDatetimetransfers[]ticketTypes[]arrivalDatetimetransfers[]alternativeTimestransfers[]alternativeTimes[]departureDatetimetransfers[]alternativeTimes[]arrivalDatetimemetadatametadatacompletedTrue when the result set is final.
metadatatimedOutTrue when results were returned before every source finished. The offers already present are valid.
metadataproviderResultsmetadataproviderResults[]gdsprovidermetadataproviderResults[]searchIdmetadataproviderResults[]completedTrue when this source has no further offers to return.
metadataproviderResults[]timedOutmetadataproviderResults[]moreComingTrue when more offers may still arrive for this
searchId.metadatastartLocationmetadatastartLocationformattedAddressmetadatastartLocationfullAddressmetadatastartLocationiataCodePresent for airport locations.
metadatastartLocationicaoCodemetadatastartLocationplaceIdReusable place identifier; send it back to skip geocoding.
metadatastartLocationlatitudemetadatastartLocationlongitudemetadatastartLocationtimezoneIANA timezone of the location.
metadataendLocationmetadataendLocationformattedAddressmetadataendLocationfullAddressmetadataendLocationiataCodePresent for airport locations.
metadataendLocationicaoCodemetadataendLocationplaceIdReusable place identifier; send it back to skip geocoding.
metadataendLocationlatitudemetadataendLocationlongitudemetadataendLocationtimezoneIANA timezone of the location.
metadatapickupDatetimeResolved pickup moment in the origin timezone.
metadatanumPassengersResponse Body Schema (responseMode=stream)
transferstransfers[]searchIdSend this value in pricing, booking and reservation reads.
transfers[]gdsprovidertransfers[]resultIdIdentifies the selected offer.
transfers[]bookingTokenOpaque value. Copy it into pricing and booking; never decode or modify it.
transfers[]expiresAtThe offer and its token stop being usable after this moment.
transfers[]vehicleIdtransfers[]totalAmountIndicative total for the offer in
currency.transfers[]currencytransfers[]bookableFalse when the offer cannot be booked.
transfers[]flightInfoRequiredWhen true,
airline and flightNumber are required to book.transfers[]extraPaxRequiredWhen true,
extraPaxInfo is required to book.transfers[]goodToKnowInfotransfers[]goodToKnowInfo[]Localized operational notes to show the traveller.
transfers[]supportstransfers[]cancellationPoliciestransfers[]cancellationPolicies[]noticeHours of notice the policy requires.
transfers[]cancellationPolicies[]refundPercenttransfers[]cancellationPolicies[]refundableUntilDatetimetransfers[]cancellationPolicies[]refundAmountRefundable amount in the offer currency.
transfers[]cancellationPolicies[]currencytransfers[]stepstransfers[]steps[]stepTypeLeg type, for example
car.transfers[]steps[]mainTrue for the primary leg of the transfer.
transfers[]steps[]descriptiontransfers[]steps[]departureDatetimetransfers[]steps[]durationMinutestransfers[]steps[]durationSecondstransfers[]steps[]distanceMeterstransfers[]steps[]distanceMilestransfers[]steps[]lineNamePresent for scheduled line transport.
transfers[]steps[]lineColortransfers[]steps[]providertransfers[]steps[]providernametransfers[]steps[]providerratingtransfers[]steps[]vehicletransfers[]steps[]vehicletypeVehicle name, for example
Shared Ride Van.transfers[]steps[]vehiclecategoryVehicle grouping, for example
Shared or Private.transfers[]steps[]vehiclemaxBagstransfers[]steps[]vehiclemaxPassengerstransfers[]steps[]vehiclenumVehiclestransfers[]steps[]vehicleimageUrltransfers[]steps[]waitTimetransfers[]steps[]waitTimeincludedtransfers[]steps[]waitTimeminutesIncludedtransfers[]steps[]waitTimeextraWaitTimeChargeabletransfers[]steps[]amenitiestransfers[]steps[]amenities[]keyValue to send in
selectedAmenities.transfers[]steps[]amenities[]nameLocalized name.
transfers[]steps[]amenities[]descriptiontransfers[]steps[]amenities[]imageUrltransfers[]steps[]amenities[]pngImageUrltransfers[]steps[]amenities[]inputTypetransfers[]steps[]amenities[]includedTrue when the amenity is already part of the offer.
transfers[]steps[]amenities[]selectableTrue when the amenity can be added to this offer.
transfers[]steps[]amenities[]selectedTrue when the amenity is part of the priced selection.
transfers[]steps[]startLocationtransfers[]steps[]startLocationformattedAddresstransfers[]steps[]startLocationfullAddresstransfers[]steps[]startLocationiataCodePresent for airport locations.
transfers[]steps[]startLocationicaoCodetransfers[]steps[]startLocationplaceIdReusable place identifier; send it back to skip geocoding.
transfers[]steps[]startLocationlatitudetransfers[]steps[]startLocationlongitudetransfers[]steps[]startLocationtimezoneIANA timezone of the location.
transfers[]steps[]endLocationtransfers[]steps[]endLocationformattedAddresstransfers[]steps[]endLocationfullAddresstransfers[]steps[]endLocationiataCodePresent for airport locations.
transfers[]steps[]endLocationicaoCodetransfers[]steps[]endLocationplaceIdReusable place identifier; send it back to skip geocoding.
transfers[]steps[]endLocationlatitudetransfers[]steps[]endLocationlongitudetransfers[]steps[]endLocationtimezoneIANA timezone of the location.
transfers[]ticketTypestransfers[]ticketTypes[]idSend this value in
ticketTypes[].id when booking.transfers[]ticketTypes[]nametransfers[]ticketTypes[]departureDatetimetransfers[]ticketTypes[]arrivalDatetimetransfers[]alternativeTimestransfers[]alternativeTimes[]departureDatetimetransfers[]alternativeTimes[]arrivalDatetimemetadatametadatacompletedTrue when the result set is final.
metadatatimedOutTrue when results were returned before every source finished. The offers already present are valid.
metadataproviderResultsmetadataproviderResults[]gdsprovidermetadataproviderResults[]searchIdmetadataproviderResults[]completedTrue when this source has no further offers to return.
metadataproviderResults[]timedOutmetadataproviderResults[]moreComingTrue when more offers may still arrive for this
searchId.metadatastartLocationmetadatastartLocationformattedAddressmetadatastartLocationfullAddressmetadatastartLocationiataCodePresent for airport locations.
metadatastartLocationicaoCodemetadatastartLocationplaceIdReusable place identifier; send it back to skip geocoding.
metadatastartLocationlatitudemetadatastartLocationlongitudemetadatastartLocationtimezoneIANA timezone of the location.
metadataendLocationmetadataendLocationformattedAddressmetadataendLocationfullAddressmetadataendLocationiataCodePresent for airport locations.
metadataendLocationicaoCodemetadataendLocationplaceIdReusable place identifier; send it back to skip geocoding.
metadataendLocationlatitudemetadataendLocationlongitudemetadataendLocationtimezoneIANA timezone of the location.
metadatapickupDatetimeResolved pickup moment in the origin timezone.
metadatanumPassengerserrorPresent on an
error event.errorCodePresent on an
error event.Response examples
json
{
"transfers": [
{
"searchId": "5c8563a5d31d4c33a3a1eafbbfe59c4b",
"gdsprovider": 0,
"resultId": "763475651c06f5ac31ea587084dc0629",
"bookingToken": "opaque_offer_token_generated_by_travelandz",
"expiresAt": "2026-08-05T21:20:00.000Z",
"totalAmount": 49.84,
"currency": "USD",
"bookable": true,
"flightInfoRequired": true,
"extraPaxRequired": false,
"goodToKnowInfo": [],
"cancellationPolicies": [
{
"notice": 48,
"refundPercent": 100,
"refundableUntilDatetime": "2026-08-14T14:40:00-04:00",
"refundAmount": 49.84,
"currency": "USD"
}
],
"supports": {},
"steps": [
{
"stepType": "car",
"main": true,
"departureDatetime": "2026-08-16T14:40:00-04:00",
"durationMinutes": 26,
"distanceMeters": 25749,
"provider": {
"name": "GO Airlink NYC",
"rating": 5
},
"vehicle": {
"type": "Shared Ride Van",
"category": "Shared",
"maxBags": 4,
"maxPassengers": 11,
"numVehicles": 1
},
"waitTime": {
"included": false,
"minutesIncluded": 0,
"extraWaitTimeChargeable": false
},
"amenities": []
}
],
"ticketTypes": [],
"alternativeTimes": [
{
"departureDatetime": "2026-08-16T14:40:00-04:00",
"arrivalDatetime": "2026-08-16T15:06:10-04:00"
},
{
"departureDatetime": "2026-08-16T13:40:00-04:00",
"arrivalDatetime": "2026-08-16T14:06:10-04:00"
}
]
}
],
"metadata": {
"completed": true,
"timedOut": false,
"providerResults": [
{
"gdsprovider": 0,
"searchId": "5c8563a5d31d4c33a3a1eafbbfe59c4b",
"completed": true,
"timedOut": false,
"moreComing": false
}
],
"startLocation": {
"formattedAddress": "433 Park Ave, New York, NY 10022, USA",
"fullAddress": "433 Park Ave, New York",
"placeId": "EiU0MzMgUGFyayBBdmUsIE5ldyBZb3JrLCBOWSAxMDAyMiwgVVNB",
"latitude": 40.7607634,
"longitude": -73.971212,
"timezone": "America/New_York"
},
"endLocation": {
"formattedAddress": "John F Kennedy International Airport",
"fullAddress": "John F Kennedy International Airport",
"iataCode": "JFK",
"icaoCode": "KJFK",
"latitude": 40.639751,
"longitude": -73.778926,
"timezone": "America/New_York"
},
"pickupDatetime": "2026-08-16T15:30:00-04:00",
"numPassengers": 2
}
}Stream events
| Event | Description |
|---|---|
provider_search_created | The search was accepted. Carries the first offers, if any are already available. |
provider_poll_result | An updated set of offers. Replace what you were showing with the payload of the latest event. |
provider_done | A source finished contributing offers. |
error | The stream could not continue. Carries error and errorCode. |
done | Final combined result. Close the connection when you receive it. |
Stream example
text
event: provider_search_created
data: {"transfers":[],"metadata":{"completed":false,"timedOut":false,"providerResults":[{"gdsprovider":0,"searchId":"5c8563a5d31d4c33a3a1eafbbfe59c4b","moreComing":true}]}}
event: provider_poll_result
data: {"transfers":[{"searchId":"5c8563a5d31d4c33a3a1eafbbfe59c4b","resultId":"763475651c06f5ac31ea587084dc0629","totalAmount":49.84,"currency":"USD"}],"metadata":{"completed":false,"timedOut":false,"providerResults":[{"gdsprovider":0,"moreComing":true}]}}
event: provider_done
data: {"transfers":[{"searchId":"5c8563a5d31d4c33a3a1eafbbfe59c4b","resultId":"763475651c06f5ac31ea587084dc0629","totalAmount":49.84,"currency":"USD"}],"metadata":{"completed":true,"timedOut":false,"providerResults":[{"gdsprovider":0,"completed":true,"moreComing":false}]}}
event: done
data: {"transfers":[{"searchId":"5c8563a5d31d4c33a3a1eafbbfe59c4b","resultId":"763475651c06f5ac31ea587084dc0629","totalAmount":49.84,"currency":"USD"}],"metadata":{"completed":true,"timedOut":false,"providerResults":[{"gdsprovider":0,"completed":true,"moreComing":false}]}}Errors
| HTTP | Code | Meaning | Recommended action |
|---|---|---|---|
400 | The body, query or path is invalid, or contains an unknown property. | Fix the request using the message array. | |
400 | transfer_invalid_currency | The currency is outside the supported list. | Use a supported currency. |
400 | transfer_invalid_language | The requested language is not supported. | Use one of the documented language values. |
429 | transfer_provider_error | The service is temporarily rate limited. | Retry with exponential backoff. |
502 | transfer_provider_error | The request could not be completed. | Do not assume success. Keep your identifiers and read the reservation when the operation could have been created. |
400 | transfer_location_not_found | An origin or destination could not be resolved. | Add a city or zipcode, or send a place ID or a coordinate pair. |
503 | The price could not be confirmed right now. | Retry later. Do not book and do not charge the traveller. |
Usage notes
If every source fails before the stream opens, the request fails with a normal JSON HTTP error. If the stream already started, the failure arrives as an error event instead. Close stream connections explicitly when you no longer need them.
Persist searchId, resultId and bookingToken for the offer the traveller selects: pricing, booking and reservation reads all need them.
cURL example
bash
curl --request POST \
--url "https://api.sandbox.travelandz.com/v1/transfers/search" \
-H "Authorization: Bearer $TRAVELANDZ_SECRET_KEY" \
-H "X-Travelandz-Id: $TRAVELANDZ_PUBLIC_KEY:$TRAVELANDZ_PROFILE_CODE" \
-H "Content-Type: application/json" \
--data '{
"mode": "one_way",
"startAddress": "433 Park Ave",
"startCity": "New York",
"startZipcode": "10022",
"endAddress": "JFK",
"pickupDatetime": "2026-08-16 15:30",
"numPassengers": 2,
"currency": "USD",
"responseMode": "complete"
}'