Simple Booking Workflow
Simple booking flow allows you to create bookings for our TUI-internal flights and charters. Selling internal flights will give you immediate feedback on the sell status (different to the advanced workflow, where you need to check for a sell-status).
Please, notice that a postman collection with an example for the endpoints is available and linked at the end of this document.
Flow Chart
Steps in Detail
CreateToken
Is used to request New Skies Session Token. You need to provide your New Skies credentials here.
curl --location 'https://playground.api.tui/flight/newskies/rest/api/auth/v1/token/user' \
--header 'Content-Type: application/json' \
--header 'x-apikey: {YourApiKey}' \
--data '{
"credentials": {
"username": "{UserName}",
"password": "{Password}",
"domain": "EXT"
}
}'Availability
Is used to retrieve flight availability for a market. There are several availability request options available. This example shows the simple/lowfare request
curl --location 'https://playground.api.tui/flight/newskies/rest/api/nsk/v4/availability/search/simple' \
--header 'Authorization: Bearer {TokenReceivedDuringCreateTokenRequest}' \
--header 'x-apikey: {YourApiKey}' \
--header 'Content-Type: application/json' \
--data '{
"origin": "DUS",
"destination": "PMI",
"searchDestinationMacs": true,
"searchOriginMacs": true,
"beginDate": "2024-10-21",
"passengers": {
"types": [
{
"type": "ADT",
"count": 2
}
],
"residentCountry": "DE"
},
"taxesAndFees": 2,
"lowFarePrice": 0,
"ssrCollectionsMode": 0,
"numberOfFaresPerJourney": 0,
"returnEmptyResults": true
}'From the response, extract the JourneyKey and FareAvailabilityKey of the flight you like to sell.
{
"data": {
"results": [
{
"trips": [
{
"multipleOriginStations": false,
"multipleDestinationStations": false,
"date": "2024-10-21T00:00:00",
"journeysAvailableByMarket": {
"DUS|PMI": [
{
"flightType": 1,
"stops": 0,
"designator": {
"destination": "PMI",
"origin": "DUS",
"arrival": "2024-10-21T08:15:00",
"departure": "2024-10-21T05:50:00"
},
"journeyKey": "WDN_MjMxMn4gfn5EVVN_MTAvMjEvMjAyNCAwNTo1MH5QTUl_MTAvMjEvMjAyNCAwODoxNX5_",
"segments": [
{
"isChangeOfGauge": false,
"isBlocked": false,
"isHosted": true,
"designator": {
"destination": "PMI",
"origin": "DUS",
"arrival": "2024-10-21T08:15:00",
"departure": "2024-10-21T05:50:00"
},
"isSeatmapViewable": true,
"segmentKey": "WDN_MjMxMn4gfn5EVVN_MTAvMjEvMjAyNCAwNTo1MH5QTUl_MTAvMjEvMjAyNCAwODoxNX5_",
"identifier": {
"identifier": "2312",
"carrierCode": "X3",
"opSuffix": null
},
"cabinOfService": null,
"externalIdentifier": null,
"international": true,
"segmentType": 0,
"legs": [
{
"legKey": "NjM4NjUwODY2MDAwMDAwMDAwIVgzITIzMTIhICFEVVMhUE1JITIxNjU0OTg2",
"operationsInfo": null,
"designator": {
"destination": "PMI",
"origin": "DUS",
"arrival": "2024-10-21T08:15:00",
"departure": "2024-10-21T05:50:00"
},
"legInfo": {
"departureTimeUtc": "2024-10-21T03:50:00Z",
"arrivalTimeUtc": "2024-10-21T06:15:00Z",
"adjustedCapacity": 189,
"arrivalTerminal": null,
"arrivalTimeVariant": 120,
"backMoveDays": 0,
"capacity": 189,
"changeOfDirection": false,
"codeShareIndicator": 0,
"departureTerminal": null,
"departureTimeVariant": 120,
"equipmentType": "73H",
"equipmentTypeSuffix": "L",
"eTicket": true,
"irop": false,
"lid": 189,
"marketingCode": "DX373HL",
"marketingOverride": false,
"operatedByText": null,
"operatingCarrier": null,
"operatingFlightNumber": null,
"operatingOpSuffix": null,
"outMoveDays": 0,
"arrivalTime": "2024-10-21T08:15:00",
"departureTime": "2024-10-21T05:50:00",
"prbcCode": "73HH",
"scheduleServiceType": "J",
"sold": 84,
"status": 0,
"subjectToGovtApproval": false
},
"nests": [],
"ssrs": [],
"seatmapReference": "WDMhMjMxMiEgITYzODY1MDg2NjAwMDAwMDAwMCFEVVMhUE1J",
"flightReference": "20241021 X32312 DUSPMI"
}
]
}
],
"fares": [
{
"fareAvailabilityKey": "MH5Zfn5YM35ORUdPQUlEfjEwMDB_fjB_MX5_WCEw",
"details": [
{
"availableCount": 105,
"status": 1,
"reference": "MH5Zfn5YM35ORUdPQUlEfjEwMDB_fjB_MX5_WA--",
"serviceBundleSetCode": null,
"bundleReferences": null,
"ssrReferences": null
}
],
"isSumOfSector": false
}
],
"notForGeneralUser": false
},
{
"flightType": 1,
"stops": 0,
"designator": {
"destination": "PMI",
"origin": "DUS",
"arrival": "2024-10-21T16:55:00",
"departure": "2024-10-21T14:30:00"
},
"journeyKey": "WDN_MjMyMn4gfn5EVVN_MTAvMjEvMjAyNCAxNDozMH5QTUl_MTAvMjEvMjAyNCAxNjo1NX5_",
"segments": [
{
"isChangeOfGauge": false,
"isBlocked": false,
"isHosted": true,
"designator": {
"destination": "PMI",
"origin": "DUS",
"arrival": "2024-10-21T16:55:00",
"departure": "2024-10-21T14:30:00"
},
"isSeatmapViewable": true,
"segmentKey": "WDN_MjMyMn4gfn5EVVN_MTAvMjEvMjAyNCAxNDozMH5QTUl_MTAvMjEvMjAyNCAxNjo1NX5_",
"identifier": {
"identifier": "2322",
"carrierCode": "X3",
"opSuffix": null
},
"cabinOfService": null,
"externalIdentifier": null,
"international": true,
"segmentType": 0,
"legs": [
{
"legKey": "NjM4NjUxMTc4MDAwMDAwMDAwIVgzITIzMjIhICFEVVMhUE1JITIxNjU0OTkw",
"operationsInfo": null,
"designator": {
"destination": "PMI",
"origin": "DUS",
"arrival": "2024-10-21T16:55:00",
"departure": "2024-10-21T14:30:00"
},
"legInfo": {
"departureTimeUtc": "2024-10-21T12:30:00Z",
"arrivalTimeUtc": "2024-10-21T14:55:00Z",
"adjustedCapacity": 189,
"arrivalTerminal": null,
"arrivalTimeVariant": 120,
"backMoveDays": 0,
"capacity": 186,
"changeOfDirection": false,
"codeShareIndicator": 0,
"departureTerminal": null,
"departureTimeVariant": 120,
"equipmentType": "73H",
"equipmentTypeSuffix": "A",
"eTicket": true,
"irop": false,
"lid": 186,
"marketingCode": "DX373H3",
"marketingOverride": false,
"operatedByText": null,
"operatingCarrier": null,
"operatingFlightNumber": null,
"operatingOpSuffix": null,
"outMoveDays": 0,
"arrivalTime": "2024-10-21T16:55:00",
"departureTime": "2024-10-21T14:30:00",
"prbcCode": "73HH",
"scheduleServiceType": "J",
"sold": 21,
"status": 0,
"subjectToGovtApproval": false
},
"nests": [],
"ssrs": [],
"seatmapReference": "WDMhMjMyMiEgITYzODY1MTE3ODAwMDAwMDAwMCFEVVMhUE1J",
"flightReference": "20241021 X32322 DUSPMI"
}
]
}
],
"fares": [
{
"fareAvailabilityKey": "MH5Zfn5YM35ORUdPQUlEfjEwMDB_fjB_MX5_WCEw",
"details": [
{
"availableCount": 165,
"status": 1,
"reference": "MH5Zfn5YM35ORUdPQUlEfjEwMDB_fjB_MX5_WA--",
"serviceBundleSetCode": null,
"bundleReferences": null,
"ssrReferences": null
}
],
"isSumOfSector": false
}
],
"notForGeneralUser": false
}
]
}
}
]
}
],
"faresAvailable": {
"MH5Zfn5YM35ORUdPQUlEfjEwMDB_fjB_MX5_WCEw": {
"totals": {
"fareTotal": 44.00,
"revenueTotal": 0.0,
"publishedTotal": 0.0,
"loyaltyTotal": 0.0,
"discountedTotal": 0.0
},
"isSumOfSector": false,
"fareAvailabilityKey": "MH5Zfn5YM35ORUdPQUlEfjEwMDB_fjB_MX5_WCEw",
"fares": [
{
"isGoverning": true,
"fareBasisCode": "NEGOAID",
"classOfService": "Y",
"classType": null,
"fareApplicationType": 0,
"fareStatus": 0,
"productClass": "PF",
"ruleNumber": "1000",
"ruleTariff": null,
"passengerFares": [
{
"fareDiscountCode": null,
"passengerDiscountCode": null,
"passengerType": "ADT",
"fareAmount": 22.00,
"revenueFare": 0.0,
"publishedFare": 0.0,
"loyaltyPoints": 0.0,
"discountedFare": 0.0,
"serviceCharges": [
{
"amount": 0.0,
"code": null,
"detail": null,
"type": 0,
"collectType": 0,
"currencyCode": "EUR",
"foreignCurrencyCode": "EUR",
"foreignAmount": 0.0,
"ticketCode": null
},
{
"amount": 22.00,
"code": null,
"detail": "TaxFeeSum",
"type": 5,
"collectType": 0,
"currencyCode": "EUR",
"foreignCurrencyCode": "EUR",
"foreignAmount": 22.00,
"ticketCode": null
}
],
"multiplier": 2
}
],
"travelClassCode": null,
"isAllotmentMarketFare": false,
"reference": "MH5Zfn5YM35ORUdPQUlEfjEwMDB_fjB_MX5_WA--"
}
]
}
},
"currencyCode": "EUR",
"includeTaxesAndFees": true,
"bundleOffers": null
}
}Sell
To sell a flight (this will create a session-state and put the selected flight onto session), use the JourneyKey and FareAvailabilityKey to perform the sell. Further more you can provide passenger-details, like name, title, dob, etc. here. If that is not feasible due to your workflow, this can also be done afterwards like described on UpdatePassenger
curl --location 'https://playground.api.tui/flight/newskies/rest/api/nsk/v4/trip' \
--header 'Authorization: Bearer {TokenReceivedDuringCreateTokenRequest}' \
--header 'x-apikey: {YourApiKey}' \
--header 'Content-Type: application/json' \
--data '{
"journeys": {
"keys": [
{
"journeyKey": "WDN_MjMxMn4gfn5EVVN_MTAvMjEvMjAyNCAwNTo1MH5QTUl_MTAvMjEvMjAyNCAwODoxNX5_",
"fareAvailabilityKey": "MH5Zfn5YM35ORUdPQUlEfjEwMDB_fjB_MX5_WCEw"
}
]
},
"passengers": [
{
"passenger": {
"name": {
"first": "Karl",
"last": "Sample",
"title": "MR"
},
"info": {
"residentCountry": "DE",
"gender": "Male",
"dateOfBirth": "1990-12-24"
},
"passengerTypeCode": "ADT"
}
},
{
"passenger": {
"name": {
"first": "Sabine",
"last": "Sample",
"title": "MRS"
},
"info": {
"residentCountry": "DE",
"gender": "Female",
"dateOfBirth": "1990-12-06"
},
"passengerTypeCode": "ADT"
}
}
],
"residentCountry": "DE",
"currencyCode": "EUR",
"loyalty": "MonetaryOnly"
}'UpdatePassenger
UpdatePassenger can be used to update passenger information after the sell was already performed.
curl --location --request PUT 'https://playground.api.tui/flight/newskies/rest/api/nsk/v3/booking/passengers/MCFBRFQ-' \
--header 'Authorization: Bearer {TokenReceivedDuringCreateTokenRequest}' \
--header 'x-apikey: {YourApiKey}' \
--header 'Content-Type: application/json' \
--data '{
"name": {
"first": "FirstName1",
"last": "LastName1",
"title": "MR"
},
"info": {
"nationality": "DE",
"residentCountry": "DE",
"gender": "Male",
"dateOfBirth": "1992-01-01"
}
}'AddContact
At least one contact is necessary in a booking, having contactTypeCode = P (primary) This contact needs all necessary contact details of your agency / department as well as a valid email-address.
curl --location 'https://playground.api.tui/flight/newskies/rest/api/nsk/v1/booking/contacts' \
--header 'Authorization: Bearer {TokenReceivedDuringCreateTokenRequest}' \
--header 'x-apikey: {YourApiKey}' \
--header 'Content-Type: application/json' \
--data-raw '{
"contactTypeCode": "P",
"phoneNumbers": [
{
"type": "Other",
"number": "999999999"
}
],
"cultureCode": "de-DE",
"address": {
"lineOne": "123 Fake Street",
"countryCode": "DE",
"provinceState": "BW",
"city": "Faketown",
"postalCode": "12345"
},
"emailAddress": "test@tui.com",
"distributionOption": "None",
"notificationPreference": "None",
"name": {
"first": "FirstName",
"last": "LastName",
"title": "MR"
}
}'SSR Availability
If you want to sell additional ssrs, ssr-availability request will give you a list of available ssrs for your booking in state.
curl --location 'https://playground.api.tui/flight/newskies/rest/api/nsk/v2/booking/ssrs/availability' \
--header 'Authorization: Bearer {TokenReceivedDuringCreateTokenRequest}' \
--header 'x-apikey: {YourApiKey}' \
--header 'Content-Type: application/json' \
--data '{
"trips": [
{
"destination": "PMI",
"origin": "DUS",
"departureDate": "2024-10-21T05:50:00",
"identifier": {
"identifier": "2312",
"carrierCode": "X3",
"opSuffix": ""
}
}
],
"passengerKeys": [
"MCFBRFQ-",
"MSFBRFQ-"
],
"currencyCode": "EUR",
"feePricingMode": 0,
"ssrAvailabilityMode": 0
}'From the Availability Response, store the ssrKey for the specific passenger. Please note, that each passenger gets its own unique ssrkey.
AddSsr
To sell an ssr, use the ssrKeys you received on the availability request
curl --location 'https://playground.api.tui/flight/newskies/rest/api/nsk/v3/booking/ssrs' \
--header 'Authorization: Bearer {TokenReceivedDuringCreateTokenRequest}' \
--header 'x-apikey: {YourApiKey}' \
--header 'Content-Type: application/json' \
--data '{
"keys": [
{
"ssrKey": "MSFNQ0ZCUkZRLSFaWkZMISFQTUkhWDMhNjM4NjUwNjU2MDAwMDAwMDAwIURVUyEyMzEyISA-",
"count": 1,
"note": "TestSell"
},
{
"ssrKey": "MSFNU0ZCUkZRLSFaWkZMISFQTUkhWDMhNjM4NjUwNjU2MDAwMDAwMDAwIURVUyEyMzEyISA-",
"count": 1,
"note": "TestSell2"
}
],
"forceWaveOnSell": true,
"currencyCode": "EUR",
"feePricingMode": 0
}'GetSeatAvailability
If you wish to assign seats directly for your passengers, check the GetSeatAvailability for unassigned seats.
curl --location 'https://playground.api.tui/flight/newskies/rest/api/nsk/v3/booking/seatmaps/journey/WDN_MjMxMn4gfn5EVVN_MTAvMjEvMjAyNCAwNTo1MH5QTUl_MTAvMjEvMjAyNCAwODoxNX5_' \
--header 'Authorization: Bearer {TokenReceivedDuringCreateTokenRequest}' \
--header 'x-apikey: {YourApiKey}'AssignSeats
To assign seats to a passenger, you need the PassengerKey, UnitKey and JourneyKey values.
curl --location 'https://playground.api.tui/flight/newskies/rest/api/nsk/v2/booking/passengers/MCFBRFQ-/seats/WDMhMjMxMiEgITYzODY1MDg2NjAwMDAwMDAwMCFEVVMhUE1JITNGIVk-' \
--header 'Authorization: Bearer {TokenReceivedDuringCreateTokenRequest}' \
--header 'x-apikey: {YourApiKey}' \
--header 'Content-Type: application/json' \
--data '{
"journeyKey": "WDN_MjMxMn4gfn5EVVN_MTAvMjEvMjAyNCAwNTo1MH5QTUl_MTAvMjEvMjAyNCAwODoxNX5_",
"waiveFee": false,
"inventoryControl": "Session",
"ignoreSeatSsrs": false,
"seatAssignmentMode": "AutoDetermine"
}'GetCurrentBooking
Now it's time to see how our booking looks like. To review the booking in state, use
curl --location 'https://playground.api.tui/flight/newskies/rest/api/nsk/v1/booking' \
--header 'Authorization: Bearer {TokenReceivedDuringCreateTokenRequest}' \
--header 'x-apikey: {YourApiKey}' \
--data ''The response will give you details about what you have booked so far, passenger and journey details as well as payment information as for example the current balance due.
AddPayment
To complete a booking, a valid payment is mandatory. The NewSkies system offers different payment options like SD-Payment, CreditCard, AgencyPayments and many more. Which payment you should use depends on your contract details and agreement with your TUI Agency Management. The given example shows payment via creditcard.
curl --location 'https://playground.api.tui/flight/newskies/rest/booking/payments' \
--header 'Authorization: Bearer {TokenReceivedDuringCreateTokenRequest}' \
--header 'x-apikey: {YourApiKey}' \
--header 'Content-Type: application/json' \
--data '{
"paymentMethodCode": "VI",
"amount": {{balanceDue}},
"paymentFields": {
"ACCTNO": "4444333322221111",
"EXPDAT": "10/8/2099",
"AMT": {{balanceDue}},
"CC::VerificationCode": "111",
"CC::AccountHolderName": "Bob Smith"
},
"currencyCode": "EUR",
"installments": 1
}'Depending on the response status code your booking is now either complete or has a failed payment. Both cases require further steps.
In case you receive a success status code, continue with the Commit Request, otherwise you need to clear your booking by using the Reset Request.
The above example shows VISA Payment. You can find examples of other payment types here.
Commit
In case your booking creation and add payment has been successful, you may now confirm your booking by a commit request.
curl --location 'https://playground.api.tui/flight/newskies/rest/api/nsk/v3/booking' \
--header 'Authorization: Bearer {TokenReceivedDuringCreateTokenRequest}' \
--header 'x-apikey: {YourApiKey}' \
--header 'Content-Type: application/json' \
--data '{}'As this commit just gives you a success status code (in best case) but no further details, repeat the Get Current Booking Request which will give you the booking details, now including a RecordLocator.
Reset
In case an error happened during the booking creation or when adding the payments, the session state can be cleared by calling the reset operation.
This cleans all the state data and discards all non-committed changes.
curl --location --request DELETE 'https://playground.api.tui/flight/newskies/rest/api/nsk/v3/booking' \
--header 'Authorization: Bearer {TokenReceivedDuringCreateTokenRequest}' \
--header 'x-apikey: {YourApiKey}' \Further reading
Ensure to check the endpoint documentation on TUI-portal for additional requests or if you want to read more about optional parameters you might want to use.
Postman
Download our postman collection containing the simple workflow.
