Travel Profile v2 - Resource

The Travel Profile resource represents a Concur Travel profile that contains travel-related information about a user.

Detailed descriptions of requests and responses are available in the documentation for each HTTP method.

Limitations

Access to this documentation does not provide access to the API. 

Get a Travel Profile

This endpoint provides travel profile information for the specified user. The travel profile includes information such as the user’s identity, contact information, rate preferences and discount codes, preferences by travel type, and custom fields.

URI

https://{InstanceURL}/api/travelprofile/v2.0/profile

Request parameters

All request parameters are optional. To identify a specific user by Login ID or XML Sync ID, you can specify the following request parameters:

Headers

Content-Type header

application/xml

Authorization header

Authorization: OAuth {access_token}

Where access_token is the OAuth 2.0 access token of the user whose travel profile information you want to retrieve.

Create / Update Travel Profile

Creating/Updating a Profile uses the same model as what is retrieved.

Helpful Tips

• Minimum elements required to create a new user include:
  • FirstName
  • LastName
  • TravelConfigID (used to verify agency and Company access to create user)
  • LoginID
  • Password (we will set a random, strong password if not provided)
  • RuleClass (uses default rule class if not provided)
• Omitted elements will be ignored and not updated
• Empty elements of datatype string will be cleared out; nillable elements will be cleared out if set as nil refer to XSD for nillable elements.

Headers

Content-Type header

application/xml

Authorization header

Authorization: OAuth {access_token}

Where access_token is the OAuth 2.0 access token of the user whose travel profile information you want to retrieve or update.

Schema

The complete schema definition is available here: Travel Profile XSD.

SAP Concur reserves the right to change the XSD. Reading/writing strictly to the XSD will result in breakage as new XML elements are added.

The Profile root element contains:

• General
• EmergencyContact
• Telephones
• Addresses
• NationalIDs
• DriversLicenses
• HasNoPassport
• Passports
• Visas
• EmailAddresses
• RatePreferences
• DiscountCodes
• Air
• Rail
• Car
• Hotel
• CustomFields
• Roles
• Sponsors
• TSAInfo
• UnusedTickets
• SouthwestUnusedTickets
• AdvantageMemberships

General

• Some elements require specific scopes be enabled to receive the data, refer to the table below.
• Profile fields, such as cost center and division, must be enabled and populated in the Travel site for data to return.

NOTE: If MiddleName is provided, the NoMiddleName flag in TSAInfo section is set to false.

Canonical List of Preferred Language Values

• “bg”
• “cs”
• “da”
• “de”
• “el”
• “en”
• “es”
• “fi”
• “fr”
• “hr”
• “hu”
• “id”
• “it”
• “ja”
• “ko”
• “nb”
• “nl”
• “nn”
• “no”
• “pl”
• “pt”
• “ro”
• “ru”
• “sk”
• “sv”
• “tr”
• “zh”
• “de-AT”
• “de-CH”
• “de-DE”
• “de-LU”
• “en-AU”
• “en-CA”
• “en-GB”
• “en-IE”
• “en-IN”
• “en-NZ”
• “en-US”
• “en-ZA”
• “es-AR”
• “es-BO”
• “es-CL”
• “es-CO”
• “es-CR”
• “es-DO”
• “es-EC”
• “es-ES”
• “es-GT”
• “es-HN”
• “es-MX”
• “es-NI”
• “es-PA”
• “es-PE”
• “es-PR”
• “es-PY”
• “es-SV”
• “es-UY”
• “es-VE”
• “fr-BE”
• “fr-CA”
• “fr-CH”
• “fr-FR”
• “fr-LU”
• “it-CH”
• “it-IT”
• “ja-JP”
• “nl-BE”
• “nl-NL”
• “no-NO”
• “pt-BR”
• “pt-PT”
• “sv-SE”
• “zh-CN”
• “zh-HK”
• “zh-TW”

EmergencyContact

The emergency contact information provided.

• Emergency Contact Information scope must be enabled to receive the data.

Address

Phone List

Telephones

The Telephones parent element contains a Telephone child element for each included telephone. The Telephone element has the attributes shown in the Response Class section and contains the following child elements:

NOTES

• Telephone Types Other, Pager, Fax, Home, Work, Work2
  • Ignores CountryCode, DeviceName, DeviceType, ContactOptIn, IsPrimaryMobile
  • Only Work (NOT Work2) uses Extension
    • Only a single number can be kept for each of these types. If more than one of each type is provided, W016 warning message is returned.
• Multiple cell phones can be updated, but will sync to the list provided. Cell phones missing from that list that currently associate with the user will be deleted.
• PrimaryMobile:
  • If there is not exactly one (1) PrimaryMobile specified in changing cell phones, then all cell phone changes will be rejected. If only one (1) cell phone is provided, it is marked as primary.

Addresses

