# FX-Port API documentation

> FX-Port is a B2B travel platform. One REST API gives travel agencies and developers flights (GDS, NDC, LCC and direct airlines), hotels (RateHawk / WorldOTA and more) and eSIMs, with the best available prices and no per-supplier code. Requests are JSON with snake_case fields; every price is returned in the currency of the agency that owns the API key.

The API lives at https://api.fx-port.com/api/v1 (v1). Authenticate with `Authorization: Bearer <key>`: keys start with `fxp_test_` for the sandbox and `fxp_live_` for live, both on the same host. A Read key can search, price and read; a Read+Write key can also book, pay and cancel. Request bodies use snake_case field names; the canonical names and the legacy camelCase names that still work are listed in the Conventions and naming guide.

Hotels can only be booked in the sandbox with the supplier's designated test hotel (see the hotels sandbox testing guide). Flight search can be streamed as server-sent events (see the streaming guide). Every page below is available as Markdown by adding `.md` to its address.

## Get started

- [Introduction](https://fx-port.com/docs/introduction.md): FX-Port is a unified travel API for flights, hotels, eSIMs and more: one integration, many suppliers, best available prices.
- [Quickstart](https://fx-port.com/docs/quickstart.md): Get a sandbox key, search, price and book a flight, then check the booking, in about ten minutes.
- [Security](https://fx-port.com/docs/security.md): How to keep your FX-Port integration secure: key handling, booking authorization and general API security hygiene.
- [Authentication](https://fx-port.com/docs/authentication.md): How to authenticate with the FX-Port API using Bearer tokens, the key permissions, the key prefixes and the environments.
- [Environments and Postman](https://fx-port.com/docs/environments.md): Live and sandbox on one base URL, decided by the API key prefix, and the Postman collections to try every endpoint.
- [Sandbox](https://fx-port.com/docs/sandbox.md): How the sandbox works, the limits of the suppliers' own test systems and what to expect while testing.

## API fundamentals

- [Conventions and naming](https://fx-port.com/docs/conventions.md): Request and response conventions, the canonical snake_case names, and the legacy camelCase names that still work and how to move off them.
- [Legacy names and twins](https://fx-port.com/docs/legacy-names.md): Every previous spelling a request still accepts and every snake_case twin a response adds, per endpoint, listed from the API's own map.
- [Errors](https://fx-port.com/docs/errors.md): The error shapes of the API, every error code you can meet, request ids and what to do about each kind of error.
- [Rate limits and fair use](https://fx-port.com/docs/rate-limits.md): How many requests a key may send, what a 429 means, which requests are refused early and how to back off.
- [Streaming search results](https://fx-port.com/docs/streaming.md): Receive flight search results supplier by supplier as server-sent events, instead of waiting for the slowest supplier.

## Flights: concepts

- [Flights API overview](https://fx-port.com/docs/flights.md): Search, price, book, hold, pay and manage flight orders across every enabled GDS, airline and NDC supplier.
- [Booking flows](https://fx-port.com/docs/flights/booking-flows.md): Step-by-step flight booking flows: instant issue, hold then pay, and how cancelling a held PNR works.
- [Passengers and ages](https://fx-port.com/docs/flights/passengers.md): Passenger types, age rules evaluated at departure, seated and lap infants, required age arrays and capacity limits.
- [Flight pricing](https://fx-port.com/docs/flights/pricing.md): What each flight price field means, the b2bPrice formula, the ACD block and how the exchange rate is presented.
- [Post-booking operations](https://fx-port.com/docs/flights/post-booking.md): Void, exchange, re-issue and refund of issued flight tickets, and how to request them from the FX-Port team today.

## Flights: search and price

- [Airport autocomplete](https://fx-port.com/docs/flights/airports.md): Airport autocomplete for origin and destination inputs. No authentication required. Supports 30+ language locales.
- [Search flights](https://fx-port.com/docs/flights/search.md): Search for flights across one, several or every enabled supplier. Start here, then expand the examples by route, passenger, filter, supplier or itinerary type.
- [Basic route examples](https://fx-port.com/docs/flights/search/basic-routes.md): One-way, round-trip, direct-only and all-supplier flight searches, with real request and response examples.
- [Passenger and cabin examples](https://fx-port.com/docs/flights/search/passenger-and-cabin.md): Family groups, lap and seated infants, adult-senior-young mixes and cabin-class searches, with real request and response examples.
- [Filter examples](https://fx-port.com/docs/flights/search/filters.md): Direct flights, refundable fares, checked bags, airline include and exclude, and flexible dates.
- [Supplier selection](https://fx-port.com/docs/flights/search/suppliers.md): Let FX-Port select suppliers automatically, or pass exact supplier ids for a special case.
- [Open-jaw and multi-city searches](https://fx-port.com/docs/flights/search/complex-itineraries.md): Search open-jaw trips and multi-city itineraries of three to six flights with the segments array.
- [Flexible-date search](https://fx-port.com/docs/flights/flexible-search.md): A ±3-day price matrix from suppliers that support flexible-date searches, for both one-way and round-trip requests.
- [Price a flight offer](https://fx-port.com/docs/flights/price.md): Price a cached flight offer to confirm the current fare. Required before booking: book_flight reads the priced offer from this cache.

## Flights: book, pay and cancel

- [Book a flight](https://fx-port.com/docs/flights/book.md): Create a booking, either an instant issue or a hold reservation. Requires Read+Write permission.
- [Quote a held booking](https://fx-port.com/docs/flights/get-order-quote.md): Get the current price and payment status of a held order before paying.
- [Pay a held booking](https://fx-port.com/docs/flights/pay-order.md): Pay a held order, issue the tickets and debit the agency balance. Requires Read+Write permission.
- [Cancel a held booking](https://fx-port.com/docs/flights/cancel-order.md): Cancel a held (unpaid) flight reservation to release the PNR. This is not a refund.
- [Quote a cancellation](https://fx-port.com/docs/flights/cancel-quote.md): Ask what cancelling an issued Duffel order would refund. Nothing is cancelled until you confirm it.
- [Confirm a cancellation](https://fx-port.com/docs/flights/confirm-cancel.md): Confirm a quoted cancellation of an issued Duffel order: the order is cancelled and the refund goes to your balance. Irreversible.

## Flights: after booking

- [Get a flight booking](https://fx-port.com/docs/flights/get-booking.md): Retrieve the full booking through one booking_id field that accepts an internal UUID, a supplier order id or a PNR, with the PDF link.
- [Get the ticket PDF](https://fx-port.com/docs/flights/get-ticket.md): Returns the ticket PDF download URL. Poll until ticket_ready is true.
- [Get the ticket number](https://fx-port.com/docs/flights/get-ticket-number.md): Ask for the e-ticket number of a booking: FX-Port asks the airline when the number is not stored yet.
- [ACD passport uploads](https://fx-port.com/docs/flights/acd-documents.md): Upload, add and replace the passport copies that an ACD booking needs: one for every traveler of the booking, sent after the booking with upload_acd_documents.

## Hotels: concepts

- [Hotels API overview](https://fx-port.com/docs/hotels.md): Geo search around a point, name search, hotel content, rates, pre-book, bookings that confirm at once, vouchers and cancellation.
- [Sandbox testing](https://fx-port.com/docs/hotels/sandbox-testing.md): Which hotel ids are safe to test with in the sandbox, and why booking any other hotel fails.
- [Mini and full hotel data](https://fx-port.com/docs/hotels/hotel-data.md): Use the compact mini data for search result lists and the full data only for the hotel page, with the size difference measured.
- [Guests and rooms](https://fx-port.com/docs/hotels/guests-and-rooms.md): How to book multiple rooms, and pass residency, the number of travelers and children ages for hotels.
- [Hotel pricing](https://fx-port.com/docs/hotels/pricing.md): What each hotel price field means, what your agency is debited (totalPrice minus agencyCommission), and how taxes and the exchange rate are shown.

## Hotels: search

- [Geo search](https://fx-port.com/docs/hotels/search.md): Search and price every hotel around a point (latitude, longitude and radius), or one hotel by id: a compact card and the cheapest price per hotel.
- [Search locations](https://fx-port.com/docs/hotels/locations.md): Search cities and destinations by name and get back usable geo coordinates for hotel availability search.
- [Hotel name search](https://fx-port.com/docs/hotels/name-search.md): Find a hotel by name. Partial names and accents are tolerated; typos only when the rest of the name is long enough.
- [Hotel details](https://fx-port.com/docs/hotels/hotel-details.md): The full page of one hotel, or its compact card with detail_level. Reads the cache and fetches an unknown hotel live.

## Hotels: rates and booking

- [Get hotel rates](https://fx-port.com/docs/hotels/rates.md): Every room and rate combination for a specific hotel, with cancellation policies. Required before pre_book.
- [Pre-book a rate](https://fx-port.com/docs/hotels/pre-book.md): Lock in the price of a chosen rate and get a partner_order_id and the booking form ahead of book_hotel. Requires Read+Write permission.
- [Book a hotel](https://fx-port.com/docs/hotels/book.md): Book a pre-booked rate with the guest details: the booking confirms at once, with no hold or pay-later. Requires Read+Write permission.

## Hotels: after booking

- [Get a hotel booking](https://fx-port.com/docs/hotels/get-booking.md): Retrieve the full hotel booking, including the pricing breakdown and the voucher PDF link, through the shared account booking endpoint.
- [Get the hotel voucher](https://fx-port.com/docs/hotels/voucher.md): Retrieve the confirmation voucher PDF URL of a confirmed hotel booking.
- [Cancel a hotel booking](https://fx-port.com/docs/hotels/cancel.md): Cancel a confirmed hotel booking owned by your agency. Requires Read+Write permission.

## eSIMs: concepts

- [eSIMs API overview](https://fx-port.com/docs/esims.md): Browse the package catalog, place orders, top up existing eSIMs and track usage across 190+ countries.
- [eSIM pricing](https://fx-port.com/docs/esims/pricing.md): What each eSIM price field means, what is debited from your balance and how the commission is read.
- [Supplier continuity](https://fx-port.com/docs/esims/supplier-continuity.md): Why a topup can occasionally be unavailable for an existing eSIM, and how FX-Port protects your agency balance when that happens.

## eSIMs: catalog and orders

- [Package catalog](https://fx-port.com/docs/esims/packages.md): List eSIM data packages by country and type, and check device compatibility.
- [Create an eSIM order](https://fx-port.com/docs/esims/orders.md): Create a new eSIM order. Requires a read+write API key.
- [Top up an eSIM](https://fx-port.com/docs/esims/topups.md): Check topup availability and top up an existing eSIM by ICCID. Creation requires a read+write API key.

## eSIMs: after the order

- [eSIM usage](https://fx-port.com/docs/esims/usage.md): Retrieve the remaining data, voice and SMS balance of one eSIM or of up to 50 eSIMs.
- [eSIM bookings](https://fx-port.com/docs/esims/bookings.md): List the eSIM orders of your agency, read the topups of an eSIM and check that a booking is yours.
- [Setup and installation instructions](https://fx-port.com/docs/esims/instructions.md): Retrieve the QR code, the APN and the installation instructions for a booking or an ICCID.

## Account and suppliers

- [Suppliers](https://fx-port.com/docs/suppliers.md): Discover every enabled supplier across all products, with capabilities and void deadlines.
- [Account API overview](https://fx-port.com/docs/account.md): Agency balances, the financial ledger and cross-product booking history.
- [List balances](https://fx-port.com/docs/account/balances.md): Current balance for each currency the agency holds.
- [Balance history](https://fx-port.com/docs/account/balance-history.md): The complete financial ledger of one currency balance: top-ups, booking debits and refunds.
- [Booking history](https://fx-port.com/docs/account/history.md): Booking summaries across all products, newest first.
- [Booking detail](https://fx-port.com/docs/account/booking-detail.md): A single booking by its public reference, with the pricing breakdown and the traveler pricing.

## Resources

- [Use these docs with AI](https://fx-port.com/docs/ai-tools.md): Open any page in ChatGPT or Claude, copy it as Markdown, or give an assistant llms.txt and the OpenAPI file.

## API reference

- [API reference](https://fx-port.com/docs/api.md): Every endpoint of the FX-Port API: parameters, request and response objects, examples in nine languages and the errors each can return.

### Flights
- [Search airports](https://fx-port.com/docs/api/search-airports.md): Airport and city autocomplete for the origin and destination of a search: send what the user has typed (an IATA code, a city or an airport name) and use the ap of the chosen record as origin or destination.
- [Get the most searched airports](https://fx-port.com/docs/api/top-airports.md): The most searched airports, for the first suggestions of an empty search box before the user types anything.
- [Search flights](https://fx-port.com/docs/api/get-flights.md): Search flights across every compatible supplier and read the offers grouped by supplier.
- [Search flexible dates](https://fx-port.com/docs/api/flexible-search.md): Get a price calendar instead of offers: the cheapest fare of each day from three days before to three days after your travel dates.
- [Price a flight offer](https://fx-port.com/docs/api/price-flight.md): Confirm the current price and conditions of one offer of a search with its supplier, just before you book it.
- [Book a flight offer](https://fx-port.com/docs/api/book-flight.md): Book an offer you have priced: ticketed at once (booking_type: issue) or held without payment (hold).
- [Get a flight booking](https://fx-port.com/docs/api/get-booking.md): Read a booking of your agency by its PNR, its supplier order id or its FX-Port id: status, prices, ticket number, the links of the PDF tickets and the ACD state.
- [Get the ticket PDF of a booking](https://fx-port.com/docs/api/get-ticket.md): Get the download links of the ticket PDF of a booking (the hold voucher for a hold).
- [Get the e-ticket number of a booking](https://fx-port.com/docs/api/get-ticket-number.md): Get the e-ticket number of a booking, asking the airline for it when it is not stored yet.
- [Get the current quote of an order](https://fx-port.com/docs/api/get-order-quote.md): Get the current price of an order, its status and whether it can still be paid.
- [Pay a held order and issue the tickets](https://fx-port.com/docs/api/pay-order.md): Pay for a held booking and issue the tickets.
- [Cancel a held reservation](https://fx-port.com/docs/api/cancel-order.md): Cancel a held (unpaid) reservation: it is deleted at the supplier and the PNR is released.
- [Quote the refund of an issued order](https://fx-port.com/docs/api/cancel-quote.md): Ask what cancelling an issued Duffel order would refund.
- [Confirm the cancellation of an order](https://fx-port.com/docs/api/confirm-cancel.md): Confirm the cancellation you quoted with cancel_quote: the Duffel order is cancelled at the airline and the refund is credited to your FX-Port balance.
- [Get the ACD document state of a booking](https://fx-port.com/docs/api/get-acd-documents.md): Read what a booking needs for ACD, which travelers already have a passport on file, and whether you can upload.
- [Upload ACD passport documents](https://fx-port.com/docs/api/upload-acd-documents.md): Add or replace the passport copies of a booking that needs ACD: one file for each traveler, sent as multipart/form-data (not JSON).

### Hotels
- [Search destinations and get coordinates](https://fx-port.com/docs/api/search-hotel-locations.md): Turns the text a user typed (a city, an area, an airport, a hotel) into places with coordinates.
- [Find a hotel by name](https://fx-port.com/docs/api/get-hotel-name-search.md): Fuzzy search over the names of every hotel FX-Port knows.
- [Find a hotel by name (JSON body)](https://fx-port.com/docs/api/post-hotel-name-search.md): The same search as GET /hotels/name-search, with the parameters in a JSON body.
- [Geo search: hotels around a point](https://fx-port.com/docs/api/search-hotels.md): Geo search: finds and prices the hotels around a point for a stay.
- [Read the content of many hotels by id](https://fx-port.com/docs/api/get-hotel-content.md): Reads the content FX-Port holds for up to 200 hotels at once, by id.
- [Read the raw hotel documents by id](https://fx-port.com/docs/api/get-hotel-details.md): Reads the cached hotel documents of up to 200 hotels, by id, exactly as FX-Port stores them: the FULL fields plus images_ext (the photos with their category) and policy_struct.
- [Read one hotel for the hotel page](https://fx-port.com/docs/api/get-hotel-info.md): Returns the content of a hotel for the page the user opens before checkout: description, photos, every room type, policies, facts and contact details, in camelCase (HotelInfo).
- [Get the rooms and rates of one hotel](https://fx-port.com/docs/api/get-hotel-rates.md): Returns every room and rate of one hotel for a stay and an occupancy, each with its meal plan, cancellation schedule and price.
- [Lock a rate before booking](https://fx-port.com/docs/api/pre-book-hotel.md): Locks the rate you chose: the supplier re-checks the price and opens an order, and FX-Port keeps the priced offer for one hour under the partnerOrderId of the answer.
- [Book a locked rate](https://fx-port.com/docs/api/book-hotel.md): Books the offer locked by pre_book and confirms it: there is no hold or pay-later option for API keys, and your agency is debited as part of the booking, when it is confirmed (the sandbox debits nothing).
- [Cancel a confirmed hotel booking](https://fx-port.com/docs/api/cancel-hotel.md): Cancels a booking of your agency and refunds it according to the cancellation schedule of the rate.
- [Get the voucher PDF links of a booking](https://fx-port.com/docs/api/get-hotel-voucher.md): Returns the links of the voucher PDFs of a booking of your agency: one with the price and one without it, to hand to the traveler.

### eSIMs
- [List eSIM packages](https://fx-port.com/docs/api/list-esim-packages.md): List the eSIM packages your agency can sell, with prices in your agency currency.
- [List eSIM compatible devices](https://fx-port.com/docs/api/list-esim-compatible-devices.md): List the devices known to support eSIM, to check a traveler's phone before the sale.
- [Create an eSIM order](https://fx-port.com/docs/api/create-esim-order.md): Create one eSIM, debit your agency balance (live only) and return the eSIM with its activation data.
- [List topup packages of an eSIM](https://fx-port.com/docs/api/list-esim-topup-packages.md): List the packages that can top up one eSIM of your agency, with prices in your agency currency.
- [Top up an eSIM](https://fx-port.com/docs/api/create-esim-topup.md): Add a topup package to an eSIM of your agency and debit your agency balance (live only).
- [Get the usage of an eSIM](https://fx-port.com/docs/api/get-esim-usage.md): Get the remaining and the total data, voice and SMS of one eSIM of your agency, with its status and expiry.
- [Get the usage of several eSIMs](https://fx-port.com/docs/api/get-esim-usage-bulk.md): Get the usage of several eSIMs of your agency in one call.
- [List eSIM bookings](https://fx-port.com/docs/api/list-esim-bookings.md): List the eSIM orders of your agency in this environment, newest first, with search and pagination.
- [List the topups of an eSIM](https://fx-port.com/docs/api/list-esim-topup-history.md): List the topups of one eSIM, newest first.
- [Check that an eSIM booking is yours](https://fx-port.com/docs/api/verify-esim-booking.md): Tell whether an eSIM booking belongs to your agency, before you build a link or a screen around its booking_id.
- [Get the setup data of a booking](https://fx-port.com/docs/api/get-esim-setup-instructions.md): Get the original order of an eSIM booking: the eSIM with its activation data and the installation steps as HTML, to build your own confirmation or setup page.
- [Get eSIM installation instructions](https://fx-port.com/docs/api/get-esim-instructions.md): Get step-by-step installation instructions for one eSIM, per operating system, in the language of the request.

### Account
- [List balances](https://fx-port.com/docs/api/list-balances.md): List the balance of your agency in each currency it holds.
- [Get the history of a balance](https://fx-port.com/docs/api/get-balance-history.md): List the money movements recorded against one balance: top-ups, booking debits and refunds, newest first.
- [List booking history](https://fx-port.com/docs/api/list-booking-history.md): List the bookings of your agency across flights, hotels, eSIMs and transfers, newest first, as short summaries.
- [Get a booking](https://fx-port.com/docs/api/get-account-booking.md): Get one booking of your agency, whatever its product: the summary of the history, the stored record and, for flights and hotels, the price breakdown and the balance operations.

### Suppliers
- [List suppliers](https://fx-port.com/docs/api/list-suppliers.md): List the suppliers that are enabled for your key, grouped by product: flights, hotels and eSIMs.

### Objects
- [The Error object](https://fx-port.com/docs/api/objects/error.md): The body of every failed call.
- [The Flight offer object](https://fx-port.com/docs/api/objects/flight-offer.md): One bookable flight offer of one supplier: the route, the price, the fare rules and the price of every traveler.
- [The Flight booking object](https://fx-port.com/docs/api/objects/flight-booking.md): A flight booking of your agency as FX-Port stores it: its status, price, ticket number, the links of the PDF tickets and the ACD state.
- [The Hotel mini object](https://fx-port.com/docs/api/objects/hotel-mini.md): The compact card of a hotel, made for a list of search results: its identity, place, stars, photos and amenities in 13 snake_case fields, about 5 KB.
- [The Hotel full object](https://fx-port.com/docs/api/objects/hotel-full.md): Everything FX-Port knows about one hotel, for the hotel page before checkout: the mini fields plus the description, every room type with photos and amenities, the policies, the facts and the contact details.
- [The eSIM package object](https://fx-port.com/docs/api/objects/esim-package.md): An eSIM package is a data plan you can sell: its data allowance, validity, destination, network operator and the prices for your agency.
- [The eSIM booking object](https://fx-port.com/docs/api/objects/esim-booking.md): An eSIM booking is one eSIM order or one topup of your agency: who it is for, what was bought, what it cost and which supplier fulfilled it.
- [The Account booking object](https://fx-port.com/docs/api/objects/account-booking.md): A booking of your agency in the account endpoints, whatever its product: flight, hotel, eSIM or transfer.

## Changelog

- [Changelog](https://fx-port.com/docs/changelog.md): What changed in the FX-Port API and in these docs, newest first.

## Product pages

Overviews of the API products for travel agencies. They are web pages, not Markdown: the reference of each documented product is in the sections above.

- [Flight booking API for travel agencies](https://fx-port.com/b2b-flights-api): Overview of the flights API: search, price, book (instant issue, or hold and pay later when the priced offer can be held), tickets and cancellation, with a sandbox to build against.
- [Hotel booking API for travel agencies](https://fx-port.com/b2b-hotels-api): Overview of the hotels API: geo search, rates, pre-book, book, voucher and cancellation, with test hotels in the sandbox.
- [eSIM API for travel companies](https://fx-port.com/b2b-esims-api): Overview of the eSIM API: package catalog, orders, top-ups, usage and installation instructions.
- [Airport transfers API for travel agencies (Preview)](https://fx-port.com/b2b-transfers-api): Preview of the planned airport transfers API. It is not in the OpenAPI document or in this documentation yet.

## Optional

- [OpenAPI document](https://fx-port.com/openapi.json): the machine-readable description of every endpoint (OpenAPI 3.1).
- [All pages in one file](https://fx-port.com/llms-full.txt): the complete documentation as Markdown.
- [Postman collections](https://fx-port.com/docs/environments.md): one collection per product, ready to import.
- [Names of the API](https://api.fx-port.com/api/v1/conventions/naming): every previous request spelling and snake_case response twin, as JSON (no key needed).