# API reference

> Every endpoint of the FX-Port API: parameters, request and response objects, examples in nine languages and the errors each can return.

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

The FX-Port API is a REST API with predictable URLs, JSON request and response bodies, and standard HTTP status codes. Use it from your server to search, price and book flights and hotels, sell eSIMs, and read your balances and bookings. This reference is generated from the [OpenAPI document](https://fx-port.com/openapi.json), so it always matches what the API accepts and returns. New here? Start with the [Quickstart](https://fx-port.com/docs/quickstart.md).

## Base URL

~~~
https://api.fx-port.com/api/v1
~~~

Live and sandbox share the base URL: the **key** you send decides which environment a request belongs to. Keys start with `fxp_test_` for the sandbox and `fxp_live_` for live. Every path in this reference is relative to the base URL.

## Authentication

Send your key as a bearer token:

~~~http
Authorization: Bearer fxp_test_YOUR_KEY
~~~

Create keys in the [dashboard](https://fx-port.com/dashboard/api). A **Read** key can search, price and read; a **Read+Write** key can also book, pay and cancel. Each endpoint page says which one it needs. See [Authentication](https://fx-port.com/docs/authentication.md) and [Security](https://fx-port.com/docs/security.md).

## Requests and responses

- Bodies are JSON (`Content-Type: application/json`), except the ACD passport upload, which is `multipart/form-data`.
- Request fields use `snake_case`. Older endpoints also accept their legacy `camelCase` spellings, and the reference marks them as deprecated and names the spelling to use: see [Conventions and naming](https://fx-port.com/docs/conventions.md) and the [list of legacy names](https://fx-port.com/docs/legacy-names.md). Responses keep their older keys and add `snake_case` twins; `?naming=snake` returns `snake_case` only.
- Every JSON response starts with an `environment` field (`sandbox` or `live`), also sent in the `X-Environment` header, and carries a `request_id` (also the `X-Request-Id` header) to quote to support.
- Prices come back in the currency of the agency that owns the key. You never send a currency.
- The travel dates in the examples are fixed dates: send a date 30 to 60 days ahead, because a date in the past is refused with `date_in_past`.
- A failed call returns the same error body everywhere (`errors[].code`, `errors[].type`, `errors[].message`): see [Errors](https://fx-port.com/docs/errors.md).
- Keys are limited per minute: see [Rate limits](https://fx-port.com/docs/rate-limits.md). Flight searches can be streamed: see [Streaming](https://fx-port.com/docs/streaming.md).

## Endpoints


| Method | Path | Permission | Description |
| --- | --- | --- | --- |
| `GET` | `/api/v1/flights/airports` | None | [Search airports](https://fx-port.com/docs/api/search-airports.md) |
| `GET` | `/api/v1/flights/top-airports` | None | [Get the most searched airports](https://fx-port.com/docs/api/top-airports.md) |
| `POST` | `/api/v1/get_flights` | Read | [Search flights](https://fx-port.com/docs/api/get-flights.md) |
| `POST` | `/api/v1/flights/flexible_search` | Read | [Search flexible dates](https://fx-port.com/docs/api/flexible-search.md) |
| `POST` | `/api/v1/flights/price_flight` | Read | [Price a flight offer](https://fx-port.com/docs/api/price-flight.md) |
| `POST` | `/api/v1/flights/book_flight` | Read+Write | [Book a flight offer](https://fx-port.com/docs/api/book-flight.md) |
| `POST` | `/api/v1/flights/get_booking` | Read | [Get a flight booking](https://fx-port.com/docs/api/get-booking.md) |
| `POST` | `/api/v1/flights/get_ticket` | Read | [Get the ticket PDF of a booking](https://fx-port.com/docs/api/get-ticket.md) |
| `POST` | `/api/v1/flights/get_ticket_number` | Read | [Get the e-ticket number of a booking](https://fx-port.com/docs/api/get-ticket-number.md) |
| `POST` | `/api/v1/flights/get_order_quote` | Read | [Get the current quote of an order](https://fx-port.com/docs/api/get-order-quote.md) |
| `POST` | `/api/v1/flights/pay_order` | Read+Write | [Pay a held order and issue the tickets](https://fx-port.com/docs/api/pay-order.md) |
| `POST` | `/api/v1/flights/cancel_order` | Read+Write | [Cancel a held reservation](https://fx-port.com/docs/api/cancel-order.md) |
| `POST` | `/api/v1/flights/cancel_quote` | Read | [Quote the refund of an issued order](https://fx-port.com/docs/api/cancel-quote.md) |
| `POST` | `/api/v1/flights/confirm_cancel` | Read+Write | [Confirm the cancellation of an order](https://fx-port.com/docs/api/confirm-cancel.md) |
| `POST` | `/api/v1/flights/get_acd_documents` | Read | [Get the ACD document state of a booking](https://fx-port.com/docs/api/get-acd-documents.md) |
| `POST` | `/api/v1/flights/upload_acd_documents` | Read+Write | [Upload ACD passport documents](https://fx-port.com/docs/api/upload-acd-documents.md) |
| `GET` | `/api/v1/hotels/locations/search` | Read | [Search destinations and get coordinates](https://fx-port.com/docs/api/search-hotel-locations.md) |
| `GET` | `/api/v1/hotels/name-search` | Read | [Find a hotel by name](https://fx-port.com/docs/api/get-hotel-name-search.md) |
| `POST` | `/api/v1/hotels/search-by-name` | Read | [Find a hotel by name (JSON body)](https://fx-port.com/docs/api/post-hotel-name-search.md) |
| `POST` | `/api/v1/hotels/search_advanced` | Read | [Geo search: hotels around a point](https://fx-port.com/docs/api/search-hotels.md) |
| `POST` | `/api/v1/hotels/search` | Read | [Read the content of many hotels by id](https://fx-port.com/docs/api/get-hotel-content.md) |
| `POST` | `/api/v1/hotels/details` | Read | [Read the raw hotel documents by id](https://fx-port.com/docs/api/get-hotel-details.md) |
| `POST` | `/api/v1/hotels/get_hotel_info` | Read | [Read one hotel for the hotel page](https://fx-port.com/docs/api/get-hotel-info.md) |
| `POST` | `/api/v1/hotels/get_rates` | Read | [Get the rooms and rates of one hotel](https://fx-port.com/docs/api/get-hotel-rates.md) |
| `POST` | `/api/v1/hotels/pre_book` | Read+Write | [Lock a rate before booking](https://fx-port.com/docs/api/pre-book-hotel.md) |
| `POST` | `/api/v1/hotels/book_hotel` | Read+Write | [Book a locked rate](https://fx-port.com/docs/api/book-hotel.md) |
| `POST` | `/api/v1/hotels/cancel_hotel` | Read+Write | [Cancel a confirmed hotel booking](https://fx-port.com/docs/api/cancel-hotel.md) |
| `GET` | `/api/v1/hotels/get_voucher` | Read | [Get the voucher PDF links of a booking](https://fx-port.com/docs/api/get-hotel-voucher.md) |
| `GET` | `/api/v1/esims/packages` | Read | [List eSIM packages](https://fx-port.com/docs/api/list-esim-packages.md) |
| `GET` | `/api/v1/esims/compatible-devices` | Read | [List eSIM compatible devices](https://fx-port.com/docs/api/list-esim-compatible-devices.md) |
| `POST` | `/api/v1/esims/orders` | Read+Write | [Create an eSIM order](https://fx-port.com/docs/api/create-esim-order.md) |
| `GET` | `/api/v1/esims/topup-packages/{iccid}` | Read | [List topup packages of an eSIM](https://fx-port.com/docs/api/list-esim-topup-packages.md) |
| `POST` | `/api/v1/esims/topups` | Read+Write | [Top up an eSIM](https://fx-port.com/docs/api/create-esim-topup.md) |
| `GET` | `/api/v1/esims/usage/{iccid}` | Read | [Get the usage of an eSIM](https://fx-port.com/docs/api/get-esim-usage.md) |
| `GET` | `/api/v1/esims/usage/bulk` | Read | [Get the usage of several eSIMs](https://fx-port.com/docs/api/get-esim-usage-bulk.md) |
| `GET` | `/api/v1/esims/bookings` | Read | [List eSIM bookings](https://fx-port.com/docs/api/list-esim-bookings.md) |
| `GET` | `/api/v1/esims/bookings/{iccid}/topup-history` | Read | [List the topups of an eSIM](https://fx-port.com/docs/api/list-esim-topup-history.md) |
| `GET` | `/api/v1/esims/bookings/{booking_id}/verify` | Read | [Check that an eSIM booking is yours](https://fx-port.com/docs/api/verify-esim-booking.md) |
| `GET` | `/api/v1/esims/bookings/{booking_id}/setup-instructions` | Read | [Get the setup data of a booking](https://fx-port.com/docs/api/get-esim-setup-instructions.md) |
| `GET` | `/api/v1/esims/instructions/{iccid}` | Read | [Get eSIM installation instructions](https://fx-port.com/docs/api/get-esim-instructions.md) |
| `GET` | `/api/v1/balances` | Read | [List balances](https://fx-port.com/docs/api/list-balances.md) |
| `GET` | `/api/v1/balances/{balance_id}/history` | Read | [Get the history of a balance](https://fx-port.com/docs/api/get-balance-history.md) |
| `GET` | `/api/v1/history` | Read | [List booking history](https://fx-port.com/docs/api/list-booking-history.md) |
| `GET` | `/api/v1/bookings/{booking_id}` | Read | [Get a booking](https://fx-port.com/docs/api/get-account-booking.md) |
| `GET` | `/api/v1/suppliers` | Read | [List suppliers](https://fx-port.com/docs/api/list-suppliers.md) |


## For tools and AI

The whole reference is one file: [`/openapi.json`](https://fx-port.com/openapi.json) (OpenAPI 3.1, with an `operationId`, examples and error codes for every endpoint). Every page of this site is also available as Markdown by adding `.md` to its address, and [`/llms.txt`](https://fx-port.com/llms.txt) indexes them. See [Use these docs with AI](https://fx-port.com/docs/ai-tools.md).