The Addresses parent element contains an address child element for each included address. The address element has the attributes shown in the response class section and contains the following child elements:

NOTE: The values returned for the Address child elements are as entered by the user. The fields do not enforce formatting and may have a wide variety of values.

NationalIDs

The NationalIDs parent element contains a NationalID child element for each included National ID. The NationalID element contains the following child elements:

NOTE: Only one National ID can be accepted.

DriversLicenses

The DriversLicenses parent element contains a DriversLicense child element for each included licenses.

• The DriversLicense element contains the following child elements:

NOTE: Only one Drivers License can be accepted.

HasNoPassport

A flag which is set when adding a new passport to a user.

• Passport Visa Information scope must be enabled to receive or update the data.

Passports

A list of passports in the user’s profile:

• Passport Visa Information scope must be enabled to receive the data.

NOTE: there can only be 2 passports associated to a user. If more than two passports are provided, W016 warning message is returned.

Visas

A list of visas in the user’s profile.

• Passport Visa Information scope must be enabled to receive or update the data.

NOTE: Visas will sync with existing visas. Any existing Visas not provided in the list will be deleted.

EmailAddresses

The EmailAddresses parent element contains an EmailAddress child element for each included email address. It contains the following child element:

RatePreferences

The RatePreferences parent element contains the following child element:

DiscountCodes

The DiscountCodes parent element contains a DiscountCode child element for each included discount code.

NOTE: Discount code elements are not available to create or update.

Air

The Air parent element contains the user’s air travel preferences and contains the following child elements:

Air Memberships

Seat

Rail

The Rail parent element contains the user’s rail travel preferences and contains the following child elements:

Rail Membership

Car

The Car parent element contains the user’s car travel preferences. It contains the following child elements:

Car Memberships

Hotel

The Hotel parent element contains the user’s hotel travel preferences. It contains the following child elements:

Hotel Memberships

CustomFields

The CustomFields parent element contains a CustomField child element for each field.

• Company Details scope must be enabled to receive the data.

Roles

A list of users associated to a user:

NOTES:

• FirstName, LastName, and Email cannot be updated.
• Managers and Arrangers must be in the same company of the user to be assigned.
• If the PrimaryIndicatorFlag is sent in as true, the arranger will be marked as primary.
• New arrangers will be marked as travel arrangers only.
• If multiple primary arrangers are provided, W016 warning message is returned.
• If multiple managers are provided, W016 warning message is returned.

Sponsors

A list of sponsors associated to a user:

NOTES:

• The company must allow sponsored users, and the sponsoring user must have the “Sponsor” role to be added to the list of sponsors
• The sponsoring user must be associated with the same company as the sponsored user.
• If the association to the sponsoring user already exists, than the data will be updated
• SponsorshipEndDate must be after SponsorshipStartDate

TSAInfo

The Transportation Security Administration (TSA) details provided.

• TSA information scope must be enabled to receive the data.

NOTE: NoMiddleName: If the profile has a middle name, NoMiddleName overrides to false

UnusedTickets

A list of unused tickets associated to a user

• Unused tickets scope must be enabled to receive the data.

SouthwestUnusedTickets

A list of unused Southwest tickets associated to a user.

• Unused tickets scope must be enabled to receive the data.

AdvantageMemberships

A list of advantage memberships associated to a user:

NOTES:

• For List of available advantage memberships See Reference
• Multiple memberships for the same VendorType, VendorCode, ProgramCode, and CardNumber are identified and a warning is thrown.
• OriginStationCode and DestinationStationCode fields are deprecated and should no longer be used. Use OriginCode and DestinationCode instead.

Possible Warnings and Error Messages

Error in XML Document

This error message occurs, when the XML is not formatted in such a way that it can be read.

<Error>
  <Message>There is an error in XML document (1, 147).</Message>
  <Server-Time>2017-06-22T16:51:37</Server-Time>
  <Id>3BDBC49E-8793-4515-BA0E-F9C71ADA7330</Id>
</Error>

The best way to find the cause of the error is by taking the body of your message and comparing it against the Travel Profile XSD. You can use free online sites to validate such as https://www.freeformatter.com/xml-validator-xsd.html

Standard Error Codes

The codes and types of messages that can be returned on updates and creates:

If incorrect API credentials are provided, the service will return the standard response, e.g. 403 Forbidden. In some cases, the API will return additional information when producing a 400, Bad Request, response. It may contain the following codes in the response’s body:

• EC1 : The user was not found in database.
• EC2: The user is not a company admin, or the company ID does not match the user’s company ID.
• EC3: The user is not an agency admin, the agency company ID is null, or if agency company ID does not match the user’s agency company ID.
• EC4: If the application’s UUID is null, or if the application is configured not to have access to the input travel config.

Examples for Travel Suppliers

Example 1: Get the travel profile for the user associated with the specified OAuth 2.0 access token

Request

