Skip to main content

Book Flight

Create a new booking (PNR) for one or more passengers on selected flights. This endpoint finalizes the booking after flight selection and passenger data entry.

Endpoint​

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

Authentication​

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

Authorization: Bearer <access_token>

Request Structure​

FieldTypeRequiredDescription
systemstringYesSystem code (e.g., VN, VJ, 1A)
contactobjectNoMain contact info (see below)
guestContactobjectNoGuest contact info (optional, see below)
passengersarrayYesList of passengers (see below)
flightValuesarrayYesList of encoded flight values from the response of API Select Flight
tourCodestringNoTour code (for agency/group bookings)
accountCodestringNoCorporate account code. For GDS, this value is carried in the selected flight value; for VN, use the corporate account code provided by the airline.
autoIssuebooleanNoAuto-issue ticket flag

Contact Object​

FieldTypeRequiredDescription
namestringYesContact or agency/OTA name
genderbooleanNoGender flag for the contact
titlestringNoTitle such as MR, MRS, MS, MSTR
phonestringYesContact phone number
emailstringYesContact email address
addressstringNoContact address
citystringNoContact city
countrystringNoContact country code or name
remarkstringNoAdditional contact note
receiveEmailbooleanNoWhether to send confirmation email
languagestringNoEmail language. Defaults to Vietnamese if omitted

Passenger Object​

FieldTypeRequiredDescription
indexintegerNoPassenger sequence number
passengerIdstringNoPassenger ID from Retrieve Booking when updating or reusing an existing passenger
givenNamestringYesGiven and middle name
surnamestringYesPassenger surname
typestringYesPassenger type: ADT, CHD, INF
genderbooleanNoPassenger gender
dateOfBirthstringConditionalRequired when passenger type is CHD or INF. Passenger date of birth
parentIdintegerNoAdult passenger reference for infant passengers
titlestringNoTitle such as MR, MRS, MS, MSTR
phonestringNoPassenger phone number
emailstringNoPassenger email address
documentobjectNoPassenger document information (see Passport Object)
seatMapsarrayNoPre-selected seat values for this passenger
baggagesarrayNoPre-selected baggage values for this passenger
ancillariesarrayNoPre-selected ancillary service values for this passenger
membershipobjectNoLoyalty or frequent flyer membership (see Membership Object)

Passport Object​

FieldTypeRequiredDescription
surNamestringConditionalRequired when document is provided. Surname as shown on the document
givenNamestringConditionalRequired when document is provided. Given name as shown on the document
dateOfBirthstringConditionalRequired when the passenger type is CHD or INF. Date of birth
genderbooleanNoDocument holder gender
numberstringConditionalRequired when document is provided. Document number, maximum 15 characters
typestringConditionalRequired when document is provided. Document type: P - passport, I - national ID
nationalstringNoNationality, 3-character country code
expiryDatestringConditionalRequired when document is provided, except when type = I. Document expiry date
issueCountrystringNoIssuing country, 3-character country code
issueDatestringNoDocument issue date

Membership Object​

FieldTypeRequiredDescription
airlinestringNoAirline code
membershipIdstringNoMembership or frequent flyer number
levelstringNoMembership tier level
skyTeamLevelstringNoSkyTeam tier level, if applicable

Sample Request​

{
  "system": "VN",
  "contact": {
    "name": "Nguyen Van A",
    "gender": true,
    "title": "MR",
    "phone": "+84901234567",
    "email": "a@example.com",
    "address": "123 Le Loi",
    "city": "Ho Chi Minh City",
    "country": "VN",
    "remark": "Primary booking contact",
    "receiveEmail": true,
    "language": "en"
  },
  "guestContact": {
    "name": "Tran Thi B",
    "gender": false,
    "title": "MS",
    "phone": "+84907654321",
    "email": "guest@example.com",
    "address": "456 Nguyen Hue",
    "city": "Ho Chi Minh City",
    "country": "VN",
    "remark": "Guest contact for itinerary notification",
    "receiveEmail": true,
    "language": "en"
  },
  "passengers": [
    {
      "index": 1,
      "surname": "Nguyen",
      "givenName": "Van A",
      "type": "ADT",
      "title": "MR",
      "gender": true,
      "dateOfBirth": "1990-01-01",
      "phone": "+84901234567",
      "email": "a@example.com",
      "document": {
        "surName": "NGUYEN",
        "givenName": "VAN A",
        "dateOfBirth": "1990-01-01",
        "gender": true,
        "number": "C1234567",
        "type": "P",
        "national": "VNM",
        "expiryDate": "2030-01-01",
        "issueCountry": "VNM",
        "issueDate": "2020-01-01"
      },
      "seatMaps": [
        "encoded_seat_value"
      ],
      "baggages": [
        "encoded_baggage_value"
      ],
      "ancillaries": [
        "encoded_ancillary_value"
      ],
      "membership": {
        "airline": "VN",
        "membershipId": "MEM123456",
        "level": "GOLD",
        "skyTeamLevel": "ELITE"
      }
    },
    {
      "index": 2,
      "surname": "Nguyen",
      "givenName": "Baby",
      "type": "INF",
      "title": "MSTR",
      "gender": true,
      "dateOfBirth": "2024-01-01",
      "parentId": 1,
      "document": {
        "surName": "NGUYEN",
        "givenName": "BABY",
        "dateOfBirth": "2024-01-01",
        "gender": true,
        "number": "I1234567",
        "type": "P",
        "national": "VNM",
        "expiryDate": "2030-01-01",
        "issueCountry": "VNM",
        "issueDate": "2024-02-01"
      }
    }
  ],
  "flightValues": [
    "eyJmbGlnaHRJZCI6MSwiZGVwYXJ0RGF0ZSI6IjIwMjUtMDctMTAiLCJzdGFydFBvaW50IjoiU0dOIiwiZW5kUG9pbnQiOiJIQU4iLCJhaXJsaW5lIjoiVk4iLCJmYXJlQ2xhc3MiOiJZIn0="
  ],
  "tourCode": "TOUR2026",
  "accountCode": "CORP001",
  "autoIssue": false
}

