# Trip API concepts

[Trips](/spotnana/basic_trip_concepts#what-is-a-trip) play a crucial role on our platform and
the [Trip APIs](/openapi/tripapi#tag/Trips) 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](/openapi/tripapi#operation/getTripDetailsV3).

> **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](/openapi/tripapi#operation/getTripDetailsV3) 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](/openapi/tripapi#operation/getTripDetailsV3) API will contain all the PNRs
and their relevant data.
You can also access each individual PNR data using the [Get PNR](/openapi/tripapi#operation/getPnrV3) 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](/openapi/tripapi#operation/createPnrV3) 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](/spotnana/basic_payment_concepts#delayed-invoice) feature. |
| `costOfGoodsSold` | The total [cost of goods sold](/spotnana/basic_payment_concepts#cost-of-goods-sold-cogs) charged by the supplier for the inventory booked. |
| `costToCustomer` | Total [cost to customer](/spotnana/basic_payment_concepts#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](/spotnana/basic_payment_concepts#total-fare-of-a-pnr) 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](/spotnana/basic_payment_concepts#service-fee) charged for the PNR. The service fee can also be included as part of the [delayed invoice](/spotnana/basic_payment_concepts#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](/spotnana/basic_payment_concepts#form-of-payment-fop) 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](/spotnana/basic_trip_concepts#shell-pnr) 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](/spotnana/basic_trip_concepts#manual-form-pnr) 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](/spotnana/basic_trip_concepts#simple-pnr) 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](/openapi/tripapi#operation/getcompanytripsummarieslist) | `/v3/trips/companies/{companyId}/list` | Retrieves the list of trips associated with a `companyId`. |
| [List trip summaries for a user](/openapi/tripapi#operation/getusertripsummarieslist) | `/v3/trips/users/{userId}/list` | Retrieves the list of trips associated with a `userId`. |
| [List trip summaries for travelers managed by an arranger](/openapi/tripapi#operation/getarrangermanagedtripsummarieslist) | `/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: 

1. **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.
2. **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).
3. **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](/openapi/tripapi#operation/getTripDetailsV3) or the [Get PNR](/openapi/tripapi#operation/getPnrV3) APIs to view the complete PNR information associated with a specific trip.