API reference
/
Air
/
Air
/
Validate air itinerary

Air API (v2)

Download OpenAPI description
AirApi.json
AirApi.yaml
Languages
Servers
Staging URL
https://apis.spotnana.com/
Spotnana mock server
https://developer.spotnana.com/_mock/openapi/airapi/

Air

APIs to perform search, checkout and book an air pnr

Operations

Initiate booking

Request

Initiates a new air booking for the trip. The identityDocs field supports the following traveler identity documents: Passport, National ID, Known Traveler Number (KTN), redress number, and immigration documents. The traveler can choose one among the list of identity documents available and provide its information during checkout.

Bodyapplication/jsonrequired
initiateBookingWorkflowIdsobject(InitiateBookingWorkflowIds)

The set of unique response ids associated with initiate booking workflow.

travelersArray of objects(AirBookTravelerInfo)
bookingChargesArray of objects(BookingCharge)
bookingContactobject(BookingContact)

Booking contact for the itinerary. Airlines send all update and change information to booking contact as well.

useExistingBookingboolean

Use existing booking if it exists to initiate

curl -i -X POST \
  https://apis.spotnana.com/v2/air/initiate-booking \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "initiateBookingWorkflowIds": {
      "checkoutResponseId": "string",
      "seatMapResponseId": "string"
    },
    "travelers": [
      {
        "travelerDetails": {
          "travelerId": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          },
          "travelerInfo": {
            "userId": {
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            }
          },
          "travelerType": "ADULT",
          "title": "MR",
          "name": {
            "family1": "Gandas",
            "family2": "FamilyTwo",
            "given": "Vichitr",
            "middle": "Kumar",
            "suffix": "SR",
            "preferred": "Don"
          },
          "gender": "FEMALE",
          "dob": {
            "iso8601": "2017-07-21"
          },
          "phoneNumber": {
            "countryCode": 91,
            "countryCodeSource": "FROM_NUMBER_WITH_PLUS_SIGN",
            "extension": "222",
            "isoCountryCode": "IN",
            "italianLeadingZero": true,
            "nationalNumber": 8150,
            "numberOfLeadingZeros": 1,
            "preferredDomesticCarrierCode": "7",
            "rawInput": "77777",
            "type": "MOBILE"
          },
          "email": "example@email.com",
          "identityDocs": [
            {
              "passport": {
                "docId": "PassportID",
                "expiryDate": {},
                "issueCountry": "IN",
                "issuedDate": {},
                "nationalityCountry": "IN",
                "type": "REGULAR"
              }
            }
          ],
          "address": {
            "addressLines": [
              "Golden Gate Bridge"
            ],
            "administrativeArea": "CA",
            "administrativeAreaName": "California",
            "description": "San Francisco Home",
            "isDefault": true,
            "languageCode": "en",
            "locality": "San Francisco",
            "locationCode": "LAX",
            "organization": "Spotnana",
            "postalCode": "94130",
            "continentCode": "AF",
            "recipients": [
              "string"
            ],
            "regionCode": "US",
            "regionName": "America",
            "revision": 1,
            "sortingCode": "Jamaica",
            "sublocality": "string",
            "timezone": "America/Los_Angeles",
            "coordinates": {
              "latitude": 77.1025,
              "longitude": 28.7041
            }
          },
          "emergencyContactInfo": {
            "address": {
              "addressLines": [
                "Golden Gate Bridge"
              ],
              "administrativeArea": "CA",
              "administrativeAreaName": "California",
              "description": "San Francisco Home",
              "isDefault": true,
              "languageCode": "en",
              "locality": "San Francisco",
              "locationCode": "LAX",
              "organization": "Spotnana",
              "postalCode": "94130",
              "continentCode": "AF",
              "recipients": [
                "string"
              ],
              "regionCode": "US",
              "regionName": "America",
              "revision": 1,
              "sortingCode": "Jamaica",
              "sublocality": "string",
              "timezone": "America/Los_Angeles",
              "coordinates": {
                "latitude": 77.1025,
                "longitude": 28.7041
              }
            },
            "designation": "MANAGER",
            "email": "emergency-contact@email.com",
            "name": {
              "family1": "Gandas",
              "family2": "FamilyTwo",
              "given": "Vichitr",
              "middle": "Kumar",
              "suffix": "SR",
              "preferred": "Don"
            },
            "phoneNumber": {
              "countryCode": 91,
              "countryCodeSource": "FROM_NUMBER_WITH_PLUS_SIGN",
              "extension": "222",
              "isoCountryCode": "IN",
              "italianLeadingZero": true,
              "nationalNumber": 8150,
              "numberOfLeadingZeros": 1,
              "preferredDomesticCarrierCode": "7",
              "rawInput": "77777",
              "type": "MOBILE"
            },
            "userOrgId": {
              "organizationAgencyId": {
                "id": "string"
              },
              "organizationId": {
                "id": "string"
              },
              "userId": {
                "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
              },
              "tmcInfo": {
                "id": {},
                "primaryServiceProviderTmc": {},
                "secondaryServiceProviderTmcs": [
                  null
                ],
                "partnerTmcId": {}
              },
              "tmcBasicInfo": {
                "contractingTmc": {},
                "bookingTmc": {}
              }
            }
          },
          "loyaltyInfos": [
            {
              "appliedTo": [
                "TAJ"
              ],
              "id": "firstId",
              "issuedBy": "firstIssuedBy",
              "type": "AIR"
            }
          ],
          "emergencyContact": {
            "name": "John Smith",
            "email": "emergency-contact@email.com",
            "designation": "MANAGER",
            "relation": "SPOUSE",
            "phoneNumbers": [
              {
                "countryCode": 91,
                "countryCodeSource": "FROM_NUMBER_WITH_PLUS_SIGN",
                "extension": "222",
                "isoCountryCode": "IN",
                "italianLeadingZero": true,
                "nationalNumber": 8150,
                "numberOfLeadingZeros": 1,
                "preferredDomesticCarrierCode": "7",
                "rawInput": "77777",
                "type": "MOBILE"
              }
            ],
            "preferredLanguage": "en-US"
          }
        },
        "seats": [
          {
            "flightId": "string",
            "seatNumbers": [
              "string"
            ]
          }
        ],
        "baggages": [
          {
            "legId": "string",
            "baggageIds": [
              "string"
            ]
          }
        ],
        "ancillaries": [
          {
            "ancillaryId": "ancillary_0"
          }
        ],
        "shareContactInfo": false,
        "specialServiceRequests": [
          {
            "indexes": {
              "legIndex": 1,
              "flightIndex": 2
            },
            "flightIndex": 0,
            "code": "WCHC",
            "info": "Special meal without egg."
          }
        ]
      }
    ],
    "bookingCharges": [
      {
        "amount": {
          "base": {
            "amount": 510,
            "currencyCode": "GBP",
            "convertedAmount": 715.42,
            "convertedCurrency": "USD",
            "otherCoinage": [
              {
                "coinageCode": "BREX_POINTS",
                "amount": 1000,
                "conversionRate": 0.01,
                "preferredCurrencyConversionRate": 0.01
              }
            ]
          },
          "tax": {
            "amount": 510,
            "currencyCode": "GBP",
            "convertedAmount": 715.42,
            "convertedCurrency": "USD",
            "otherCoinage": [
              {
                "coinageCode": "BREX_POINTS",
                "amount": 1000,
                "conversionRate": 0.01,
                "preferredCurrencyConversionRate": 0.01
              }
            ]
          }
        },
        "paymentMethod": {
          "selectedPaymentSource": {
            "paymentSourceId": "f49d00fe-1eda-4304-ba79-a980f565281d",
            "rawPaymentSource": {
              "type": "string",
              "cardDetails": {
                "company": "VISA",
                "token": "4111111111111111",
                "expiry": {}
              }
            },
            "postPaymentRedirectionUrl": "https://mycompany.com/checkout?paymentSourceId=f49d00fe-1eda-4304-ba79-a980f565281d",
            "cvv": "string",
            "amount": {
              "amount": 510,
              "currencyCode": "GBP",
              "convertedAmount": 715.42,
              "convertedCurrency": "USD",
              "otherCoinage": [
                {}
              ]
            }
          }
        }
      }
    ],
    "bookingContact": {
      "emailAddress": "mail@mail.com",
      "phoneNumber": {
        "countryCode": 91,
        "countryCodeSource": "FROM_NUMBER_WITH_PLUS_SIGN",
        "extension": "222",
        "isoCountryCode": "IN",
        "italianLeadingZero": true,
        "nationalNumber": 8150,
        "numberOfLeadingZeros": 1,
        "preferredDomesticCarrierCode": "7",
        "rawInput": "77777",
        "type": "MOBILE"
      }
    },
    "useExistingBooking": true
  }'

