API Documentation

Complete reference for the DownFare REST API. All endpoints return JSON and require authentication.

Base URL

http://downfare.com/api/v1

Authentication

Include your API key in the X-API-Key header with every request.

X-API-Key: your-api-key-here

Rate Limiting

Rate limits are enforced per API key. The default limit is 60 requests per minute. Rate limit headers are included in every response: 

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1718462400

Error Responses

All errors follow a consistent JSON format with an error code and human-readable message. 

{
    "error": "validation_error",
    "message": "The origin field is required.",
    "errors": {
        "origin": ["The origin field is required."]
    }
}
Status Code Description
400Bad Request -- Invalid parameters
401Unauthorized -- Invalid or missing API key
403Forbidden -- Insufficient scopes
404Not Found -- Resource does not exist
422Validation Error -- Check the errors object
429Too Many Requests -- Rate limit exceeded
500Server Error -- Something went wrong on our end

Authentication

All API requests must be authenticated using an API key. Include your key in the X-API-Key header with every request. API keys are issued upon approval of your developer application.

GET /api/v1/*

All endpoints require authentication via the X-API-Key header.

Parameters

Name Type Required Description
X-API-Key header Yes Your unique API key provided upon approval. 
{
    "error": "Unauthenticated.",
    "message": "A valid API key is required. Include it as the X-API-Key header."
}

Flights

Search for flight offers across hundreds of airlines worldwide. Retrieve detailed offer information including pricing, segments, fare rules, seat maps, and real-time flight status.

Base Path: /api/v1/flights
GET /api/v1/flights/search

Search for available flight offers based on origin, destination, dates, and passenger counts.

Parameters

Name Type Required Description
origin string Yes IATA airport code for departure (e.g., JFK, LHR).
destination string Yes IATA airport code for arrival (e.g., LAX, CDG).
departure_date string Yes Departure date in YYYY-MM-DD format.
return_date string No Return date in YYYY-MM-DD format. Omit for one-way flights.
adults integer No Number of adult passengers (1-9). Defaults to 1.
children integer No Number of child passengers (0-9). Defaults to 0.
infants integer No Number of infant passengers (0-9). Defaults to 0.
travel_class string No Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST. Defaults to ECONOMY. 
{
    "data": [
        {
            "id": "offer_abc123",
            "price": {
                "amount": "349.00",
                "currency": "USD"
            },
            "segments": [
                {
                    "departure": "JFK",
                    "arrival": "LAX",
                    "departureTime": "2025-06-15T08:00:00",
                    "arrivalTime": "2025-06-15T11:30:00",
                    "airline": "AA",
                    "flightNumber": "AA100",
                    "duration": "PT5H30M"
                }
            ],
            "travelClass": "ECONOMY",
            "seatsAvailable": 4
        }
    ],
    "meta": {
        "total": 24,
        "currency": "USD"
    }
}
GET /api/v1/flights/offers/{offerId}

Retrieve detailed information for a specific flight offer, including fare rules and baggage allowances.

Parameters

Name Type Required Description
offerId string Yes The unique identifier of the flight offer. 
{
    "data": {
        "id": "offer_abc123",
        "price": {
            "amount": "349.00",
            "currency": "USD"
        },
        "segments": [
            {
                "departure": "JFK",
                "arrival": "LAX",
                "departureTime": "2025-06-15T08:00:00",
                "arrivalTime": "2025-06-15T11:30:00",
                "airline": "AA",
                "flightNumber": "AA100"
            }
        ],
        "fareRules": {
            "refundable": false,
            "changeable": true,
            "changeFee": "75.00"
        },
        "baggageAllowance": {
            "carryOn": "1 piece",
            "checked": "1 piece (23kg)"
        }
    }
}
POST /api/v1/flights/offers/{offerId}/price

Get a confirmed, up-to-date price for a flight offer. Prices may change between search and booking, so always confirm before checkout.

Parameters

Name Type Required Description
offerId string Yes The unique identifier of the flight offer to price. 
{
    "data": {
        "offerId": "offer_abc123",
        "price": {
            "amount": "355.00",
            "currency": "USD"
        },
        "priceChanged": true,
        "seatsRemaining": 3
    }
}
GET /api/v1/flights/offers/{offerId}/seatmap

Retrieve the seat map for a specific flight offer, showing available and occupied seats by cabin section.

Parameters

Name Type Required Description
offerId string Yes The unique identifier of the flight offer. 
{
    "data": {
        "cabins": [
            {
                "class": "ECONOMY",
                "rows": [
                    {
                        "number": 10,
                        "seats": [
                            {
                                "column": "A",
                                "available": true,
                                "price": "15.00"
                            },
                            {
                                "column": "B",
                                "available": true,
                                "price": "0.00"
                            },
                            {
                                "column": "C",
                                "available": false,
                                "price": null
                            }
                        ]
                    }
                ]
            }
        ]
    }
}
GET /api/v1/flights/status

Get real-time status for a specific flight by carrier code, flight number, and departure date.

Parameters

Name Type Required Description
carrier_code string Yes Two-letter IATA carrier code (e.g., AA, BA, LH).
flight_number string Yes Flight number (e.g., 100, 2045).
departure_date string Yes Departure date in YYYY-MM-DD format. 
{
    "data": {
        "flightNumber": "AA100",
        "status": "on_time",
        "departure": {
            "airport": "JFK",
            "scheduled": "2025-06-15T08:00:00",
            "estimated": "2025-06-15T08:05:00",
            "terminal": "8",
            "gate": "B22"
        },
        "arrival": {
            "airport": "LAX",
            "scheduled": "2025-06-15T11:30:00",
            "estimated": "2025-06-15T11:25:00"
        }
    }
}
GET /api/v1/flights/inspiration

Get inspiration flight deals from a given origin. Returns popular destinations with lowest available fares.

Parameters

Name Type Required Description
origin string No IATA airport code for departure. Returns global deals if omitted. 
{
    "data": [
        {
            "destination": "BCN",
            "city": "Barcelona",
            "country": "ES",
            "price": {
                "amount": "199.00",
                "currency": "USD"
            },
            "departureDate": "2025-07-01"
        },
        {
            "destination": "FCO",
            "city": "Rome",
            "country": "IT",
            "price": {
                "amount": "249.00",
                "currency": "USD"
            },
            "departureDate": "2025-07-05"
        }
    ]
}

Hotels

Search hotels, retrieve live room rates and property detail, validate rates, create and cancel bookings, and pull the static content feed.

Base Path: /api/v1/hotels
GET /api/v1/hotels/search

Search all active hotel providers for available rooms at a destination. Requires the hotels:read scope.

Parameters

Name Type Required Description
city_code string Yes Destination city / destination code (max 10 chars).
check_in_date date Yes Check-in date (YYYY-MM-DD), today or later.
check_out_date date Yes Check-out date (YYYY-MM-DD), after check_in_date.
adults integer Yes Number of adult guests (1-9).
children integer No Number of children (0-9).
child_ages string No Comma-separated ages of the children, e.g. "5,8".
rooms integer No Number of rooms required (1-9). Defaults to 1.
currency string No ISO 4217 currency code (3 letters). 
{
    "data": [
        {
            "id": "HOTELBEDS_12345",
            "name": "Grand Plaza Hotel",
            "starRating": 4,
            "location": {
                "city": "Paris",
                "country": "FR",
                "latitude": 48.8566,
                "longitude": 2.3522
            },
            "price": {
                "amount": "189.00",
                "currency": "USD",
                "perNight": true
            },
            "amenities": [
                "wifi",
                "pool",
                "spa",
                "restaurant"
            ],
            "thumbnail": "https:\/\/example.com\/images\/hotel_12345.jpg"
        }
    ],
    "meta": {
        "total": 56,
        "currency": "USD"
    }
}
GET /api/v1/hotels/{hotelId}

Get live room offers, amenities, images, and a review summary for a specific hotel. Requires the hotels:read scope.

Parameters

Name Type Required Description
hotelId string (path) Yes Provider-prefixed hotel ID from search, e.g. HOTELBEDS_12345.
check_in_date date Yes Check-in date (YYYY-MM-DD), today or later.
check_out_date date Yes Check-out date (YYYY-MM-DD), after check_in_date.
adults integer Yes Number of adult guests (1-9).
children integer No Number of children (0-9).
child_ages string No Comma-separated ages of the children, e.g. "5,8".
rooms integer No Number of rooms required (1-9). 
{
    "data": {
        "id": "HOTELBEDS_12345",
        "name": "Grand Plaza Hotel",
        "description": "A luxurious 4-star hotel in the heart of Paris.",
        "starRating": 4,
        "rooms": [
            {
                "type": "Standard Double",
                "rateKey": "20240101|...|net",
                "price": {
                    "amount": "189.00",
                    "currency": "USD"
                },
                "maxOccupancy": 2
            },
            {
                "type": "Deluxe Suite",
                "rateKey": "20240101|...|net",
                "price": {
                    "amount": "349.00",
                    "currency": "USD"
                },
                "maxOccupancy": 3
            }
        ],
        "amenities": [
            "wifi",
            "pool",
            "spa",
            "restaurant",
            "gym",
            "parking"
        ],
        "images": [
            "https:\/\/example.com\/images\/hotel1.jpg",
            "https:\/\/example.com\/images\/hotel2.jpg"
        ]
    }
}
GET /api/v1/hotels/content

Paginated static content feed of hotel records (name, location, images, amenities, room types) for downstream ingestion. Requires the hotels:read scope.

Parameters

Name Type Required Description
page integer No Page number. Defaults to 1.
pageSize integer No Records per page (1-1000). Defaults to 100.
provider string No Content provider. Defaults to "hotelbeds" (the only provider that currently returns data). 
{
    "data": [
        {
            "id": "HOTELBEDS_12345",
            "name": "Grand Plaza Hotel",
            "city": "Paris",
            "country": "FR",
            "category": "4EST",
            "images": [
                "https:\/\/example.com\/images\/hotel1.jpg"
            ]
        }
    ],
    "meta": {
        "page": 1,
        "pageSize": 100,
        "total": 24500
    }
}
POST /api/v1/hotels/check-rate

Validate one or more rate keys before booking, confirming the current price and cancellation policies. Requires the hotels:read scope. Body: application/json.

Parameters

Name Type Required Description
rateKeys array<string> (body) Yes Rate keys obtained from search or hotel detail (min 1).
originalPrice number (body) No Quoted price to compare against, for price-change detection. 
{
    "data": {
        "rates": [
            {
                "rateKey": "20240101|...|net",
                "price": {
                    "amount": "189.00",
                    "currency": "USD"
                },
                "price_changed": false,
                "cancellation_policies": [
                    {
                        "amount": "0.00",
                        "from": "2024-06-20T00:00:00"
                    }
                ]
            }
        ]
    }
}
POST /api/v1/hotels/book

Create a confirmed hotel booking and charge the API key owner's platform wallet. Requires the hotels:read scope. Body: application/json.

Parameters

Name Type Required Description
rateKey string (body) Yes Rate key for the room to book (re-validate with check-rate first).
holder.name string (body) Yes Lead guest first name.
holder.surname string (body) Yes Lead guest last name.
holder.email email (body) No Lead guest email.
holder.phone string (body) No Lead guest phone.
paxes array (body) No Per-room pax list (roomId, type AD|CH, name, surname, age). Defaults to a single adult holder.
clientReference string (body) No Your own reference ID (max 64 chars).
remark string (body) No Special requests (max 2000 chars).
tolerance number (body) No Allowed price-change tolerance percent (0-100). Defaults to 5.0; booking is rejected if the live price moved beyond it. 
{
    "data": {
        "reference": "HB-1234567",
        "status": "CONFIRMED",
        "hotel": {
            "id": "HOTELBEDS_12345",
            "name": "Grand Plaza Hotel"
        },
        "total": {
            "amount": "189.00",
            "currency": "USD"
        }
    }
}
DELETE /api/v1/hotels/book/{reference}

Cancel a confirmed hotel booking by its provider reference (PNR), scoped to the API key owner. Requires the hotels:read scope.

Parameters

Name Type Required Description
reference string (path) Yes Hotelbeds booking reference (PNR).
reason string (body) No Cancellation reason.
request_refund boolean (body) No Whether to request a refund. Defaults to false. 
{
    "data": {
        "reference": "HB-1234567",
        "status": "CANCELLED",
        "refund": {
            "amount": "0.00",
            "currency": "USD"
        }
    }
}

Vacation Rentals

Browse vacation rental properties including apartments, villas, and holiday homes with availability and pricing.

Base Path: /api/v1/rentals
GET /api/v1/rentals/search

Search approved rental listings by destination (city code or coordinates), dates, and guest/property filters. Requires the rentals:read scope.

Parameters

Name Type Required Description
city_code string Yes Destination code (max 10 chars). Required unless latitude + longitude are provided.
latitude number No Latitude (-90 to 90). Required (with longitude) when city_code is omitted.
longitude number No Longitude (-180 to 180). Required (with latitude) when city_code is omitted.
check_in_date date Yes Check-in date (YYYY-MM-DD), today or later.
check_out_date date Yes Check-out date (YYYY-MM-DD), after check_in_date.
guests integer Yes Number of guests (1-20).
property_type string No Filter by property type (apartment, villa, etc.).
min_bedrooms integer No Minimum number of bedrooms.
min_bathrooms integer No Minimum number of bathrooms.
amenities array<string> No Required amenities; all listed must be present.
min_price number No Minimum nightly average price.
max_price number No Maximum nightly average price (>= min_price). 
{
    "data": [
        {
            "id": "rental_def456",
            "title": "Cozy Apartment Near Eiffel Tower",
            "propertyType": "apartment",
            "bedrooms": 2,
            "maxGuests": 4,
            "price": {
                "amount": "120.00",
                "currency": "USD",
                "perNight": true
            },
            "rating": 4.7,
            "thumbnail": "https:\/\/example.com\/images\/rental_def456.jpg"
        }
    ],
    "meta": {
        "total": 38,
        "currency": "USD"
    }
}
GET /api/v1/rentals/{rentalId}

Retrieve full details, availability, nightly pricing, and review summary for a specific rental. Requires the rentals:read scope.

Parameters

Name Type Required Description
rentalId integer (path) Yes The unique identifier of the rental property.
check_in_date date Yes Check-in date (YYYY-MM-DD), today or later.
check_out_date date Yes Check-out date (YYYY-MM-DD), after check_in_date.
guests integer Yes Number of guests (1-20). 
{
    "data": {
        "id": "rental_def456",
        "title": "Cozy Apartment Near Eiffel Tower",
        "description": "A beautifully furnished 2-bedroom apartment just minutes from the Eiffel Tower.",
        "propertyType": "apartment",
        "bedrooms": 2,
        "bathrooms": 1,
        "maxGuests": 4,
        "amenities": [
            "wifi",
            "kitchen",
            "washer",
            "air_conditioning"
        ],
        "houseRules": {
            "no_smoking": true,
            "no_parties": true,
            "checkIn": "15:00",
            "checkOut": "11:00"
        },
        "images": [
            "https:\/\/example.com\/images\/rental1.jpg",
            "https:\/\/example.com\/images\/rental2.jpg"
        ]
    }
}

Tours & Activities

Discover tours, experiences, and activities available at destinations worldwide. Book guided tours, day trips, and unique experiences.

Base Path: /api/v1/tours
GET /api/v1/tours/search

Search for tours and activities available at a destination. Requires the tours:read scope.

Parameters

Name Type Required Description
city_code string Yes Destination code (max 10 chars).
date date No Preferred activity date (YYYY-MM-DD), today or later.
category string No Filter by activity category.
duration string No Filter by duration.
currency string No ISO 4217 currency code (3 letters). 
{
    "data": [
        {
            "id": "tour_ghi012",
            "title": "Skip-the-Line Eiffel Tower Tour",
            "category": "sightseeing",
            "duration": "PT3H",
            "price": {
                "amount": "65.00",
                "currency": "USD",
                "perPerson": true
            },
            "rating": 4.8,
            "reviewCount": 1240,
            "thumbnail": "https:\/\/example.com\/images\/tour_ghi012.jpg"
        }
    ],
    "meta": {
        "total": 89,
        "currency": "USD"
    }
}
GET /api/v1/tours/{activityId}

Get detailed information about a specific tour or activity, including availability and booking options.

Parameters

Name Type Required Description
activityId string Yes The unique identifier of the tour or activity. 
{
    "data": {
        "id": "tour_ghi012",
        "title": "Skip-the-Line Eiffel Tower Tour",
        "description": "Enjoy priority access to the Eiffel Tower with an expert local guide.",
        "category": "sightseeing",
        "duration": "PT3H",
        "languages": [
            "en",
            "fr",
            "es"
        ],
        "includes": [
            "Skip-the-line ticket",
            "Professional guide",
            "Headset"
        ],
        "meetingPoint": {
            "address": "Champ de Mars, Paris",
            "latitude": 48.8584,
            "longitude": 2.2945
        },
        "availableDates": [
            "2025-06-15",
            "2025-06-16",
            "2025-06-17"
        ]
    }
}

Wellness & Spa

Search for wellness and spa experiences worldwide, including massages, thermal baths, yoga retreats, facials, and beauty treatments. Browse offerings by destination, date, and category.

Base Path: /api/v1/wellness
GET /api/v1/wellness/search

Search for available wellness and spa experiences at a specific destination.

Parameters

Name Type Required Description
city_code string Yes City or destination code (e.g., BKK, DPS, IST).
date string No Preferred appointment date in YYYY-MM-DD format.
category string No Filter by category: spa_treatment, massage, facial, body_treatment, thermal_bath, hammam, yoga, meditation, fitness, wellness_retreat, detox.
adults integer No Number of adult participants (1-9). Defaults to 1.
children integer No Number of child participants (0-9). Defaults to 0.
currency string No ISO 4217 currency code (e.g., USD, EUR). Defaults to USD. 
{
    "data": [
        {
            "id": "wellness_abc123",
            "name": "Traditional Thai Massage",
            "description": "Authentic Thai massage experience in a serene spa setting.",
            "image": "https:\/\/example.com\/images\/thai-massage.jpg",
            "price": {
                "amount": "85.00",
                "currency": "USD"
            },
            "duration": "120 minutes",
            "category": "massage",
            "rating": 4.8,
            "review_count": 342,
            "free_cancellation": true,
            "source": "manual"
        }
    ],
    "meta": {
        "total": 24
    }
}
GET /api/v1/wellness/{offerId}

Get detailed information about a specific wellness or spa experience, including amenities, inclusions, and booking details.

Parameters

Name Type Required Description
offerId string Yes The unique identifier of the wellness offer. 
{
    "data": {
        "id": "wellness_abc123",
        "name": "Traditional Thai Massage",
        "description": "Experience the art of traditional Thai massage in a peaceful spa environment.",
        "images": [
            "https:\/\/example.com\/images\/thai-massage-1.jpg",
            "https:\/\/example.com\/images\/thai-massage-2.jpg"
        ],
        "price": {
            "amount": "85.00",
            "currency": "USD",
            "per_person": true
        },
        "duration": "120 minutes",
        "duration_minutes": 120,
        "category": "massage",
        "rating": 4.8,
        "review_count": 342,
        "location": {
            "city": "Bangkok",
            "address": "123 Sukhumvit Road, Bangkok"
        },
        "highlights": [
            "Certified therapists",
            "Traditional techniques",
            "Complimentary herbal tea"
        ],
        "included": [
            "Massage session",
            "Herbal compress",
            "Welcome drink"
        ],
        "excluded": [
            "Gratuities",
            "Transportation"
        ],
        "amenities": [
            "sauna",
            "steam_room",
            "pool",
            "relaxation_area"
        ],
        "meeting_point": "123 Sukhumvit Road, Bangkok 10110",
        "free_cancellation": true,
        "cancellation_policy": "Free cancellation up to 24 hours before appointment."
    }
}

Car Rentals

Search for rental car availability, confirm pricing, and create car rental orders across pickup and drop-off locations worldwide.

Base Path: /api/v1/cars
GET /api/v1/cars/search

Search for available rental cars at a specific location and time range.

Parameters

Name Type Required Description
pickup_code string Yes Pickup location name or IATA code.
dropoff_code string No Drop-off location. Same as pickup if omitted.
pickup_datetime string Yes Pickup date and time in YYYY-MM-DDTHH:MM format.
return_datetime string Yes Return date and time in YYYY-MM-DDTHH:MM format.
currency string No ISO 4217 currency code (e.g., USD, EUR).
driver_age integer No Driver age (18-99). Some providers require this.
car_type string No Filter by car type (compact, sedan, suv, etc.).
transmission string No Filter by transmission type (automatic, manual). 
{
    "data": [
        {
            "id": "car_jkl345",
            "vehicle": {
                "make": "Toyota",
                "model": "Corolla",
                "year": 2024,
                "category": "compact"
            },
            "supplier": "Hertz",
            "price": {
                "amount": "42.00",
                "currency": "USD",
                "perDay": true
            },
            "features": [
                "automatic",
                "air_conditioning",
                "4_doors",
                "5_seats"
            ],
            "thumbnail": "https:\/\/example.com\/images\/car_jkl345.jpg"
        }
    ],
    "meta": {
        "total": 31,
        "currency": "USD"
    }
}
GET /api/v1/cars/offers/{offerId}/price

Get confirmed, up-to-date pricing for a specific car rental offer. Always confirm pricing before creating an order.

Parameters

Name Type Required Description
offerId string Yes The unique identifier of the car rental offer.
provider string No Provider name (e.g., expedia, manual). Defaults to expedia. 
{
    "data": [
        {
            "id": "car_jkl345",
            "vehicle": {
                "make": "Toyota",
                "model": "Corolla",
                "category": "compact"
            },
            "price": {
                "amount": "42.00",
                "currency": "USD",
                "perDay": true,
                "totalAmount": "294.00"
            },
            "insurance": {
                "included": true,
                "type": "basic"
            }
        }
    ],
    "meta": {
        "priceValidUntil": "2025-06-15T12:00:00Z"
    }
}
POST /api/v1/cars/orders

Create a car rental order from a confirmed offer. Requires cars:write scope.

Parameters

Name Type Required Description
offer_id string Yes The offer ID to book.
provider string Yes Provider name: manual or expedia.
driver object No Driver details (name, age, license info).
customer object No Customer contact details (name, email, phone).
payment object No Payment details. 
{
    "data": {
        "orderId": "car_order_xyz",
        "status": "confirmed",
        "vehicle": {
            "make": "Toyota",
            "model": "Corolla"
        },
        "pickup": {
            "location": "JFK Airport",
            "datetime": "2025-06-15T10:00:00"
        },
        "dropoff": {
            "location": "JFK Airport",
            "datetime": "2025-06-22T10:00:00"
        },
        "totalPrice": {
            "amount": "294.00",
            "currency": "USD"
        }
    }
}

Transfers

Book airport transfers, city-to-city rides, and private car services. Create, retrieve, and cancel transfer orders.

Base Path: /api/v1/transfers
POST /api/v1/transfers/orders

Create a transfer order for airport pickups, hotel transfers, or city-to-city rides.

Parameters

Name Type Required Description
transfer_offer_id string Yes The transfer offer ID to book.
travelers array Yes Array of traveler objects with name and contact details.
customer object No Customer contact information.
payment object No Payment details.
provider string No Provider name. Defaults to amadeus. 
{
    "data": {
        "id": "transfer_mno678",
        "status": "confirmed",
        "pickup": {
            "address": "Charles de Gaulle Airport, Terminal 2E",
            "time": "2025-06-15T14:00:00"
        },
        "dropoff": {
            "address": "Grand Plaza Hotel, Paris"
        },
        "vehicle": {
            "type": "sedan",
            "maxPassengers": 3
        },
        "price": {
            "amount": "55.00",
            "currency": "USD"
        },
        "driver": {
            "name": "Jean-Pierre",
            "phone": "+33612345678"
        }
    }
}
GET /api/v1/transfers/orders/{orderId}

Retrieve details for a specific transfer order, including status, driver information, and vehicle details.

Parameters

Name Type Required Description
orderId string Yes The unique transfer order identifier.
provider string No Provider name. Defaults to amadeus. 
{
    "data": {
        "id": "transfer_mno678",
        "status": "confirmed",
        "pickup": {
            "address": "Charles de Gaulle Airport, Terminal 2E",
            "time": "2025-06-15T14:00:00"
        },
        "dropoff": {
            "address": "Grand Plaza Hotel, Paris"
        },
        "vehicle": {
            "type": "sedan",
            "maxPassengers": 3
        },
        "price": {
            "amount": "55.00",
            "currency": "USD"
        },
        "driver": {
            "name": "Jean-Pierre",
            "phone": "+33612345678"
        }
    }
}
DELETE /api/v1/transfers/orders/{orderId}

Cancel an existing transfer order. Subject to the cancellation policy of the provider.

Parameters

Name Type Required Description
orderId string Yes The unique transfer order identifier.
provider string No Provider name. Defaults to amadeus. 
{
    "data": {
        "id": "transfer_mno678",
        "status": "cancelled",
        "cancelledAt": "2025-06-14T10:00:00Z"
    }
}

Bookings

Manage the complete booking lifecycle. Create bookings from flight, hotel, or other offers, list existing bookings, and handle cancellations.

Base Path: /api/v1/bookings
POST /api/v1/bookings

Create a booking for a priced flight offer, associated with the API key owner. Requires the bookings:write scope. Body: application/json.

Parameters

Name Type Required Description
offer_id string (body) Yes The priced flight offer ID to book.
passengers array (body) Yes One object per passenger.
passengers.*.title string (body) Yes Passenger title (e.g. MR, MS).
passengers.*.first_name string (body) Yes Passenger first name.
passengers.*.last_name string (body) Yes Passenger last name.
passengers.*.date_of_birth date (body) Yes Passenger date of birth (YYYY-MM-DD).
passengers.*.contact.email email (body) Yes Passenger contact email.
passengers.*.contact.phone string (body) Yes Passenger contact phone. 
{
    "data": {
        "id": "booking_pqr901",
        "bookingNumber": "BK-20250615-ABC",
        "status": "confirmed",
        "offerType": "flight",
        "totalPrice": {
            "amount": "698.00",
            "currency": "USD"
        },
        "createdAt": "2025-06-10T09:30:00Z"
    }
}
GET /api/v1/bookings

List all bookings belonging to the API key owner, with optional filtering and pagination. Requires the bookings:read scope.

Parameters

Name Type Required Description
module_type string No Filter by module, e.g. flights, hotels, rentals, tours, cars, transfers.
status string No Filter by booking status, e.g. confirmed, pending, cancelled, completed.
per_page integer No Results per page. Defaults to 20. 
{
    "data": [
        {
            "id": "booking_pqr901",
            "bookingNumber": "BK-20250615-ABC",
            "status": "confirmed",
            "offerType": "flight",
            "totalPrice": {
                "amount": "698.00",
                "currency": "USD"
            },
            "createdAt": "2025-06-10T09:30:00Z"
        }
    ],
    "meta": {
        "total": 12,
        "page": 1,
        "per_page": 15,
        "last_page": 1
    }
}
GET /api/v1/bookings/{bookingId}

Get full details for a specific booking, including traveler information and payment status.

Parameters

Name Type Required Description
bookingId string Yes The unique booking identifier or booking number. 
{
    "data": {
        "id": "booking_pqr901",
        "bookingNumber": "BK-20250615-ABC",
        "status": "confirmed",
        "offerType": "flight",
        "passengers": [
            {
                "name": "John Doe",
                "email": "john@example.com"
            }
        ],
        "totalPrice": {
            "amount": "698.00",
            "currency": "USD"
        },
        "paymentStatus": "paid",
        "createdAt": "2025-06-10T09:30:00Z"
    }
}
POST /api/v1/bookings/{bookingId}/cancel

Cancel a booking scoped to the API key owner. Requires the bookings:write scope. Subject to the offer's cancellation policy.

Parameters

Name Type Required Description
bookingId string (path) Yes The unique booking identifier.
reason string (body) No Optional reason for cancellation (max 500 chars).
request_refund boolean (body) No Whether to request a refund. Defaults to false. 
{
    "data": {
        "id": "booking_pqr901",
        "status": "cancelled",
        "refund": {
            "amount": "628.20",
            "currency": "USD",
            "status": "processing"
        },
        "cancelledAt": "2025-06-12T14:00:00Z"
    }
}

Places & Autocomplete

Search for places, airports, and popular destinations. Use these endpoints to power search forms and autocomplete fields in your application.

Base Path: /api/v1/places
GET /api/v1/places/search

Search for places by name or city. Returns locations with coordinates, ratings, and metadata.

Parameters

Name Type Required Description
q string Yes Search query string (minimum 1 character).
limit integer No Maximum number of results (1-20). Defaults to 10. 
{
    "data": [
        {
            "id": 1,
            "name": "Eiffel Tower",
            "city": "Paris",
            "country": "FR",
            "lat": 48.8584,
            "lng": 2.2945,
            "types": [
                "tourist_attraction",
                "landmark"
            ],
            "rating": 4.7
        }
    ]
}
GET /api/v1/places/airports

Search for airports by name or IATA code. Useful for powering flight search autocomplete fields.

Parameters

Name Type Required Description
q string Yes Search query (minimum 2 characters). Matches airport name, city, or IATA code. 
{
    "data": [
        {
            "iata": "JFK",
            "name": "John F. Kennedy International Airport",
            "city": "New York",
            "country": "US"
        },
        {
            "iata": "LGA",
            "name": "LaGuardia Airport",
            "city": "New York",
            "country": "US"
        }
    ]
}
GET /api/v1/places/popular

Get popular destinations for a given travel module. Useful for showing trending locations on your homepage.

Parameters

Name Type Required Description
type string No Module type: flights, hotels, tours, rentals, cars, transfers. Defaults to flights. 
{
    "data": [
        {
            "destination": "Paris",
            "country": "FR",
            "iata": "CDG",
            "searchCount": 15420
        },
        {
            "destination": "London",
            "country": "GB",
            "iata": "LHR",
            "searchCount": 12890
        },
        {
            "destination": "Tokyo",
            "country": "JP",
            "iata": "NRT",
            "searchCount": 9780
        }
    ]
}