# Flights API overview

> Search, price, book, hold, pay and manage flight orders across every enabled GDS, airline and NDC supplier.

Source: https://fx-port.com/docs/flights

Search, price, book and manage flight orders across every enabled supplier through one API. A search fans out to the suppliers that can serve the route and returns the fares of each, with prices in your agency's currency.

For a summary of what the API covers, who it is for and how to get access, see the [flight booking API for travel agencies](https://fx-port.com/b2b-flights-api).


> [!NOTE]
> **New suppliers are added without a change on your side.** FX-Port keeps connecting GDS, NDC and low-cost suppliers, direct airline deals and more office ids. An integration that selects suppliers automatically benefits from every new supplier and fare. Richer content (more fare families, ancillary types) ships under a new API version, so your current integration keeps working.


## Flight concepts

Read these before you integrate: they apply to every flight endpoint.


- [Booking flows](https://fx-port.com/docs/flights/booking-flows.md): Instant issue, hold then pay, and how cancelling works.
- [Passengers and ages](https://fx-port.com/docs/flights/passengers.md): Passenger types, ages at departure, seated and lap infants, capacity limits.
- [Flight pricing](https://fx-port.com/docs/flights/pricing.md): What each price field means and the `b2bPrice` formula.
- [Post-booking operations](https://fx-port.com/docs/flights/post-booking.md): Cancel, refund, void and exchange: what is self-serve and what is manual.
- [Streaming search results](https://fx-port.com/docs/streaming.md): The first offers in about two seconds, supplier by supplier.


## Endpoints

| Method | Path | Permission | Description |
|---|---|---|---|
| `POST` | `/api/v1/get_flights` | Read | Search for flights. Add `?stream=true` for [server-sent events](https://fx-port.com/docs/streaming.md) |
| `POST` | `/api/v1/flights/flexible_search` | Read | The ±3-day price matrix |
| `POST` | `/api/v1/flights/price_flight` | Read | Price an offer: required before booking |
| `POST` | `/api/v1/flights/book_flight` | **Read+Write** | Create a booking, instant issue or hold |
| `POST` | `/api/v1/flights/get_order_quote` | Read | The current price and state of a held order |
| `POST` | `/api/v1/flights/pay_order` | **Read+Write** | Pay a held order and issue the tickets |
| `POST` | `/api/v1/flights/cancel_order` | **Read+Write** | Cancel a **held (unpaid)** reservation |
| `POST` | `/api/v1/flights/cancel_quote` | Read | Ask what cancelling an issued **Duffel** order would refund |
| `POST` | `/api/v1/flights/confirm_cancel` | **Read+Write** | Confirm that cancellation: irreversible |
| `POST` | `/api/v1/flights/get_booking` | Read | The booking, with the PDF links |
| `POST` | `/api/v1/flights/get_ticket` | Read | The ticket PDF links |
| `POST` | `/api/v1/flights/get_ticket_number` | Read | The e-ticket number |
| `POST` | `/api/v1/flights/get_acd_documents` | Read | The passport documents of an ACD booking: [ACD passport uploads](https://fx-port.com/docs/flights/acd-documents.md) |
| `POST` | `/api/v1/flights/upload_acd_documents` | **Read+Write** | Add or replace those passports (multipart) |
| `GET` | `/api/v1/flights/airports` | Public | Airport autocomplete |
| `GET` | `/api/v1/flights/top-airports` | Public | The most searched airports |

Every endpoint is described in the [API reference](https://fx-port.com/docs/api.md).

## What every flight endpoint has in common

- **Auth.** `Authorization: Bearer fxp_test_...` (sandbox) or `fxp_live_...` (live). A read key is enough for the Read endpoints; the Read+Write endpoints answer `403 read_write_permission_required` to a read key. See [Authentication](https://fx-port.com/docs/authentication.md).
- **Sandbox suppliers.** `amadeus_aqc_dz_1` (Amadeus Algeria: only routes that touch Algeria; supports hold and void) and `duffel_1` (Duffel: worldwide; instant ticketing only). See [Sandbox](https://fx-port.com/docs/sandbox.md).
- **Names.** Requests use `snake_case`; older spellings still work and are answered with a `warnings` array. Responses keep their keys and add snake_case twins. See [Conventions and naming](https://fx-port.com/docs/conventions.md).
- **Your agency.** It is always the one of your API key. Every flights endpoint accepts an `agency_id` (older spelling `agencyId`) so that older clients keep working, and ignores it: do not send it.
- **Identifiers.** A booking is found by its PNR, its supplier order id or its FX-Port id (a UUID), depending on the endpoint: each page says which.
- **Rate limits.** Search and general endpoints 6,000 requests per minute per key; booking endpoints (`book_flight`, `pay_order`, `cancel_order`, `get_order_quote`, `get_booking`) 1,200. See [Rate limits](https://fx-port.com/docs/rate-limits.md).
- **Size.** A search response is 0.7 to 14 MB: send `Accept-Encoding: gzip`.

## Important notes


> [!WARNING]
> **Hold warning.** Holding a flight can prevent you from creating another booking for the same passenger on the same airline and route with some suppliers. If you no longer need a hold, cancel it (`cancel_order`) to release the PNR. A displayed deadline is not a guarantee: an airline can release the PNR early, and only a successful `pay_order` confirms the issue. See [Cancelling](https://fx-port.com/docs/flights/booking-flows.md#cancelling).

> [!WARNING]
> **Fee accuracy.** The exchange fees, refund fees and penalties in `conditions` are indicative and can differ from what is charged. Tell travelers that a ticket is "refundable for a fee" or "changeable for a fee"; do not quote exact amounts.

> [!WARNING]
> **Check `success`, not only the status.** After a booking, `pay_order`, `get_order_quote`, `cancel_quote` and `confirm_cancel` answer **`200`** with `"success": false` when the supplier refuses the request. See [Errors](https://fx-port.com/docs/errors.md#check-success-not-only-the-status).


## Error responses

Every error carries a stable `code`: branch on `errors[0].code`, not on the text. The error body is described in [Errors](https://fx-port.com/docs/errors.md).

| Status | Typical codes | Cause |
|---|---|---|
| `400` | `invalid_airport_code`, `invalid_date`, `invalid_cabin_class`, `missing_field`, `hold_not_supported`, `invalid_booking_type` | The request is wrong; read `errors[0].field` |
| `401` | `authentication_required`, `invalid_api_key` | Missing, malformed or revoked key |
| `402` | `insufficient_balance` | Live only: the balance cannot pay the booking |
| `403` | `read_write_permission_required`, `agency_not_active` | A read key on a write endpoint, or an agency that is not approved. A booking of another agency is never a `403`: it is a `404`, like an unknown id |
| `404` | `search_not_found`, `offer_not_found`, `offer_not_priced`, `booking_not_found` | The id is unknown for your agency and environment |
| `409` | `duplicate_booking`, `booking_in_progress`, `invalid_booking_status` | The request is valid but not possible in the current state |
| `410` | `offer_expired` | The supplier withdrew the offer: search again |
| `413` | `request_too_large` | The body is too large |
| `422` | supplier validation codes | The supplier rejected a passenger detail (a booking only) |
| `429` | `rate_limit_exceeded`, `concurrency_limit_exceeded` | Too many requests, or too many streams open at the same time: wait for `Retry-After` |
| `503` | `all_suppliers_failed`, `supplier_busy`, `service_overloaded`, `supplier_temporarily_unavailable`, `balance_lock_timeout` | No supplier answered, a supplier lane is full, FX-Port is too busy to prepare a large answer, or another operation holds your balance for a moment: retry with backoff (`Retry-After` says how long when it is sent) |

The codes of each endpoint are in its page.

## Questions?

Write to the FX-Port developer team at [dev@fx-port.com](mailto:dev@fx-port.com) for integration help, feature requests or to report an API error. For a void, an exchange, a re-issue or a refund of an issued Amadeus ticket, use **Request support** on the booking page in the FX-Port dashboard or write to the same address.