Request Constraints & Business Rules​

  • system must match the system code from the flight search/selection.
  • flightValues must be taken from the Select Flight response and must not be altered.
  • Do not use raw flightValue values from Search Flight directly for booking; call Select Flight first to verify availability and pricing.
  • All passengers must have unique names and valid types (ADT, CHD, INF).
  • Contact info must be valid and reachable.
  • For CHD and INF passengers, passenger dateOfBirth is required and must be valid.
  • For CHD and INF passengers with document information, document dateOfBirth is required.
  • If passenger document is provided, type (DocumentType), number, surName, givenName, and expiryDate are required.
  • If passenger document.type is I, expiryDate is optional.
  • Only available after a successful flight search and select.
  • Payment method must be supported by the airline/system.
  • If autoIssue is true, ticketing will be attempted immediately after booking.
  • Session/offer expiry may apply; always verify session if required.

Response Structure​

FieldTypeNullableDescription
systemstringYesName of the airline system
statusbooleanNotrue if successful, false if failed
errorobjectYesError details (if any)
descriptionstringYesError description (if any)
trackingIdstringYesTracking ID for request logs
trackingTimestringYesTime for request tracking
bookingCodestringYesBooking code (PNR)
bookingTimestringYesBooking creation time
totalAmountnumberYesTotal booking amount (fare + tax + fees)
totalFareAmountnumberYesTotal fare (excluding tax/fees)
totalTaxAmountnumberYesTotal tax
expirationDatestringYesHold expiration date
timePurchasestringYesPayment deadline
contactobjectYesContact info (see above)
guestContactobjectYesGuest contact info (if provided)
passengersarrayYesList of passengers (see BookingPassenger)
flightsarrayYesList of flight segments (see Flight)
isNDCbooleanNoWhether this is an NDC booking

Sample Response:

{
  "system": "VN",
  "status": true,
  "bookingCode": "ABC123",
  "bookingTime": "2025-07-01T08:00:00Z",
  "totalAmount": 5000000,
  "totalFareAmount": 4500000,
  "totalTaxAmount": 500000,
  "expirationDate": "2025-07-02T08:00:00Z",
  "timePurchase": "2025-07-01T18:00:00Z",
  "contact": {
    "title": "Mr",
    "name": "Nguyen Van A",
    "phone": "+84901234567",
    "email": "a@example.com"
  },
  "passengers": [
    {
      "index": 1,
      "surname": "Nguyen",
      "givenName": "Van A",
      "type": "ADT",
      "title": "MR",
      "gender": true
    }
  ],
  "flights": [
    {
      "leg": 0,
      "startPoint": "SGN",
      "endPoint": "HAN",
      "startDate": "2025-07-10T08:00:00",
      "endDate": "2025-07-10T10:00:00",
      "flightValue": "...",
      "segments": []
    }
  ],
  "isNDC": false,
  "trackingId": "abc123",
  "trackingTime": "2025-07-01T08:01:00.000Z"
}

Error Codes​

This endpoint may return the following error codes:

For a complete list of error codes, see Error Codes.

Security & Validation​

  • All input is validated for type and required fields.
  • Only authenticated users can access this endpoint.
  • The endpoint is protected against unauthorized booking attempts and data tampering.
  • Use HTTPS for all requests. Handle and store personal data in compliance with GDPR and other relevant regulations.

Validation Questions​

  • Are there limits on the number of passengers per booking?
  • Are there restrictions on combining certain passenger types (e.g., INF/CHD/ADT ratios)?
  • What are the supported payment methods for each airline/system?
  • Are there time limits for holding bookings before payment/issuance?

For integration support, see Contact Support.