Responses

OK

Bodyapplication/json
initiateBookingResponseIdstring

Initiated booking's reference id

Example: "CuwDQ2hCa09HVTJZemsyWVRFNFlUUm"
paymentSourcePrePaymentInformationArray of objects(PaymentSourcePrePaymentInformation)
Response
application/json
{
  "initiateBookingResponseId": "CuwDQ2hCa09HVTJZemsyWVRFNFlUUm",
  "paymentSourcePrePaymentInformation": [
    { … }
  ]
}

Validate air itinerary

Request

Validates the air itinerary for availability and pricing

Bodyapplication/jsonrequired
workflowIdsobject(WorkflowIds)

The set of unique response ids associated with the booking workflow.

tripIdobject(TripId)

The trip ID with which this booking will be associated.

travelersArray of objects(AirBookTravelerInfo)
bookingChargesArray of objects(BookingCharge)
promotionCodeobject(PromotionCode)

Promo code applied to the order (optional)

curl -i -X POST \
  https://apis.spotnana.com/v2/air/revalidate-itinerary \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "workflowIds": {
      "checkoutResponseId": "string",
      "seatMapResponseId": "string",
      "paymentSetupResponseId": "string",
      "initiateBookingId": "string"
    },
    "tripId": {
      "id": "2783425534"
    },
    "travelers": [
      {
        "travelerDetails": {
          "travelerId": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          },
          "travelerInfo": {
            "userId": {
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            }
          },
          "travelerType": "ADULT",
          "title": "MR",
          "name": {
            "family1": "Gandas",
            "family2": "FamilyTwo",
            "given": "Vichitr",
            "middle": "Kumar",
            "suffix": "SR",
            "preferred": "Don"
          },
          "gender": "FEMALE",
          "dob": {
            "iso8601": "2017-07-21"
          },
          "phoneNumber": {
            "countryCode": 91,
            "countryCodeSource": "FROM_NUMBER_WITH_PLUS_SIGN",
            "extension": "222",
            "isoCountryCode": "IN",
            "italianLeadingZero": true,
            "nationalNumber": 8150,
            "numberOfLeadingZeros": 1,
            "preferredDomesticCarrierCode": "7",
            "rawInput": "77777",
            "type": "MOBILE"
          },
          "email": "example@email.com",
          "identityDocs": [
            {
              "passport": {
                "docId": "PassportID",
                "expiryDate": {},
                "issueCountry": "IN",
                "issuedDate": {},
                "nationalityCountry": "IN",
                "type": "REGULAR"
              }
            }
          ],
          "address": {
            "addressLines": [
              "Golden Gate Bridge"
            ],
            "administrativeArea": "CA",
            "administrativeAreaName": "California",
            "description": "San Francisco Home",
            "isDefault": true,
            "languageCode": "en",
            "locality": "San Francisco",
            "locationCode": "LAX",
            "organization": "Spotnana",
            "postalCode": "94130",
            "continentCode": "AF",
            "recipients": [
              "string"
            ],
            "regionCode": "US",
            "regionName": "America",
            "revision": 1,
            "sortingCode": "Jamaica",
            "sublocality": "string",
            "timezone": "America/Los_Angeles",
            "coordinates": {
              "latitude": 77.1025,
              "longitude": 28.7041
            }
          },
          "emergencyContactInfo": {
            "address": {
              "addressLines": [
                "Golden Gate Bridge"
              ],
              "administrativeArea": "CA",
              "administrativeAreaName": "California",
              "description": "San Francisco Home",
              "isDefault": true,
              "languageCode": "en",
              "locality": "San Francisco",
              "locationCode": "LAX",
              "organization": "Spotnana",
              "postalCode": "94130",
              "continentCode": "AF",
              "recipients": [
                "string"
              ],
              "regionCode": "US",
              "regionName": "America",
              "revision": 1,
              "sortingCode": "Jamaica",
              "sublocality": "string",
              "timezone": "America/Los_Angeles",
              "coordinates": {
                "latitude": 77.1025,
                "longitude": 28.7041
              }
            },
            "designation": "MANAGER",
            "email": "emergency-contact@email.com",
            "name": {
              "family1": "Gandas",
              "family2": "FamilyTwo",
              "given": "Vichitr",
              "middle": "Kumar",
              "suffix": "SR",
              "preferred": "Don"
            },
            "phoneNumber": {
              "countryCode": 91,
              "countryCodeSource": "FROM_NUMBER_WITH_PLUS_SIGN",
              "extension": "222",
              "isoCountryCode": "IN",
              "italianLeadingZero": true,
              "nationalNumber": 8150,
              "numberOfLeadingZeros": 1,
              "preferredDomesticCarrierCode": "7",
              "rawInput": "77777",
              "type": "MOBILE"
            },
            "userOrgId": {
              "organizationAgencyId": {
                "id": "string"
              },
              "organizationId": {
                "id": "string"
              },
              "userId": {
                "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
              },
              "tmcInfo": {
                "id": {},
                "primaryServiceProviderTmc": {},
                "secondaryServiceProviderTmcs": [
                  null
                ],
                "partnerTmcId": {}
              },
              "tmcBasicInfo": {
                "contractingTmc": {},
                "bookingTmc": {}
              }
            }
          },
          "loyaltyInfos": [
            {
              "appliedTo": [
                "TAJ"
              ],
              "id": "firstId",
              "issuedBy": "firstIssuedBy",
              "type": "AIR"
            }
          ],
          "emergencyContact": {
            "name": "John Smith",
            "email": "emergency-contact@email.com",
            "designation": "MANAGER",
            "relation": "SPOUSE",
            "phoneNumbers": [
              {
                "countryCode": 91,
                "countryCodeSource": "FROM_NUMBER_WITH_PLUS_SIGN",
                "extension": "222",
                "isoCountryCode": "IN",
                "italianLeadingZero": true,
                "nationalNumber": 8150,
                "numberOfLeadingZeros": 1,
                "preferredDomesticCarrierCode": "7",
                "rawInput": "77777",
                "type": "MOBILE"
              }
            ],
            "preferredLanguage": "en-US"
          }
        },
        "seats": [
          {
            "flightId": "string",
            "seatNumbers": [
              "string"
            ]
          }
        ],
        "baggages": [
          {
            "legId": "string",
            "baggageIds": [
              "string"
            ]
          }
        ],
        "ancillaries": [
          {
            "ancillaryId": "ancillary_0"
          }
        ],
        "shareContactInfo": false,
        "specialServiceRequests": [
          {
            "indexes": {
              "legIndex": 1,
              "flightIndex": 2
            },
            "flightIndex": 0,
            "code": "WCHC",
            "info": "Special meal without egg."
          }
        ]
      }
    ],
    "bookingCharges": [
      {
        "amount": {
          "base": {
            "amount": 510,
            "currencyCode": "GBP",
            "convertedAmount": 715.42,
            "convertedCurrency": "USD",
            "otherCoinage": [
              {
                "coinageCode": "BREX_POINTS",
                "amount": 1000,
                "conversionRate": 0.01,
                "preferredCurrencyConversionRate": 0.01
              }
            ]
          },
          "tax": {
            "amount": 510,
            "currencyCode": "GBP",
            "convertedAmount": 715.42,
            "convertedCurrency": "USD",
            "otherCoinage": [
              {
                "coinageCode": "BREX_POINTS",
                "amount": 1000,
                "conversionRate": 0.01,
                "preferredCurrencyConversionRate": 0.01
              }
            ]
          }
        },
        "paymentMethod": {
          "selectedPaymentSource": {
            "paymentSourceId": "f49d00fe-1eda-4304-ba79-a980f565281d",
            "rawPaymentSource": {
              "type": "string",
              "cardDetails": {
                "company": "VISA",
                "token": "4111111111111111",
                "expiry": {}
              }
            },
            "postPaymentRedirectionUrl": "https://mycompany.com/checkout?paymentSourceId=f49d00fe-1eda-4304-ba79-a980f565281d",
            "cvv": "string",
            "amount": {
              "amount": 510,
              "currencyCode": "GBP",
              "convertedAmount": 715.42,
              "convertedCurrency": "USD",
              "otherCoinage": [
                {}
              ]
            }
          }
        }
      }
    ],
    "promotionCode": {
      "code": "NEWUSER"
    }
  }'

