Purpose

The purpose of the Profile API is to allow 3rd party systems to interact with and update profile information. This will give 3rd party systems the opportunity to interact with FCM in real time, allowing traveler data to move from internal customer systems to GDSs and Online Booking Tools with the minimum of delay, enhancing the traveler experience for both online and offline bookings.

The term Portal is also known as HUB for FCM customers globally.  It is critical that the key word is kept as ‘portal’.

API Request

The api will be developed as a restful api with the option to consume the service using XML or JSON.

A “Content-Type” header should be provided, specifying the format in which data is sent to the API. Similarly an “Accept” header should be provided, specifying the format in which data is received from the API.

Valid values for the Content Type and Accept headers are:

text/xml
application/json

Environments

The url for the production api is:

https://api.portal.fcm.travel

Test environments are available and as part of the implementation process we can set up an account in suitable test environment.  Please be aware that the test environments are refreshed periodically which may result in any test data created being removed.

Security

Security for the API will be provided using the OAUTH 2.0 protocol. Each API user will only be able to modify companies which have been explicitly white-listed for that user.

All messages to the API must use HTTPS with TLS 1.2. TLS 1.1 and below are disabled and will not work. An unsecured endpoint will not be available under any circumstances.

In order to perform operation, an access token should be obtained and passed back in subsequent operations. The following two headers should be provided in all authenticated requests:

• Authorization - bearer <access token>

• token_type - bearer

 <Access Token> should be replaced with the Access Token value obtained from the Token request.

Traveler Users

Traveler user accounts can be used to authenticate allowing the ability to build client facing applications, such as mobile apps using the API. Travelers who authenticate will only be able to perform operations on their own profile.

Service Accounts

Service Accounts can be configured and used to access API operations. If a Service Account is used it must be given explicit permissions to access operations. It will also need permissions to access and update profiles. Access to update profiles will be given to accounts based on a range of potential factors including individual companies, or various types of groups.

Profile Identities

Throughout the API, the ability to identify profiles is exceptionally important. Being able to identify profiles allows us to determine if

a)       A profile exists and should be updated or,
b)      A profile doesn’t exist and an error should be returned or a new profile created. 

Due to the wide varieties that the HUB platform interacts with, there are a number of ways a profile can be identified. The 3 key ways are:

-          Traveler Guid: the Traveler Guid is the identifier of a profile within the FCM environment. It is often synchronized with OBTs and GDSs and is the preferred way of identifying a profile.

-          Email Address: the primary email address of the profile is often used as an identifier where Traveler Guids are not available. They can also be used as a login if the API is being used to build third party applications where the user is required to login.

-          Lumina ID: the Lumina ID is valid only for systems that have knowledge of the Lumina Profile (AU/NZ)

When a profile identity is being passed to an API operation, at least one of these values must be provided. A search will be done to find the profile matching the identity. The order of precedence for these different pieces of information when conducting a search is:

1.       Traveler GUID
2.       Lumina ID
3.       Email Address

This means that a search is first done by Traveler Guid, and if no profile is found the Lumina ID is used, finally if a match is still not found, a search by Email Address will be conducted to locate a profile. The implication is that all pieces of information can be used and the first piece that matches a profile will ultimately be used find the profile.

Authentication

In order to authenticate, the user credentials need to be sent to the Token service operation. This will return an access token which is to be passed back in the Authorization header of subsequent requests, as well as a refresh token.

A refresh token can be used to obtain a new access token prior to the existing access token expiring. For service accounts, the refresh token will expire at the same time as the access token which will be 15 minutes after issuance. Refresh tokens generated by traveler user accounts will not expire and can be used indefinitely. The purpose of this behaviour is to allow native clients, such as mobile application, to retain the ability to indefinitely call the Profile API performing only operations to which they are entitled.