Itinerary - GET Itinerary & Trip Details

API Recipes: API Tasks

This series of API Recipes describes API tasks associated with developing apps, apps for Travel Management Companies, (TMC), Travel Suppliers and businesses who need to get data about their employees’ travel related booking. This recipe assumes you are a current customer or platform partner.

Before You Begin

Review the following checklist to ensure you are able to perform the task in this recipe. To see reference information, click the link in the bullet point

• Understand the authentication process
• Be able to access the Get Trips API
• Be able to access the Itinerary Web Service (TMC & Third Party)
• Ensure you have a definition XSD, usable for architecting your solution

Get Itinerary and Trip Details: Pulling Itinerary Trip Data

Developers, travel suppliers and travel management companies will want to use the processes described in this recipe.

• With an authorized Oauth token, Developers can retrieve detailed itineraries for users or user groups. Using this data allows developers to create applications that match opportunities for users in a given locale, region or country specific to user interests. For example, TV Food Maps matches destinations on a user’s itinerary to notify them of a featured restaurant from a TV show like Diners, DriveIns and Dives near the location of their itinerary
• Travel Suppliers can use the processes to analyze itineraries/trips for gaps in such services as car rental and hotel accommodations, and use the information to offer these services. This is particularly useful if you want to provide an enhanced travel experience for your users
• Travel Management Companies can use these processes to analyze individual or company travel data, offer traveler support services, Triplink support or business intelligence and analytics

The order in which most partners obtain travel data is:

1. Manually add a new itinerary. This creates a sample trip that allows the developer to retrieve their first itinerary via the API and with the response and the XSD, build a schema or data structure.
2. Populate internal systems by building a scheduled process to poll for itineraries based on specific function parameters.
3. Use the list of itineraries to obtain greater trip details. Most travel suppliers and TMC’s will retrieve trip details based on day, time period or users.

Each of these processes can be used by itself. For example if a travel supplier only wanted to obtain itinerary details, they can follow the Get Itinerary Details process described below.

Get List of Itineraries:

The GET List of Itineraries required for the Get Itinerary endpoint is located in the official SAP Concur developer page here.

If you are a developer and only want to get the GET Itinerary API use the process which follows:

If you have not configured your sandbox to obtain access, you can make that request from the Support Page here. Remember to include the name of the SAP Concur representative you with whom you are working in the form.

If you have configured your sandbox, the GET List of Itineraries required for the Get Itinerary endpoint is located in the official SAP Concur developer page here.

Important

• Use the Itinerary scope. More details here. Use the search term ITINER
• Use either Web flow or Apps Center flow authentication
• Ensure that your dates are recent

This task retrieves trip summaries for the traveler specified in the Oauth token. This endpoint can also be used to get details for trips for a different user, organization or for the entire company. Get List of Itineraries is used most often when a Travel management Company (TMC) needs to retrieve a list of trips on behalf of a user or company.

Examples:

Entire Company (Oauth consumer must have Admin user role)

https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={startdate}&endDate={enddate}&_createdAfterDate={_date}&createdBeforeDate={date}&lastModifiedDate={date}&bookingType={type}&userid_type=login&userid_value=ALL

Individual user (Oauth consumer)

https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={startdate}&endDate={enddate}&_createdAfterDate={_date}&createdBeforeDate={date}&lastModifiedDate={date}&bookingType={type}

Individual user (other than the Oauth consumer)

https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={startdate}&endDate={enddate}&_createdAfterDate={_date}&createdBeforeDate={date}&lastModifiedDate={date}&bookingType={type}&userid_type=login_id&userid_value={loginID}

Additional examples can be viewed here.

Function Parameters

Refer to the sample XML GET Itinerary Details Get request for guidance.

Get Itinerary details

This process allows developers, travel suppliers and travel management companies to obtain details on itineraries for specific trips. By default, the Oauth consumer should be the owner of the trip. The Get Itinerary endpoint can also be used to get details for trips that the Oauth consumer does not own. Travel management companies use this process to get trip details on behalf of a user. This assumes the TMC is registered with SAP Concur and possesses a valid account with one the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

Function Parameters

The request returns an itinerary parent element with a subset of child elements. A partial list appears below. The complete list is located here.

Parent element parameters

Booking Child elements

Get Trip details

