Trip API Concepts

Trips play a crucial role on our platform and the Trip APIs are frequently upgraded with new features. Therefore, it’s important to have the latest information about the request and response schema before starting to work with the Trip APIs.

This page will provide a more contextual understanding of selected Trip APIs and their fields, parameters, and functionalities.

Get trip details

To learn more about the response fields present in this API, see Get trip details.

Notes:
This page will only describe the most important fields in the API response. For example, details such as tripId are essential at every stage of the booking process. However, fields such as startDate, considered to be self explanatory, are not covered.
For a short description of every field in this API, view the Get trip details page.

basicTripInfo

Contains all the basic information related to a trip. The following are some of the nested fields present within the basicTripInfo object:

API Fields	Context
`tripId`	Contains the unique trip ID generated by Spotnana. Each booking made on Spotnana must either be associated with an existing `tripId` or have new `tripId` created for it.
`tripName`	A user-friendly trip name provided at the time of booking.

pnrs

An array object that contains the list of all PNR IDs created by Spotnana for the trip and the respective PNR data is stored in the data field. A trip can contain multiple PNR IDs and the booking data associated with each of them.

Note: The pnrs field in Get trip details API will contain all the PNRs and their relevant data. You can also access each individual PNR data using the Get PNR API.

The following are some of the data stored for a PNR. These fields can be found within pnrs > data:

API Fields	Context
`version`	Indicates the specific version of the PNR. The numerical value of the version will be incremented by 1 each time a PNR is updated.
`createdVia`	Specifies the mode of booking. This field can contain the following values: `OBT:` Indicates if the PNR was created via the Spotnana Online Booking Tool (OBT). `OFFLINE`: Indicates if the PNR was created offline by the travel agents on the supplier side. `SHELL`: Indicates if the PNR was created directly on a Global Distribution System (GDS). `PASSIVE`: Indicates if the PNR was created using the passive segment on a GDS. `API`: Indicates if the PNR was created using the Create PNR API.
`initialVersionCreatedVia`	Specifies the mode by which the initial PNR was created. For example, a travel agent could create a PNR on the airline website and then update the corresponding data in the Spotnana PNR. This would be stored as `initialVersionCreatedVia: OFFLINE` and `createdVia: OBT`.
`sourceInfo`	Contains information regarding the source of the booking. You can access the `sourcePnrId` of the booking within this field.
`pnrTravelers`	An array used to contain information about all the travelers associated with the `pnrId`. This field can contain traveler-related information such as user ID, personal information, persona, applicable loyalties, and business information about the traveler.
`invoiceDelayedBooking`	Indicates if the booking has been made using the delayed invoice feature.
`costOfGoodsSold`	The total cost of goods sold charged by the supplier for the inventory booked.
`costToCustomer`	Total cost to customer charged by the Travel Management Company (TMC). This field will only contain information if the TMC charges an additional service fee for the booking. If the TMC doesn’t charge any service fee, the `costToCustomer` field will be empty.
`airPnr`	If the PNR is for an air booking, the `airPnr` object will hold all its relevant information.
`totalFare`	The total fare of a PNR. The `totalFare` > `currencyCode` indicates the currency in which the supplier has charged for your booking. If you’ve paid for the booking in a different currency, then the `convertedAmount` and `convertedCurrency` will reflect the converted amount and the currency code in which you’ve paid.
`serviceFees`	The service fee charged for the PNR. The service fee can also be included as part of the delayed invoice which can be identified by `serviceFees` > `status`.
`paymentInfo`	Detailed information about the list of all payment methods used for the booking and the fare breakdown for each payment method. This field also contains the refund fare breakdown for each form of payments used.
`bookingHistory`	Holds the list of updates made to a booking. The `bookingHistory` > `bookingInfo` > `status` field contains the type of change made to the booking (e.g., booked, exchanged, updated, or canceled). The `bookingHistory` > `bookerInfo` > `role` field indicates if the booking/update is made by the traveler, agent, travel manager, or others. If the booker role is not specified the `role` field will contain `UNKNOWN_ROLE`.

pendingShellPnrs

A list of Shell PNRs created for the trip. Once the bookingStatus of a Shell PNR is CONFIRMED_STATUS, the Shell PNR data is moved into pnrs > data.

pendingManualFormPnrs

A list of Manual Form PNRs created for the trip. Once the bookingStatus of a Manual Form PNR is CONFIRMED_STATUS, the data is moved into the pnrs > data.

simplePnrs

A list of Simple PNRs created for the trip and the data for them that we received from the supplier.

Get trip summaries

Use the following 3 endpoints to obtain the list of trip summaries:

API Name	Endpoint	Description
List trip summaries for a company	`/v3/trips/companies/{companyId}/list`	Retrieves the list of trips associated with a `companyId`.
List trip summaries for a user	`/v3/trips/users/{userId}/list`	Retrieves the list of trips associated with a `userId`.
List trip summaries for travelers managed by an arranger	`/v3/trips/arrangers/{arrangerId}/list`	Retrieves the list of trips for all travelers managed by a specific arranger. The request must contain the `arrangerId` (i.e., the `userId` of the arranger). This endpoint can be used for travel arrangers whose role types are `COMPANY_TRAVEL_ARRANGER` and `TRAVEL_ARRANGER`.

Some additional features offered by these endpoints are:

Pagination: A maximum of 100 trip summaries can be returned in a single API call. In the request, specify the starting index of the list in the paginationRequestParams > offset field. The maximum number of trip summaries to be returned can be specified in the paginationRequestParams > limit field (supports values from 1 to 100).

For example, if you have 200 trip summaries to be returned and you wish to paginate the response and display 100 trip summaries per page. To achieve this, you'll make 2 consecutive API calls. In the first API call the offset: 0 and limit: 100 will return the first 100 trip summaries. In the second API call the offset: 100 and limit: 100 will return the next list of 100 trip summaries.
Filters: You can filter the list of trips in the response using the tripFilters field in the request. Choose the filter type from the tripFilters > filterType field. You can filter the response by userId, tripId, companyId, policy status, trip type (e.g., UPCOMING), travel type (e.g., air, hotel, etc.), policy status (i.e., OUT_OF_POLICY or IN_POLICY), and trip dates (i.e., trip start, end, created, and updated dates).
Sorting: The sortOptions field in the request can be used to sort the list of trip summaries in the response. Currently, the endpoint supports sorting by the trip START_DATE and END_DATE. You can also sort through the dates in an ascending or descending order.

Note: The includePnrSummaries field in the request can be used to retrieve the PNR summaries associated with the list of trips displayed. However, as a best practice, we recommend to keep includePnrSummaries as false to reduce the API processing time. Instead, you can use the Get trip details or the Get PNR APIs to view the complete PNR information associated with a specific trip.