POST /reservations

The /reservations API is used to create, read and delete bookings and reprice flights.

The POST verb will create a booking.

Verb URI Description
POST /reservations/{ver}/{airline} Create a booking

Book & Hold vs. Book & Ticket
When creating a booking, you can do what is known as ‘book and hold’, or you can ‘book and ticket’. In the book and hold scenario, the booking is created on the SITA reservations system and is held for a period of time (max 24 hours). The user must then pay for the booking offline (via call centre or sales office) to actually get a ticket. In the book and ticket scenario, the payment details are supplied when creating a booking and payment is taken, and the tickets are issued. In most cases, the user will book and ticket.

Paying with Credit Card
When paying for a booking with credit card, these details are passed in the POST data in the creditCardPaymentInfo object.

Paying with PayPal
When paying with PayPal, it is necessary to call the /reservations/payPalExpressCheckout API as the first step. This will generate the necessary correlation Id and payPal URL to redirect the user to a web page to perform the PayPal authorisation. After PayPal authorisation, the /reservations API can be called to create the booking. Therefore, the sequence of events is:

1. GET /reservations/payPalExpressCheckout API
2. Redirect to PayPal mobile site to do authorisations
3. On redirect back from PayPal, call the POST /reservations API

Adding Frequent Flyer Numbers
If a frequent flyer number is not valid, it may be rejected by the SITA RES system, for example, if the name of the passenger does not correspond to the name on the frequent flyer account. When this happens, the reservation is still created, and an OTAWarning is added to state that the Frequent Flyer number could not be added for the specific passenger.

Path Parameters

Path Parameter Notes Example
ver API Version number v1
airline 2 character IATA code. MH

Query Parameters (for Email and SMS Notifications)

Query Parameter Notes Example
sendSMSConfirmation Send it with value “true” if request SMS confirmation true or false
sendEmailConfirmation Send it with value “true” if request Email confirmation true or false
Channel Associate it with the email and SMS template.
If not sent, default template will be used
MOBILEWEB, ANDROID, IPHONE, IPAD
ConfirmationURL The URL to display the booking detail itravel/viewBooking.xhmtl=$detail.pnr&l={lastName}
clientAppName The name of the Application that made the booking MHmobile

POST Data

The post data contains the passenger information, the magicString (from the /shop response) and the payment details.

  • passengers : This is an array of passenger objects. All passenger objects must provide surname, givenName, email, phoneNumber and paxType. Child (paxType=”CNN”) and Infant (paxType=”INF”) passengers must provide a dateOfBirth in yyyy-MM-dd format. For children and infant passengers, the email & phone number is generally the same as the lead passenger.
  • magicString : The magicString is taken from the GET /shop API result.
  • creditCardPaymentInfo : When paying by credit or debit card, this object contains the card details. The cardType specifies the card type (1= Credit Card, 2= Debit Card) and the cardCode specifies the issuer (VI, AX, CA).

Example


{
  "passengers": [
    {
      "surname": "COOPER",
      "givenName": "ADTONE",
      "email": "kevin.osullivan0@sita.aero",
      "phoneNumber": "+447770728190",
      "paxType": "ADT",
      "ffqNumber": "304250446",
      "ffqAirline": "MH",
     “SSR”:”
    },
    {
      "surname": "COOPER",
      "givenName": "ADTTWO",
      "email": "kevin.osullivan1@sita.aero",
      "phoneNumber": "+447770728191",
      "paxType": "ADT",
      "ffqNumber": "304250446",
      "ffqAirline": "MH"
    },
    {
      "surname": "COOPER",
      "givenName": "INFONE",
      "email": "kevin.osullivan0@sita.aero",
      "phoneNumber": "+447770728190",
      "paxType": "INF",
      "dateOfBirth": "2012-01-01"
    }
  ],
  "magicString": "+=+=+= EXCLUDED FOR BREVITY +=+=+=",
  "creditCardPaymentInfo": {
    "cardType": 1,
    "cardCode": "VI",
    "cardNumber": "4200000000000000",
    "expireDate_MMyyyy": "062016",
    "cardHolderName": "JOHN SMITH",
    "ccv": "123"
  }
}

Response Data

This section provides a high level overview of the important, non obvious elements of the response data. The response object is a json simplified version of the OTA ReadRS data. If you are familiar with OTA, this response data will be familiar.

  • airReservation : All the booking data is in the airReservation object.
    • bookingReferenceID
      This is the unique booking reference string (5 character alpha numeric string). This reference should be displayed to the user as they will need to use it later when retrieving a booking.

    • originDestinationOptions
      This object contains details of each flight segment. The following is an example of a flight segment object:

      
      {
            "stopOvers": [],
              "directFlight": true,
              "flights": [
                {
                  "flightNumber": "1137",
                  "departureAirport": {
                    "code": "PEN",
                    "name": "Penang Intl",
                    "city": "Penang",
                    "country": "Malaysia",
                    "lat": 5.297139,
                    "lng": 100.276864,
                    "terminal": null,
                    "gate": null,
                    "timezone": "Asia/Kuala_Lumpur"
                  },
                  "arrivalAirport": {
                    "code": "KUL",
                    "name": "Kuala Lumpur Intl",
                    "city": "Kuala Lumpur",
                    "country": "Malaysia",
                    "lat": 2.745578,
                    "lng": 101.709917,
                    "terminal": null,
                    "gate": null,
                    "timezone": "Asia/Kuala_Lumpur"
                  },
                  "marketingAirline": null,
                  "operatingAirline": "MH",
                  "equipment": "",
                  "flightRPH": 2,
                  "comments": [],
                  "depScheduled": "2013-06-27T07:00:00.000+08:00",
                  "arrScheduled": "2013-06-27T08:05:00.000+08:00",
                  "depEstimated": null,
                  "depActual": null,
                  "arrEstimated": null,
                  "arrActual": null,
                  "stopQuantity": 0,
                  "bookingClassAvails": [
                    {
                      "code": "V",
                      "quantity": 1,
                      "statusCode": "",
                      "rph": -1
                    }
                  ],
                  "resBookDesigCode": "V",
                  "minutesToScheduledFlightDeparture": 1823
                }
              ]
            },
                    
    • passengers
      This is an array of passenger objects. The data in this object is self-explanatory (name, email, phone, etc.). One element worth mentioning is the travelerRefNumber. This is a unique index for the passenger in question. This value is used in other elements of the airReservation, for example the SSRs or ticketing data, to identify which passenger a SSR refers to. The first passenger has index of 1 (not 0).

    • ticketing
      This object contains the ticketing information for the passengers. The fields in this object are:

      • ticketType - generally eTicket
      • travelerRefNumber - a space delimited string specifying the passengers to whom this ticketing data refers to.
      • ticketTimeLimit - For ‘book and hold’ this is the time when the booking will automatically be deleted if the booking is not paid for by the customer. For ‘book and ticket’, this will be null.
      • ticketingStatus -is either 2 (booking held) or 3 (ticketed)
    • remarks
      This is an array of text remarks made by the booking engine or travel agent when creating the booking. These are generally free text remarks designed to be interpreted by a human, not a computer.

    • SSRs
      A SSR is a Special Service Request. The array of SSRs hold information about frequent flyer cards, eTicket numbers, Infant status, special meals or wheelchair requests.

    • OSIs
      OSI is Other Service Request. This will contain information such as Infant status.