GET {InstanceURI}/api/travelprofile/v2.0/profile HTTP/1.1
Authorization: OAuth {access token}

Example 2: Get the travel profile for a user with a specific login ID

Request

GET https://www.concursolutions.com/api/travelprofile/v2.0/profile?userid_type=login&userid_value=cm@example.com HTTP/1.1
Authorization: OAuth {access token}

Examples for TMCs

Example 3: Get the travel profile for the user associated with the specified OAuth 2.0 access token

Request

GET {InstanceURI}/api/travelprofile/v2.0/profile HTTP/1.1
Authorization: OAuth {access token}

Example 4: Get the travel profile for a user with a specific login ID

Request

GET https://www.concursolutions.com/api/travelprofile/v2.0/profile?userid_type=login&userid_value=cm@example.com HTTP/1.1
Authorization: OAuth {access token}

Example 5: Create a new user

Request

POST https://www.concursolutions.com/api/travelprofile/v2.0/profile HTTP/1.1
Authorization: OAuth {access token}

Body

<ProfileResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Action="Create" LoginId="william.never@email.com">
  <General>
    <FirstName>William</FirstName>
    <LastName>Never</LastName>
    <RuleClass>Default Rule Class</RuleClass>
    <TravelConfigID>555</TravelConfigID>
  </General>
  <Password>password123</Password>
</ProfileResponse>

Example 6: Update a user

Request

POST https://www.concursolutions.com/api/travelprofile/v2.0/profile HTTP/1.1
Authorization: OAuth {access token}

Body

<ProfileResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Action="Update" LoginId="william.never@email.com">
  <General>
    <FirstName>Bill</FirstName>
  </General>
</ProfileResponse>

Get a list of travel profile summaries

This endpoint provides a list of travel profile summaries that have been updated since the specified date. The response is separated into pages.

Request

GET {InstanceURI}/api/travelprofile/v2.0/summary?LastModifiedDate=2020-01-01T01:00:00&travelConfigs=100,200,3000&Active=1 HTTP/1.1
Authorization: OAuth {access token}

Request parameters

LastModifiedDate is required. All other request parameters are optional. Available request parameters are as follows:

Headers

Accept header

application/xml

Authorization header

Authorization: OAuth {access_token}

Where access_token is the OAuth 2.0 access token of the user whose travel profile summaries you want to retrieve. If you want to access company-wide travel profile information, the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.

Schema

The data model of the response for the GET operation. The complete schema definition is also available here: Travel Profile Summary V2 XSD

<ConnectResponse>
  <Metadata>
    <Paging>
      <TotalPages />
      <TotalItems />
      <Page />
      <ItemsPerPage />
      <PreviousPageURL />
      <NextPageURL />
    </Paging>
  </Metadata>
  <Data>
    <ProfileSummary>
      <Status />
      <LoginID />
      <XmlProfileSyncID />
      <ProfileLastModifiedUTC />
    </ProfileSummary>
  </Data>
</ConnectResponse>

Response

ConnectResponse root element

The ConnectResponse root element contains the General, Telephones, Addresses, DriversLicenses, EmailAddresses, RatePreferences, DiscountCodes, Air, Car, Hotel, and CustomFields child elements. It has the attributes shown in the response class section.

Metadata element

The Metadata parent element contains the Paging child element.

Paging elements

The Paging parent element contains contains the paging information for the response and it contains the following child elements:

Data element

The Data parent element contains a ProfileSummary child element for each included travel profile.

ProfileSummary

The ProfileSummary element contains the profile information for the response and it contains the following child elements:

Example

This example gets the list of travel profile summaries modified after January 1 2015.

Request

GET {InstanceURI}/api/travelprofile/v2.0/summary?LastModifiedDate=2015-01-01T01:00:00 HTTP/1.1
Authorization: OAuth {access token}

Response

HTTP/1.1 200 OK
Content-Type: application/xml

<ConnectResponse>
  <Metadata>
    <Paging>
      <TotalPages>1</TotalPages>
      <TotalItems>2</TotalItems>
      <Page>1</Page>
      <ItemsPerPage>200</ItemsPerPage>
      <PreviousPageURL />
      <NextPageURL />
    </Paging>
  </Metadata>
  <Data>
    <ProfileSummary>
      <Status>Active</Status>
      <LoginID>mariab@company1.com</LoginID>
      <XmlProfileSyncID>`string`123</XmlProfileSyncID>
      <ProfileLastModifiedUTC>2015-01-01T01:00:00</ProfileLastModifiedUTC>
    </ProfileSummary>
    <ProfileSummary>
      <Status>Inactive</Status>
      <LoginID>peterk@company1.com</LoginID>
      <XmlProfileSyncID>`string`456</XmlProfileSyncID>
      <ProfileLastModifiedUTC>2015-01-01T01:00:00</ProfileLastModifiedUTC>
    </ProfileSummary>
  </Data>
</ConnectResponse>