Developers should build a scheduled process to poll for itineraries or get trips on demand when a user logs onto their website to make a booking. Using the Oauth token of the user for whom you want details as the authorization, perform this two-step process:

1. GET a list of trips for the user.
2. GET the details of each trip one at a time.

For more information on how to GET a trip list for a user by using their Oauth token, go here.

Example Get List of Trips request:

GET https://{InstanceURL}/api/travel/trip/v1.1 HTTP/1.1
Authorization: OAuth {user's access token}
Accept: application/xml

You can also get the details of each trip by using the TripID. The Get Trip List response includes the unique TripID for each trip.

Example trip details request

GET https://{InstanceURL}/api/travel/trip/v1.1/{TripID} HTTP/1.1
Authorization: OAuth {user's access token}
Accept: application/xml

Refer to the sample Get trip details for a trip ID for guidance.

Important

No itinerary can contain all of the possible elements, because the response will always be a subset of the possible returned values. For full response details, view the Public Itinerary XSD.

Once you have the trip details, look for trips that lack your segment type.

• For example, if you are a TripLink Car Supplier, look for trips that may include a flight but which lack a rental car reservation.

• If you are a TripLink Hotel Supplier, look for trips that may include a flight but which lack a hotel reservation. If you are polling for trips at an interval, you may choose to email a traveler to offer them your service to add to their upcoming trip. For example, if you are a TripLink Hotel partner, you may choose to email the traveler: “If you would like to reserve a hotel for your upcoming trip to Boston on 13 December, we are offering a special rate at our property in city center. Log on here to add a hotel reservation to your trip.”

• If you are checking for upcoming trips when the traveler logs in to your mobile app or website to make a booking, you may choose to present to the traveler a list of their upcoming trips that lack your segment type. For example, if you are a TripLink Car Supplier, you may choose to present a list of upcoming trips that lack a rental car reservation and allow the traveler to easily add a car rental to that trip, prepopulating the pickup and drop-off locations and dates/times using the information from the trip details.

In the case of User Connections customer who has booked a hotel through the SAP Concur platform:

• If your user has downloaded TV Food Maps, they will receive an email as the date of the trip approaches
• The email will indicate which restaurants featured on which TV shows will be near the location at which the employee is staying

Advanced Information

The information in this section is NOT intended for use by User Connections developers.

Itinerary Status and Booking Source

Travel Management Companies will find these two elements in the GET trips response extremely useful when obtaining Trip Details:

• The status of the itinerary: 0- Confirmed; 1- Ticketed by agent; 2- Canceled
• Booking Source (refer to the table below)

Subscribe and Unsubscribe

Note: As part of a security improvement to our authentication infrastructure, the decision has been made to retire notifications for Profile, Form of Payment, and Itinerary for a user or a company because of their handling of OAuth tokens. This functionality has been deprecated as of June 2020.

Concur Travel Suppliers and Travel Management Companies may need to know how to post a company notification subscription for itinerary changes. Use the information which follows to guide you. More information on these topics can be found in the SAP Concur Developer Center in the resource: Subscribe or unsubscribe from notifications.

To subscribe to notifications to be alerted whenever employees who have booked travel through Concur Travel change their travel plans by adding, modifying or canceling an itinerary is referred to as a POST Company Notification Subscription for Itinerary Changes request.

To create this request, use the following example as a template. Notice that the request parameter is Itinerary. The Request XML string also requires an Oath token for an administrative user in the company. The user must have one of the following user roles: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.

XML Example request to subscribe:

POST http://www.concursolutions.com/api/company/v1.0/subscribe?type=itinerary HTTP/1.1
Authorization: OAuth {access token}
...

The notification is sent to the Postback URL that the partner has registered during application review. Partners can only have one postback URL for all notification types. The notification will include the type, oauth_token_key, userid_type, and userid_value query parameters, specifying the updated user as seen in the example:

https://postbackurl.com?type=itinerary&oauth_token_key={oauthtoken}&userid_type=login&userid_value=cm@example.com

While the response body includes a Notification parent element, there are several child elements.

XML Example request to unsubscribe from Itinerary Changes:

https://www.concursolutions.com/api/company/v1.0/unsubscribe?type=itinerary

Refer to the sample Post Company Notification Subscription for Itinerary Changes Response for guidance.