POST/v1/transfers/reservations/changes/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/reservations/changes/search' \
-H 'Authorization: Bearer YOUR_SECRET_KEY' \
-H 'X-Travelandz-Id: YOUR_PUBLIC_KEY:YOUR_PROFILE_CODE' \
-H 'Content-Type: application/json' \
-d '{"reservationHashedId":"5c8563a5d31d4c33a3a1eafbbfe59c4b","pickupDatetime":"2026-08-30 22:00","numPassengers":2,"currency":"USD"}'Add your credentials to send a request.
This request needs identifiers or tokens from an earlier call. Run the previous step first, then paste its values here.
Response
Click "Try it!" to send a request and see the response here.
Find replacement offers for an existing reservation.
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
Only reservationHashedId is required. Send just the fields you want to change: everything you omit is taken from the original reservation.
This endpoint always answers with JSON. It never opens a stream.
Request Body Schema
reservationHashedIdIdentifier of the reservation you want to replace.
modenumPassengersWhen sent, an integer of at least 1.
startAddressOptional override of the original location.
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.
endAddressOptional override of the original location.
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.
pickupDatetimeflightDatetimereturnPickupDatetimereturnFlightDatetimeamenitiesamenities[]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
json
{
"reservationHashedId": "5c8563a5d31d4c33a3a1eafbbfe59c4b",
"pickupDatetime": "2026-08-30 22:00",
"numPassengers": 2,
"currency": "USD"
}Success response
Returns a new change searchId and offers[]. The offers have the same shape as a normal search result, including an opaque bookingToken per offer.
Response Body Schema
gdsprovidersearchIdChange search identifier. Send it to pricing and confirmation.
moreComingTrue when more replacement offers may still arrive.
pickupDatetimenumPassengersstartLocationstartLocationformattedAddressstartLocationfullAddressstartLocationiataCodePresent for airport locations.
startLocationicaoCodestartLocationplaceIdReusable place identifier; send it back to skip geocoding.
startLocationlatitudestartLocationlongitudestartLocationtimezoneIANA timezone of the location.
endLocationendLocationformattedAddressendLocationfullAddressendLocationiataCodePresent for airport locations.
endLocationicaoCodeendLocationplaceIdReusable place identifier; send it back to skip geocoding.
endLocationlatitudeendLocationlongitudeendLocationtimezoneIANA timezone of the location.
offersoffers[]searchIdSend this value in pricing, booking and reservation reads.
offers[]gdsprovideroffers[]resultIdIdentifies the selected offer.
offers[]bookingTokenOpaque value. Copy it into pricing and booking; never decode or modify it.
offers[]expiresAtThe offer and its token stop being usable after this moment.
offers[]vehicleIdoffers[]totalAmountIndicative total for the offer in
currency.offers[]currencyoffers[]bookableFalse when the offer cannot be booked.
offers[]flightInfoRequiredWhen true,
airline and flightNumber are required to book.offers[]extraPaxRequiredWhen true,
extraPaxInfo is required to book.offers[]goodToKnowInfooffers[]goodToKnowInfo[]Localized operational notes to show the traveller.
offers[]supportsoffers[]cancellationPoliciesoffers[]cancellationPolicies[]noticeHours of notice the policy requires.
offers[]cancellationPolicies[]refundPercentoffers[]cancellationPolicies[]refundableUntilDatetimeoffers[]cancellationPolicies[]refundAmountRefundable amount in the offer currency.
offers[]cancellationPolicies[]currencyoffers[]stepsoffers[]steps[]stepTypeLeg type, for example
car.offers[]steps[]mainTrue for the primary leg of the transfer.
offers[]steps[]descriptionoffers[]steps[]departureDatetimeoffers[]steps[]durationMinutesoffers[]steps[]durationSecondsoffers[]steps[]distanceMetersoffers[]steps[]distanceMilesoffers[]steps[]lineNamePresent for scheduled line transport.
offers[]steps[]lineColoroffers[]steps[]provideroffers[]steps[]providernameoffers[]steps[]providerratingoffers[]steps[]vehicleoffers[]steps[]vehicletypeVehicle name, for example
Shared Ride Van.offers[]steps[]vehiclecategoryVehicle grouping, for example
Shared or Private.offers[]steps[]vehiclemaxBagsoffers[]steps[]vehiclemaxPassengersoffers[]steps[]vehiclenumVehiclesoffers[]steps[]vehicleimageUrloffers[]steps[]waitTimeoffers[]steps[]waitTimeincludedoffers[]steps[]waitTimeminutesIncludedoffers[]steps[]waitTimeextraWaitTimeChargeableoffers[]steps[]amenitiesoffers[]steps[]amenities[]keyValue to send in
selectedAmenities.offers[]steps[]amenities[]nameLocalized name.
offers[]steps[]amenities[]descriptionoffers[]steps[]amenities[]imageUrloffers[]steps[]amenities[]pngImageUrloffers[]steps[]amenities[]inputTypeoffers[]steps[]amenities[]includedTrue when the amenity is already part of the offer.
offers[]steps[]amenities[]selectableTrue when the amenity can be added to this offer.
offers[]steps[]amenities[]selectedTrue when the amenity is part of the priced selection.
offers[]steps[]startLocationoffers[]steps[]startLocationformattedAddressoffers[]steps[]startLocationfullAddressoffers[]steps[]startLocationiataCodePresent for airport locations.
offers[]steps[]startLocationicaoCodeoffers[]steps[]startLocationplaceIdReusable place identifier; send it back to skip geocoding.
offers[]steps[]startLocationlatitudeoffers[]steps[]startLocationlongitudeoffers[]steps[]startLocationtimezoneIANA timezone of the location.
offers[]steps[]endLocationoffers[]steps[]endLocationformattedAddressoffers[]steps[]endLocationfullAddressoffers[]steps[]endLocationiataCodePresent for airport locations.
offers[]steps[]endLocationicaoCodeoffers[]steps[]endLocationplaceIdReusable place identifier; send it back to skip geocoding.
offers[]steps[]endLocationlatitudeoffers[]steps[]endLocationlongitudeoffers[]steps[]endLocationtimezoneIANA timezone of the location.
offers[]ticketTypesoffers[]ticketTypes[]idSend this value in
ticketTypes[].id when booking.offers[]ticketTypes[]nameoffers[]ticketTypes[]departureDatetimeoffers[]ticketTypes[]arrivalDatetimeoffers[]alternativeTimesoffers[]alternativeTimes[]departureDatetimeoffers[]alternativeTimes[]arrivalDatetimeResponse examples
json
{
"gdsprovider": 0,
"searchId": "5c8563a5d31d4c33a3a1eafbbfe59c49",
"moreComing": false,
"pickupDatetime": "2026-08-30T22:00:00-04:00",
"numPassengers": 2,
"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"
},
"offers": [
{
"searchId": "5c8563a5d31d4c33a3a1eafbbfe59c49",
"gdsprovider": 0,
"resultId": "763475651c06f5ac31ea587084dc0640",
"bookingToken": "opaque_change_offer_token_generated_by_travelandz",
"expiresAt": "2026-08-30T22:20:00.000Z",
"totalAmount": 49.84,
"currency": "USD",
"bookable": true,
"flightInfoRequired": true,
"extraPaxRequired": false,
"goodToKnowInfo": [],
"cancellationPolicies": [
{
"notice": 48,
"refundPercent": 100,
"refundAmount": 49.84,
"currency": "USD"
}
],
"supports": {},
"steps": [
{
"stepType": "car",
"main": true,
"departureDatetime": "2026-08-30T22:40:00-04:00",
"provider": {
"name": "GO Airlink NYC",
"rating": 5
},
"vehicle": {
"type": "Shared Ride Van",
"category": "Shared",
"maxBags": 4,
"maxPassengers": 11,
"numVehicles": 1
},
"amenities": []
}
],
"ticketTypes": [],
"alternativeTimes": [
{
"departureDatetime": "2026-08-30T22:40:00-04:00",
"arrivalDatetime": "2026-08-30T23:06:10-04:00"
},
{
"departureDatetime": "2026-08-30T23:40:00-04:00",
"arrivalDatetime": "2026-08-31T00:06:10-04:00"
}
]
}
]
}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
After the traveller picks a replacement offer, request pricing for it and then confirm the change. The original reservation stays active until the change is confirmed.
cURL example
bash
curl --request POST \
--url "https://api.sandbox.travelandz.com/v1/transfers/reservations/changes/search" \
-H "Authorization: Bearer $TRAVELANDZ_SECRET_KEY" \
-H "X-Travelandz-Id: $TRAVELANDZ_PUBLIC_KEY:$TRAVELANDZ_PROFILE_CODE" \
-H "Content-Type: application/json" \
--data '{
"reservationHashedId": "5c8563a5d31d4c33a3a1eafbbfe59c4b",
"pickupDatetime": "2026-08-30 22:00",
"numPassengers": 2,
"currency": "USD"
}'