Responses

OK

Bodyapplication/json
bookingIdstring

The booking ID for the booking.

Example: "bookingid"
fareBreakDownobject(BookingFareBreakdown)
legPricesArray of objects(LegPrice)
perTravelerPricesArray of objects(PerTravelerPrice)
policyDetailsobject(PnrPolicyInfo)

Policy Info applicable for the associated itinerary

Response
application/json
{
  "bookingId": "bookingid",
  "fareBreakDown": {
    "totalFare": { … },
    "merchantFee": { … },
    "airlineFee": { … }
  },
  "legPrices": [
    { … }
  ],
  "perTravelerPrices": [
    { … }
  ],
  "policyDetails": {
    "policies": [ … ],
    "ruleResultInfos": [ … ]
  }
}

Validate air itinerary (interim)

Request

Validates an itinerary at any interim stage of air booking workflow and allows you to keep track of fare details before proceeding to checkout. Using this endpoint is optional. It requires a searchId and the itineraryId to obtain the latest fare details of the selected itinerary. The travelerType field in this endpoint response currently only accepts ADULT, CHILD and INFANT.

Bodyapplication/jsonrequired
searchIdstringrequired

The unique searchId corresponding to the selected itinerary.

itineraryIdstringrequired

The selected itineraryId which you would like to validate.

curl -i -X POST \
  https://apis.spotnana.com/v2/air/intermediate-revalidate-itinerary \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "searchId": "string",
    "itineraryId": "string"
  }'

Responses

OK

Bodyapplication/json
bookingIdstring

The booking ID for the booking.

Example: "bookingid"
fareBreakDownobject(BookingFareBreakdown)
legPricesArray of objects(LegPrice)
perTravelerPricesArray of objects(PerTravelerPrice)
policyDetailsobject(PnrPolicyInfo)

Policy Info applicable for the associated itinerary

Response
application/json
{
  "bookingId": "bookingid",
  "fareBreakDown": {
    "totalFare": { … },
    "merchantFee": { … },
    "airlineFee": { … }
  },
  "legPrices": [
    { … }
  ],
  "perTravelerPrices": [
    { … }
  ],
  "policyDetails": {
    "policies": [ … ],
    "ruleResultInfos": [ … ]
  }
}

Loyalty Programs

Operations
Copyright © 2025 Spotnana Technology, Inc.