...
The interface is part of our standard web service offering and can be found in our swagger documentation.
View file | ||||
---|---|---|---|---|
|
Panel | ||||
---|---|---|---|---|
| ||||
|
...
Faces supports multiple Oauth2 grant flows, depending on the individual requirements of the client application. The following table lists possible flows:
Type | Purpose | Description | Restrictions | ||
---|---|---|---|---|---|
Authorization Code | Interact with the API on behalf of an end-user | Allows an application to act on behalf of a (or multiple) specific user within Faces. The Authorization Code Flow requires the client application to open a popup-window where an user signs into Faces and explicitly allows access. Once Access has been granted, a refresh-token is issued which allows further access without additional human interaction. | Not all API operations may be available, depending on the authorization level of the user. (e.g. company data can not be queried or updated by a traveller) | ||
Implicit | Similar to the Authorization Code flow, with the difference that no refresh-token will be issued and thus only temporary access of maximum one hour is possible before re-confirmation is needed. | Same as for Authorization Code.
| |||
Client Credentials | Machine-to-Machine communication | Currently allows a specific OAuth2 Client to be linked to a specific travel agency in Faces. No end-user interaction is required | ID-Tokens cannot be requested since the access is not tied to a specific user. |
...
Parameter | Description | ||
---|---|---|---|
CLIENT_ID:CLIENT_SECRET | The clientId and clientSecret which has been setup for the application, sent as HTTP Basic authentication
| ||
code=THE_AUTH_CODE | The authorization code received in step 3 | ||
redirect_uri=CALLBACK_URL | The same callback url as used in step 2 | ||
grant_type=authorization_code | Specifies that you are wanting to trade an authorization_code for a long-lived request token. |
...
Code Block | ||
---|---|---|
| ||
{ "access_token": "eb0afd63-7ad3-4b0f-a3cb-bacbbf4cac7c", "token_type": "bearer", "refresh_token": "0561038e-02d3-48e4-a859-399acacad59c", "expires_in": 3599 } |
Note |
---|
Please do only rely on the "access_token", "token_type", "refresh_token" and "expires_in" attributes within the token response payload. |
Step 5: Get new access token
...
As a result, a new access token will be issued.
Note |
---|
Please do only rely on the "access_token", "token_type", "expires_in" attributes within the token response payload. |
AnchorIDToken IDToken
ID token
IDToken | |
IDToken |
...
Code Block | ||||
---|---|---|---|---|
| ||||
{ "access_token": "f88a7119-b585-4c9c-9867-88a40aae41f8", "token_type": "bearer", "refresh_token": "bab32afe-acf8-4a8e-ba7c-ed567daa0ee4", "expires_in": 3599, "scope": "email openid profile", "id_token": "eyJhbGciOiJSUzI1NiJ9.eyJvcGVuaWQiOiIzZDkyMDVjYS1mMjY0LTRhZDgtYjFhYy1lNjQ1NTU3ZWFhOTkiLCJwcm9maWxlIjp7ImZpcnN0bmFtZSI6IlJlbW8iLCJwaG9uZSI6Iis0MTQ0MTIzNDU2NyIsImRpc3BsYXluYW1lIjoiSGVyciBSZW1vIFLDpGJlciIsIm5hbWUiOiJSw6RiZXIifSwiZW1haWwiOiJyZW1vLnRlc3RAdW1icmVsbGEuY2gifQ.ni2_4eszvqV5JgWBzJNmQ8jq225_7i-TiMAFzSGDSkPt6J5CTPSQF5wsq_Og5tOzd39nybGfwRzDyAkAOWinU2_djUv58gMx095U77ccSlSVYca6sn8t8WL62v8AOPSO9h8ok52nQpjtZFWcni4KABlcCKd_feT_5KjAmsRQwf7NZ0gqkoP3Y4Ymo454N8ezu822slF-ub4UdA1VBHDZuCJtQWbdsT2Cfep1NWRf3by_uP2s6yxHcHmQ0R_kYwXKMW2SbxyGo821cN-sxXYmppb4ipDtPKC7ANUYc5wZQ2Gp0gAenMIfxooz0njkEWKKMq3pwZWNJnWHDwVsluqI_w" } |
Note |
---|
Please do only rely on the "access_token", "token_type", "refresh_token", "expires_in", "scope" and "id_token" attributes within the token response payload. |
Decoded ID-Token
The following extract depicts a decoded ID-Token from the value of "id_token" in the response above
...
Scope | api.profilesondemand.writeread |
---|---|
Endpoint | api/v1/profiles/company/<uuid>/subsidiaries |
Request method | GET |
...
Umbrella Faces logically divides a greeting into common title and formal title. The common title is restricted to a predefined list (please see the swagger document for the most up to date list), whereas the formal title allows storage of freetext title information with the limitation of only showing certain formal titles in the UI.
Note | ||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Depending on the travel agency setup, not all combinations of common / formal title are supported by the Faces UI. It's best to consult with the travel agency on their setup to ensure a consistent user experience. The common titles referenced in the swagger definition are generally valid for every agency. Please refer to the following table:
|
Using compoundTitle vs commonTitle & formalTitle
Umbrella Faces in it's backend always stores the compoundTitle, but transparently derives common and formal title in API requests using the following general format: compoundTitle = trim(commonTitle + " " + formalTitle).
...
It is important to note that the commonTitle is mandatory whenever sex is set to M MALE or F FEMALE if the agency is using Title Structure "Default".
Should you create / update a profile using compoundTitle, you might still get an errorMessage for greeting.commonTitle in case the supplied compoundTitle can not be derived into a valid commonTitle.
Get linked traveler profiles
Anchor TravelerGreetingStructure TravelerGreetingStructure
Arranger
TravelerGreetingStructure | |
TravelerGreetingStructure |
Scope | api.profilesondemand.read |
---|---|
Endpoint | api/v1/traveller/<uuid>/arranger-contacts |
Request method | GET |
Query returns an array of travelers where the specified uuid is linked as an arranger.
Parameters
Name | Description | Validation |
---|---|---|
uuid | The profile UUID for which you want to get a list of travellers where profile is selected as arranger | Mandatory parameter |
Code Block | ||||
---|---|---|---|---|
| ||||
curl -v -H "Authorization: Bearer <token>" \
"https://hurricane.umbrellanet.ch/uf-test/api/v1/traveller/065fe9e0-47b7-4d12-b3de-d3aa38169175/arranger-contacts" |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
[
{
"displayText": "Mr. Bob Example",
"contactUuid": "4cc19e19-11f4-46c3-b4f6-1ee2360a5752"
},
{
"displayText": "Mrs. Jane Never",
"contactUuid": "9a57f51b-1b7b-43cd-8582-d909670682aa"
}
] |
Anchor | ||||
---|---|---|---|---|
|
Scope | api.profilesondemand.read |
---|---|
Endpoint | api/v1/traveller/<uuid>/approver-contacts |
Request method | GET |
Query returns an array of travelers where the specified uuid is linked as an approver.
Parameters
Name | Description | Validation |
---|---|---|
uuid | The profile UUID for which you want to get a list of travellers where profile is selected as approver | Mandatory parameter |
Code Block | ||||
---|---|---|---|---|
| ||||
curl -v -H "Authorization: Bearer <token>" \
"https://hurricane.umbrellanet.ch/uf-test/api/v1/traveller/065fe9e0-47b7-4d12-b3de-d3aa38169175/approver-contacts" |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
[
{
"displayText": "Mr. Bob Example",
"contactUuid": "4cc19e19-11f4-46c3-b4f6-1ee2360a5752"
},
{
"displayText": "Mrs. Jane Never",
"contactUuid": "9a57f51b-1b7b-43cd-8582-d909670682aa"
}
] |
Create new traveler profile
...
Create a new traveler profile
Parameters
Name | Description | Validation |
---|---|---|
returnAddSections | List of additional profile sections which should be included in the response, even if not modified by the current operation | Optional parameter (GET) |
...
Updates (part of) the details of a single traveler profile.
Parameters
Name | Description | Validation |
---|---|---|
<uuid> | The UUID of the profile to update | Required parameter |
returnAddSections | List of additional profile sections which should be included in the response, even if not modified by the current operation | Optional parameter (GET) |
...
Delete a single traveler profile from Faces as well as all downline systems.
Parameters
Name | Description | Validation |
---|---|---|
<uuid> | The UUID of the profile to delete | Required parameter |
...
Fetch plaintext credit card data from a company or traveler profile.
Parameters
Name | Description | Validation |
---|---|---|
uuid | Owning (company / traveler) profile UUID | Required parameter |
ccUuid | Specific credit card UUID as obtained from the CREDIT_CARDS section of the profile. See: Company profile sections overview, Traveler profile sections overview | Required parameter |
...
Fetch the generic setup of a travelagency tailored to the access level of the calling user / application
Parameters
Name | Description | Validation |
---|---|---|
<uuid> | The UUID of the travelagency | Required parameter |
profileType | May be used to restrict the response to configuration for a specific profile type. | OptionalOne of TRAVELLER, CORPORATE
|
...
Fetch the generic setup of a company tailored to the access level of the calling user / application
Parameters
Name | Description | Validation |
---|---|---|
<uuid> | The UUID of the company | Required parameter |
merged | Defines wheter to include only the company setup (false) or merge it with the underlying agency setup (true) | Boolean value: true or false Optional, default: false |
profileType | May be used to restrict the response to configuration for a specific profile type. | Optional One of TRAVELLER, CORPORATE |
...
Fetch a list of publishing errors
Parameters
Name | Description | Validation |
---|---|---|
page | Current page within the result set, starts at 0 | Optional, number >= 0 |
pageSize | Maximum number of results per page. Default 25 | Optional, number > 0 and <= 100 |
since | Restrict results to errors that have occurred on or after a specific timestamp | Optional Format yyyy-MM-dd'T'HH:mm[:ss[.SSS]]X |
...
Fetch a list of available frequent flyer options
Parameters
Name | Description | Validation |
---|---|---|
profileType | Some options are only available on COPORATE level but no on TRAVELLER profiles. This parameter allows to query the valid options per profile type | Optional parameter:
Will return all frequent flyer options (unfiltered) if omitted |
Code Block | ||||
---|---|---|---|---|
| ||||
curl -v -H "Authorization: Bearer <token>" \ "https://hurricane.umbrellanet.ch/uf-test/api/v1/reference-data/air-providers?profileType=TRAVELLER" |
Get hotel chain codes
Scopes | (none needed) |
---|---|
Endpoints | api/v1/reference-data/hotel-chains |
Request method | GET |
Fetch a list of available hotel chain code options
Code Block | ||||
---|---|---|---|---|
| ||||
curl -v -H "Authorization: Bearer <token>" \
"https://hurricane.umbrellanet.ch/uf-test/api/v1/reference-data/hotel-chains" |
Get rental car providers
Scopes | (none needed) |
---|---|
Endpoints | api/v1/reference-data/car-providers |
Request method | GET |
...
Fetch a list of known rail card types
Parameters
Name | Description | Validation |
---|---|---|
agency | Allows specifying an agency UUID for which the supported rail card types should be listed. Depending on the agency setup the available types may differ | Optional Parameter Will return all card types if omitted |
...