Search Flight

Search for available flights based on origin, destination, travel dates, and passenger information. This is the primary endpoint for finding flight options before booking.

---

Endpoint

• URL: /api/v1/flight/search
• Method: POST
• Auth Required: Yes (Bearer Token/X-API-KEY)
• Content-Type: application/json

---

Authentication

This endpoint requires a valid JWT Bearer token in the Authorization header:

Authorization: Bearer <access_token>

Obtain tokens via /api/v1/sign-in (POST) with your credentials.

---

Request Structure

Field	Type	Required	Description
system	string	Yes	Airline system code
adt	integer	Yes	Number of adult passengers
chd	integer	No	Number of child passengers
inf	integer	No	Number of infant passengers
flights	array	Yes	List of flight segments (see FlightRequest)
specialType	string	No	Special passenger type (STU, YTH, SEA, ...)
promoCode	string	No	Airline discount/coupon code
airlines	array	No	List of preferred airline codes (2-letter IATA codes)
pricingType	integer	No	Pricing type preference: 0 - All, 1 - GDS, 2 - NDC
combine	boolean	No	Combine multi-segment tickets (applies to VN)

FlightRequest Object

Field	Type	Required	Description
leg	integer	Yes	Flight segment sequence number
startPoint	string	Yes	Departure airport code (3-letter IATA)
endPoint	string	Yes	Arrival airport code (3-letter IATA)
departDate	DateOnly	Yes	Departure date (YYYY-MM-DD format)

Example Request:

{
  "system": "VN",
  "adt": 1,
  "chd": 0,
  "inf": 0,
  "flights": [
    {
      "leg": 1,
      "startPoint": "SGN",
      "endPoint": "HAN",
      "departDate": "2024-06-02"
    }
  ],
  "specialType": null,
  "promoCode": null,
  "airlines": ["VN"],
  "pricingType": 0,
  "combine": false
}

---

Request Constraints & Business Rules

• At least one adult passenger (adt >= 1) is required.
• Child passengers must be accompanied by adults.
• Infant passengers count cannot exceed adult passenger count.
• departDate must be in the future.
• Airport codes must be valid 3-letter IATA codes.
• Special types have specific eligibility requirements:
  • STU: Student
  • SEA: Seaman
  • LAB: Labor
  • VG2/VG4/VG6/VG8: Groups are specific for Vietnam Airlines
• Multi-city searches can include up to 6 segments.

---

Response Structure

Returns an array of TripOtaFlightSearchResponse objects:

Field	Type	Nullable	Description
system	string	Yes	System name (e.g., VN, VJ, 1A)
status	boolean	No	true if successful, false if failed
error	object	Yes	Error details (if any)
description	string	Yes	Error description (if any)
trackingId	string	Yes	Tracking ID for request logs
trackingTime	string	Yes	Time for request tracking (ISO 8601 format)
fareDatas	array	Yes	List of available flight options (see FareData)

FareData Object

Field	Type	Nullable	Description
fareDataId	integer	No	Unique identifier for this fare option
itinerary	integer	No	Itinerary sequence number
currency	string	Yes	Currency code (e.g., VND, USD)
system	string	Yes	Booking system code
adt	integer	No	Number of adults
chd	integer	No	Number of children
inf	integer	No	Number of infants
fareAdt	number	No	Base fare per adult
fareChd	number	No	Base fare per child
fareInf	number	No	Base fare per infant
taxAdt	number	No	Taxes and fees per adult
taxChd	number	No	Taxes and fees per child
taxInf	number	No	Taxes and fees per infant
priceAdt	number	No	Total price per adult (base fare + taxes)
priceChd	number	No	Total price per child (base fare + taxes)
priceInf	number	No	Total price per infant (base fare + taxes)
totalFare	number	No	Total base fare for all passengers
totalTax	number	No	Total taxes and fees for all passengers
totalPrice	number	No	Total amount for all passengers
pricingType	integer	Yes	Pricing type: 0 - All, 1 - GDS, 2 - NDC
isDomestic	boolean	No	Whether this is a domestic flight
options	array	Yes	List of flight options (see Option)

Option Object

Field	Type	Nullable	Description
optionId	integer	No	Unique identifier for this fare option
flights	array	Yes	List of flight (see Option)

Flight Object

Field	Type	Nullable	Description
leg	integer	No	Leg index: 0 - Outbound, 1 - Return
startPoint	string	Yes	Departure airport code (IATA)
endPoint	string	Yes	Arrival airport code (IATA)
startPointUtcOffset	TimeSpan	Yes	UTC offset of departure location
endPointUtcOffset	TimeSpan	Yes	UTC offset of arrival location
startDate	datetime	Yes	Departure date and time (ISO 8601 format, e.g., 2025-12-20T18:55:00)
endDate	datetime	Yes	Arrival date and time (ISO 8601 format, e.g., 2025-12-20T21:00:00)
duration	integer	No	Total flight duration (in minutes, read-only)
flightValue	string	Yes	Encoded flight value for use in related functions
stopNum	integer	No	Number of stops (read-only)
noRefund	boolean	No	true if the fare is non-refundable
promo	boolean	No	true if this is a promotional fare
timeLimit	datetime	Yes	Time limit to issue ticket
segments	array	Yes	List of segments making up the flight (see Segment below)

