Flight Search API Documentation
Overview
This API enables flight search operations with support for round-trip, one-way, and open-jaw itineraries. It returns comprehensive flight solutions including fare breakdowns, baggage rules, change/refund policies.
API Endpoint
- URL:
{{host}}/hub/flight/search
- Method:
POST
- Content-Type:
application/json
| Key |
Value |
Description |
Authorization |
Bearer {token} |
Access token (Required) |
Content-Type |
application/json |
Request/Response format |
Request Body
{
"providers": "flight.provider2",
"type": "ROUND_TRIP",
"children": 0,
"infants": 0,
"adults": 1,
"routes": [
{
"departureCode": "SGN",
"arrivalCode": "SIN",
"departureDate": "2025-11-07"
},
{
"departureCode": "SIN",
"arrivalCode": "SGN",
"departureDate": "2025-11-09"
}
],
"cabinClass": "",
"airlines": "",
"promotionCodes": "",
"directFlight": false
}
Request Body Parameters
| Field |
Type |
Required |
Description |
Example/Values |
providers |
String |
No |
Comma-separated list of providers to search. If not specified, all available providers are searched. |
"flight.provider1,flight.provider2" |
type |
String |
Yes |
Trip type |
"ROUND_TRIP", "ONE_WAY", "OPEN_JAW" |
airlines |
String |
No |
Comma-separated list of airline codes to search. If not specified, all available airlines are searched. |
"VN,QH" |
cabinClass |
String |
Yes |
Cabin class preference |
"economy", "business", "first" |
adults |
Number |
Yes |
Number of adult passengers |
1-9 |
children |
Number |
No |
Number of child passengers |
0-8 |
infants |
Number |
No |
Number of infant passengers |
0-8 |
routes |
Array |
Yes |
Array of route objects (see below) |
|
promotionCodes |
String |
No |
The promotion codes. |
|
directFlight |
Boolean |
No |
Indicates whether to search for direct flights only. Defaults to false if not provided. |
true, false |
Route Object Structure
| Field |
Type |
Required |
Description |
Example |
departureCode |
String |
✅ Yes |
IATA departure airport code |
"HAN" |
arrivalCode |
String |
✅ Yes |
IATA arrival airport code |
"DAD" |
departureDate |
String |
✅ Yes |
Departure date (YYYY-MM-DD) |
"2025-03-21" |
Sample Response
{
"solutions": [
{
"provider": "flight.provider2.VN",
"solutionId": "a50577bc7630e13b9334ada9ee9031df52712df850dccd3ff899c79754f2bc8e+GfCvlC5GSA6hFHHFHzeVIw+4c5e2ab7-e81f-4e8f-b64c-2c74cf2fcebb+++VN",
"type": "COMBINED",
"requireEnrichment": false,
"allowPayLater": true,
"isNDC": false,
"fare": {
"adultFare": {
"fare": 3295000,
"tax": 4138000,
"fee": 0,
"currency": "VND",
"discountAmount": 0,
"count": 1,
"total": 7433000,
"point": 0,
"totalPoint": 0
},
"childFare": {
"fare": 0,
"tax": 0,
"fee": 0,
"currency": "USD",
"discountAmount": 0,
"count": 0,
"total": 0,
"point": 0,
"totalPoint": 0
},
"infantFare": {
"fare": 0,
"tax": 0,
"fee": 0,
"currency": "USD",
"discountAmount": 0,
"count": 0,
"total": 0,
"point": 0,
"totalPoint": 0
},
"totalFare": 3295000,
"totalTax": 4138000,
"totalFee": 0,
"totalPrice": 7433000,
"totalDiscountAmount": 0,
"totalPoint": 0
},
"flights": [
{
"sequence": 1,
"flightDuration": 200,
"travelDuration": 200,
"journeyId": "00000000-0000-0000-0000-000000000000",
"segments": [
{
"segmentId": "1",
"sequence": 1,
"bookingCode": "E",
"cabinClass": "ECONOMY",
"available": 9,
"departureCode": "HAN",
"departureName": "Hanoi",
"departureDate": "2025-11-08",
"departureTime": "08:05",
"departureTerminal": "2",
"arrivalCode": "SIN",
"arrivalName": "Singapore",
"arrivalDate": "2025-11-08",
"arrivalTime": "12:25",
"arrivalTerminal": "3",
"airlines": "VN",
"airlinesName": "VIETNAM AIRLINES",
"equipment": "321",
"flightNumber": "661",
"flightTime": 200,
"stopTime": 0,
"baggageRules": {
"adults": [
{
"baggageAmount": "1PC"
}
]
},
"miniRules": {},
"fareBasis": "E1YVN"
}
]
},
{
"sequence": 2,
"flightDuration": 200,
"travelDuration": 200,
"journeyId": "00000000-0000-0000-0000-000000000000",
"segments": [
{
"segmentId": "2",
"sequence": 1,
"bookingCode": "Q",
"cabinClass": "ECONOMY",
"available": 9,
"departureCode": "SIN",
"departureName": "Singapore",
"departureDate": "2025-11-08",
"departureTime": "13:25",
"departureTerminal": "3",
"arrivalCode": "HAN",
"arrivalName": "Hanoi",
"arrivalDate": "2025-11-08",
"arrivalTime": "15:45",
"arrivalTerminal": "2",
"airlines": "VN",
"airlinesName": "VIETNAM AIRLINES",
"equipment": "321",
"flightNumber": "660",
"flightTime": 200,
"stopTime": 0,
"baggageRules": {
"adults": [
{
"baggageAmount": "1PC"
}
]
},
"miniRules": {},
"fareBasis": "Q1YVN"
}
]
}
]
},
{
"provider": "flight.provider2.1A",
"solutionId": "caa9437624e7a91dce3068b03feb4ea28cde6a4de21cc7bad7f327d2445ed145+CouP70K2SvG_gP4wyiHR4A+c34bf860-e02d-4664-8de7-93bf0021ddc6+++1A",
"type": "COMBINED",
"requireEnrichment": false,
"allowPayLater": true,
"isNDC": false,
"fare": {
"adultFare": {
"fare": 4797000,
"tax": 5232000,
"fee": 0,
"currency": "VND",
"discountAmount": 0,
"count": 1,
"total": 10029000,
"point": 0,
"totalPoint": 0
},
"childFare": {
"fare": 0,
"tax": 0,
"fee": 0,
"currency": "USD",
"discountAmount": 0,
"count": 0,
"total": 0,
"point": 0,
"totalPoint": 0
},
"infantFare": {
"fare": 0,
"tax": 0,
"fee": 0,
"currency": "USD",
"discountAmount": 0,
"count": 0,
"total": 0,
"point": 0,
"totalPoint": 0
},
"totalFare": 4797000,
"totalTax": 5232000,
"totalFee": 0,
"totalPrice": 10029000,
"totalDiscountAmount": 0,
"totalPoint": 0
},
"flights": [
{
"sequence": 1,
"flightDuration": 200,
"travelDuration": 200,
"journeyId": "00000000-0000-0000-0000-000000000000",
"segments": [
{
"segmentId": "1",
"sequence": 1,
"bookingCode": "G",
"cabinClass": "ECONOMY",
"available": 9,
"departureCode": "HAN",
"departureName": "Hanoi",
"departureDate": "2025-11-08",
"departureTime": "09:35",
"departureTerminal": "2",
"arrivalCode": "SIN",
"arrivalName": "Singapore",
"arrivalDate": "2025-11-08",
"arrivalTime": "13:55",
"arrivalTerminal": "4",
"airlines": "A1",
"airlinesName": "A.P.G. DISTRIBUTION SYSTEM",
"equipment": "321",
"flightNumber": "2915",
"flightTime": 200,
"stopTime": 0,
"baggageRules": {
"adults": [
{
"baggageAmount": "1PC",
"baggageWeight": "20kg",
"carryOnAmount": "1PC",
"carryOnWeight": "7kg"
}
]
},
"miniRules": {},
"fareBasis": "GAPVJ"
}
]
},
{
"sequence": 2,
"flightDuration": 255,
"travelDuration": 550,
"journeyId": "00000000-0000-0000-0000-000000000000",
"segments": [
{
"segmentId": "2",
"sequence": 1,
"bookingCode": "G",
"cabinClass": "ECONOMY",
"available": 9,
"departureCode": "SIN",
"departureName": "Singapore",
"departureDate": "2025-11-08",
"departureTime": "17:00",
"departureTerminal": "4",
"arrivalCode": "SGN",
"arrivalName": "Ho Chi Minh City",
"arrivalDate": "2025-11-08",
"arrivalTime": "18:05",
"arrivalTerminal": "2",
"airlines": "A1",
"airlinesName": "A.P.G. DISTRIBUTION SYSTEM",
"equipment": "321",
"flightNumber": "2814",
"flightTime": 125,
"stopTime": 295,
"baggageRules": {
"adults": [
{
"baggageAmount": "1PC",
"baggageWeight": "20kg",
"carryOnAmount": "1PC",
"carryOnWeight": "7kg"
}
]
},
"miniRules": {},
"fareBasis": "GAPVJ"
},
{
"segmentId": "3",
"sequence": 2,
"bookingCode": "G",
"cabinClass": "ECONOMY",
"available": 9,
"departureCode": "SGN",
"departureName": "Ho Chi Minh City",
"departureDate": "2025-11-08",
"departureTime": "23:00",
"departureTerminal": "1",
"arrivalCode": "HAN",
"arrivalName": "Hanoi",
"arrivalDate": "2025-11-09",
"arrivalTime": "01:10",
"arrivalTerminal": "1",
"airlines": "A1",
"airlinesName": "A.P.G. DISTRIBUTION SYSTEM",
"equipment": "320",
"flightNumber": "4152",
"flightTime": 130,
"stopTime": 0,
"baggageRules": {
"adults": [
{
"baggageAmount": "1PC",
"baggageWeight": "20kg",
"carryOnAmount": "1PC",
"carryOnWeight": "7kg"
}
]
},
"miniRules": {},
"fareBasis": "GAPVJ"
}
]
}
]
},
{
"provider": "flight.provider2.1A",
"solutionId": "caa9437624e7a91dce3068b03feb4ea28cde6a4de21cc7bad7f327d2445ed145+qu0aCYHfSN2NHWjO1ALHzQ+1bbb1926-edec-4d59-ab7c-5a3584f64a14+++1A",
"type": "COMBINED",
"requireEnrichment": false,
"allowPayLater": true,
"isNDC": false,
"fare": {
"adultFare": {
"fare": 4797000,
"tax": 5232000,
"fee": 0,
"currency": "VND",
"discountAmount": 0,
"count": 1,
"total": 10029000,
"point": 0,
"totalPoint": 0
},
"childFare": {
"fare": 0,
"tax": 0,
"fee": 0,
"currency": "USD",
"discountAmount": 0,
"count": 0,
"total": 0,
"point": 0,
"totalPoint": 0
},
"infantFare": {
"fare": 0,
"tax": 0,
"fee": 0,
"currency": "USD",
"discountAmount": 0,
"count": 0,
"total": 0,
"point": 0,
"totalPoint": 0
},
"totalFare": 4797000,
"totalTax": 5232000,
"totalFee": 0,
"totalPrice": 10029000,
"totalDiscountAmount": 0,
"totalPoint": 0
},
"flights": [
{
"sequence": 1,
"flightDuration": 200,
"travelDuration": 200,
"journeyId": "00000000-0000-0000-0000-000000000000",
"segments": [
{
"segmentId": "1",
"sequence": 1,
"bookingCode": "G",
"cabinClass": "ECONOMY",
"available": 9,
"departureCode": "HAN",
"departureName": "Hanoi",
"departureDate": "2025-11-08",
"departureTime": "09:35",
"departureTerminal": "2",
"arrivalCode": "SIN",
"arrivalName": "Singapore",
"arrivalDate": "2025-11-08",
"arrivalTime": "13:55",
"arrivalTerminal": "4",
"airlines": "A1",
"airlinesName": "A.P.G. DISTRIBUTION SYSTEM",
"equipment": "321",
"flightNumber": "2915",
"flightTime": 200,
"stopTime": 0,
"baggageRules": {
"adults": [
{
"baggageAmount": "1PC",
"baggageWeight": "20kg",
"carryOnAmount": "1PC",
"carryOnWeight": "7kg"
}
]
},
"miniRules": {},
"fareBasis": "GAPVJ"
}
]
},
{
"sequence": 2,
"flightDuration": 255,
"travelDuration": 565,
"journeyId": "00000000-0000-0000-0000-000000000000",
"segments": [
{
"segmentId": "2",
"sequence": 1,
"bookingCode": "G",
"cabinClass": "ECONOMY",
"available": 9,
"departureCode": "SIN",
"departureName": "Singapore",
"departureDate": "2025-11-08",
"departureTime": "17:00",
"departureTerminal": "4",
"arrivalCode": "SGN",
"arrivalName": "Ho Chi Minh City",
"arrivalDate": "2025-11-08",
"arrivalTime": "18:05",
"arrivalTerminal": "2",
"airlines": "A1",
"airlinesName": "A.P.G. DISTRIBUTION SYSTEM",
"equipment": "321",
"flightNumber": "2814",
"flightTime": 125,
"stopTime": 310,
"baggageRules": {
"adults": [
{
"baggageAmount": "1PC",
"baggageWeight": "20kg",
"carryOnAmount": "1PC",
"carryOnWeight": "7kg"
}
]
},
"miniRules": {},
"fareBasis": "GAPVJ"
},
{
"segmentId": "3",
"sequence": 2,
"bookingCode": "G",
"cabinClass": "ECONOMY",
"available": 9,
"departureCode": "SGN",
"departureName": "Ho Chi Minh City",
"departureDate": "2025-11-08",
"departureTime": "23:15",
"departureTerminal": "1",
"arrivalCode": "HAN",
"arrivalName": "Hanoi",
"arrivalDate": "2025-11-09",
"arrivalTime": "01:25",
"arrivalTerminal": "1",
"airlines": "A1",
"airlinesName": "A.P.G. DISTRIBUTION SYSTEM",
"equipment": "321",
"flightNumber": "2168",
"flightTime": 130,
"stopTime": 0,
"baggageRules": {
"adults": [
{
"baggageAmount": "1PC",
"baggageWeight": "20kg",
"carryOnAmount": "1PC",
"carryOnWeight": "7kg"
}
]
},
"miniRules": {},
"fareBasis": "GAPVJ"
}
]
}
]
}
]
}
Response Field Description
This document describes the JSON response body for a flight search solution returned by the flight search API endpoint. This is a single item within the solutions array.
| Field |
Type |
Description |
provider |
String |
The ID of the flight provider for this solution. |
solutionId |
String |
A unique identifier for this flight solution. This ID is used for booking. |
type |
String |
The type of flight booking. Example: "COMBINED" |
fare |
Object |
Detailed fare information for this flight solution. See Fare Object Structure. |
isNDC |
Bool |
Indicates whether the flight is distributed through an NDC (New Distribution Capability) channel. |
requireEnrichment |
Bool |
Require enrich information for this flight solution.
If it's true, you must call Enrich API ({{host}}/hub/flight/enrich). |
allowPayLater |
Bool |
Allow to pay later. |
flights |
Array |
Array of objects detailing the flight legs. See Flights Array Structure. |
Fare Object Structure
| Field |
Type |
Description |
adultFare |
Object |
Fare details for adult passengers. See Passenger Fare Object Structure. |
childFare |
Object |
Fare details for child passengers. See Passenger Fare Object Structure. |
infantFare |
Object |
Fare details for infant passengers. See Passenger Fare Object Structure. |
totalFare |
Number |
The sum of the base fares for all passengers (excluding taxes and fees). |
totalTax |
Number |
The sum of the taxes for all passengers. |
totalFee |
Number |
The sum of the fees for all passengers. |
totalPrice |
Number |
The grand total price for all passengers (base fare + taxes + fees). |
totalDiscountAmount |
Number |
The sum of the discounts for all passengers. |
totalPoint |
Number |
The sum of the points for all passengers. |
Passenger Fare Object Structure (adultFare, childFare, infantFare)
| Field |
Type |
Description |
fare |
Number |
The base fare for this passenger type. |
tax |
Number |
Taxes for this passenger type. |
fee |
Number |
Fees for this passenger type. |
currency |
String |
Currency code for the fare elements (e.g., "USD"). |
count |
Integer |
Number of passengers of this type. |
total |
Number |
Total fare including taxes and fees, for this type. |
point |
Integer |
Points of the voucher. |
totalPoint |
Integer |
The total points (point * count). |
Flights Array Structure
| Field |
Type |
Description |
sequence |
Integer |
Flight leg sequence (1=outbound, 2=return). Starts from 1. |
flightDuration |
Integer |
Total flight time in minutes for the entire leg. |
travelDuration |
Integer |
Total travel time in minutes for the entire leg (including layovers). |
journeyId |
String |
The journey object that groups all flight segments of a single trip. |
segments |
Array |
An array containing information about each segment of the flight leg. See Segments Array Structure. |
Segments Array Structure
| Field |
Type |
Description |
segmentId |
String |
Unique identifier for the flight segment. |
sequence |
Integer |
Segment order within the leg. |
bookingCode |
String |
Fare class code (e.g., "X"). Consult the airline for the specific meaning of the booking code. |
cabinClass |
String |
Cabin class for the segment (e.g., "ECONOMY"). |
available |
Integer |
Number of seats available in this class. |
departureCode |
String |
IATA departure airport code (e.g., "SGN"). |
departureName |
String |
Departure airport name (e.g., "Ho Chi Minh City"). |
departureDate |
String |
Departure date (YYYY-MM-DD) (e.g., "2025-06-20"). |
departureTime |
String |
Departure time (HH:mm) (e.g., "12:50"). |
departureTerminal |
String |
Departure terminal (e.g., "1"). |
arrivalCode |
String |
IATA arrival airport code (e.g., "HAN"). |
arrivalName |
String |
Arrival airport name (e.g., "Hanoi"). |
arrivalDate |
String |
Arrival date (YYYY-MM-DD) (e.g., "2025-06-20"). |
arrivalTime |
String |
Arrival time (HH:mm) (e.g., "15:00"). |
arrivalTerminal |
String |
Arrival terminal (e.g., "1"). |
airlines |
String |
2-letter airline code (e.g., "QH"). |
airlinesName |
String |
Airline name (e.g., "BAMBOO AIRWAYS"). |
equipment |
String |
Aircraft type (e.g., "JET"). |
flightNumber |
String |
Flight number (e.g., "242"). |
flightTime |
Integer |
Flight time in minutes. |
stopTime |
Integer |
Layover time in minutes (0 for direct flights). |
baggageRules |
Object |
Baggage rules for this segment. See Baggage Rules Object. |
miniRules |
Object |
Rules regarding penalties, refunds, and reissues. See Mini Rules Object. |
fareBasis |
String |
Indicates the fare basis code that defines the fare type and rules applied to the ticket. |
Baggage Rules Object
| Field |
Type |
Description |
adults |
Array |
Baggage rules for adult passengers. See Baggage Rule Details Object. |
children |
Array |
Baggage rules for child passengers. See Baggage Rule Details Object. |
infants |
Array |
Baggage rules for infant passengers. |
Baggage Rule Details Object
| Field |
Type |
Description |
baggageAmount |
String |
Amount of checked baggage allowed (e.g., "0PC" for 0 pieces). |
baggageWeight |
String |
Weight of checked baggage allowed (e.g., "7KG" for 7 kilograms). |
carryOnAmount |
String |
Amount of Carry-on baggage allowed (e.g., "1PC" for 1 pieces). |
carryOnWeight |
String |
Weight of Carry-on baggage allowed (e.g., "7KG" for 7 kilograms). |
Mini Rules Object
| Field |
Type |
Description |
adults |
Array |
Penalty rules for adults. See Penalty Rule Object. |
children |
Array |
Penalty rules for children. See Penalty Rule Object. |
infants |
Array |
Penalty rules for infants. |
Penalty Rule Object
| Field |
Type |
Description |
miniruleText |
String |
The rule text. |
miniruleHtml |
String |
The rule html. |
penaltyType |
String |
The type of penalty (e.g., "REFUND", "REISSUE"). |
allowRefund |
String |
Indicates if a refund is allowed ("NOT_ALLOWED"). |
situation |
String |
When the penalty applies ("BEFORE_DEPARTURE", "AFTER_DEPARTURE"). |
noShowTime |
String |
No-show timing relative to departure. |
noShowTimeUnit |
String |
Time unit for the no-show period. |
amount |
Number |
A general fee amount. |
currency |
String |
The currency code (e.g., "USD"). |
percent |
Number |
The penalty amount as a percentage of the fare. |
baseType |
String |
The basis for the penalty calculation (e.g., "FARE"). |