Segment Object

Field	Type	Nullable	Description
id	integer	No	Unique identifier for the segment
startPoint	string	Yes	Departure airport code (IATA)
endPoint	string	Yes	Arrival airport code (IATA)
startPointUtcOffset	TimeSpan	Yes	UTC offset at departure
endPointUtcOffset	TimeSpan	Yes	UTC offset at arrival
startDate	datetime	Yes	Departure time (ISO 8601 format, e.g., 2025-12-20T18:55:00)
endDate	datetime	Yes	Arrival time (ISO 8601 format, e.g., 2025-12-20T21:00:00)
startTerminal	string	Yes	Departure terminal
endTerminal	string	Yes	Arrival terminal
flightNumber	string	Yes	Flight number
plane	string	Yes	Aircraft code/model
status	string	Yes	Booking status
fareClass	string	Yes	Booking class (e.g., Y, M, B, etc.)
fareBasis	string	Yes	Fare basis code
duration	integer	No	Segment duration (minutes, read-only)
cabinCode	string	Yes	Cabin code (Y - Economy, C - Business, F - First, etc.)
hasStop	boolean	No	If the flight has technical or planned stop
handBaggage	string	Yes	Cabin baggage allowance
freeBaggage	string	Yes	Checked baggage allowance
stopPoint	string	Yes	Stop airport code (if any)
stopTime	number	Yes	Duration of stop (minutes)
stopOvernight	boolean	No	Indicates if overnight stop exists
changeStation	boolean	No	Indicates change of train/station
changeAirport	boolean	No	Indicates change of airport
marketingCarrier	string	Yes	Marketing carrier (IATA code)
operatingCarrier	string	Yes	Operating carrier (IATA code)
dayChange	boolean	No	Indicates if arrival is on different day than departure
marriageGrp	boolean	Yes	Marriage group status
flightsMiles	integer	Yes	Distance in miles
technicalStop	string	Yes	Code/location for technical stop (if any)

Example Response:

[
  {
    "system": "string",
    "status": true,
    "error": {
      "id": 0,
      "message": "string"
    },
    "description": "string",
    "trackingId": "string",
    "timeTracking": "2025-08-25T08:18:53.001Z",
    "fareDatas": [
      {
        "fareDataId": 0,
        "itinerary": 0,
        "currency": "string",
        "adt": 0,
        "chd": 0,
        "inf": 0,
        "fareAdt": 0,
        "fareChd": 0,
        "fareInf": 0,
        "taxAdt": 0,
        "taxChd": 0,
        "taxInf": 0,
        "priceAdt": 0,
        "priceChd": 0,
        "priceInf": 0,
        "totalFare": 0,
        "totalTax": 0,
        "totalPrice": 0,
        "pricingType": 0,
        "isDomestic": true,
        "options": [
          {
            "optionId": 0,
            "flights": [
              {
                "leg": 0,
                "startPoint": "string",
                "endPoint": "string",
                "startPointUtcOffset": {},
                "endPointUtcOffset": {},
                "startDate": "2025-08-25T08:18:00",
                "endDate": "2025-08-25T10:18:00",
                "duration": 0,
                "flightValue": "string",
                "stopNum": 0,
                "noRefund": true,
                "promo": true,
                "timeLimit": "2025-08-25T08:18:53.001Z",
                "segments": [
                  {
                    "id": 0,
                    "id": 0,
                    "startPoint": "string",
                    "endPoint": "string",
                    "startPointUtcOffset": {},
                    "endPointUtcOffset": {},
                    "startDate": "2025-08-25T08:18:00",
                    "endDate": "2025-08-25T10:18:00",
                    "startTerminal": "string",
                    "endTerminal": "string",
                    "flightNumber": "string",
                    "plane": "string",
                    "status": "string",
                    "fareClass": "string",
                    "fareBasis": "string",
                    "duration": 0,
                    "cabinCode": "string",
                    "hasStop": true,
                    "handBaggage": "string",
                    "freeBaggage": "string",
                    "stopPoint": "string",
                    "stopTime": 0.0,
                    "stopOvernight": true,
                    "changeStation": true,
                    "changeAirport": true,
                    "marketingCarrier": "string",
                    "operatingCarrier": "string",
                    "dayChange": true,
                    "marriageGrp": true,
                    "flightsMiles": 0,
                    "technicalStop": "string"
                  }
                ],
                "timeLimit": "2025-08-25T08:18:53.001Z"
              }
            ]
          }
        ]
      }
    ]
  }
]

---

Error Codes

See Error Codes for details on possible error responses.

---

Security & Validation

• All input is validated for type and required fields.
• Only authenticated users can access this endpoint.
• Airport codes are validated against IATA standards.
• Date validation ensures future travel dates only and less than 365 from current.
• Passenger count validation ensures logical combinations.

---

Validation Questions

• What is the maximum number of passengers allowed per search?
• Are there restrictions on how far in advance flights can be searched?
• How are connecting flights handled in multi-city searches?
• What special types are available for each airline system?

---

For integration support, see Contact Support.