Using the Profiles on Demand API allows third-party applications to query profile information from Umbrella Faces after being authorized with OAuth2 authentication.
The interface is part of our standard web service offering and can be found in our swagger documentation.
Table of Contents
Preamble / General Notes
The Profiles on Demand API relies fully on the OAuth2 protocol to perform authentication and authorization to profiles. It is strongly suggested to get a general grasp of the OAuth 2.0 flows, specifically the Authorization Code and Client Credentials flows, before running any API related inquiries.
As the name suggests, the Profiles On Demand API is designed to provide profiles on demand.
It is specifically prohibited to run bulk queries for profiles aimed at dumping / synchronizing the full profile data base to a third party system.
The API is continuously being developed and extended. As a result, new data structures may be added to existing responses at any time without prior notice. It is therefore required to design a client application to only request information needed by the application as well as configure the application to not fail should there be additional (newly added) properties in the response.
Upon examining the swagger documentation you may find more APIs not listed in this documentation. These are for internal use only and will not be made available to the general public
Rate Limiting
As per our contract, we reserve the right to subject API calls to a rate limit. The following headers will be present in server responses in case an API is subject to rate limiting:
Normally these headers are not present, they will dynamically appear if you application becomes subject to rate limiting (i.e. due to having made excessive API calls in the past)
| Header Name | Value |
|---|---|
| X-Rate-Limit-Remaining | Number of requests remaining |
X-Rate-Limit-Retry-After | Sent alongside a HTTP 429 error when hitting the rate limit Number of seconds remaining until another API request may be made |
Authentication
Application registration and certification
Third parties wishing to access data from Faces must provide the following details, which will be evaluated before any Oauth API can be accessed:
| Field | Description |
|---|---|
| Application Name | Application name, which will be shown to the user |
| Application Purpose | Short description of what the application wants to achieve using the Oauth2 enabled APIs |
| Desired OAuth Scopes | OAuth Scopes requested by the application see Available OAuth Data-Scopes |
| Desired OAuth Flow(s) | One or more OAuth flows, see Supported OAuth2 Flows By default you will be granted access to the Authorization Code flow, which requires user interaction to authorize your application, however depending on your applications purpose it may be possible to setup a different flow (For example to allow unlimited access to all profiles belonging to your own travel agency in case you’re implementing an in-house application) |
Umbrella will provide the application with a clientId and clientSecret to be used for development on our integration environment at https://hurricane.umbrellanet.ch/uf-test
Certification will be achieved by demonstrating the product accessing Faces using Oauth
Available OAuth Data-Scopes
Your application will be granted some or all of the following OAuth scopes for data access:
| Scope | Description |
|---|---|
| api.profilesondemand.read | Access to the Profiles API (read only) |
| api.profilesondemand.write | Access to the Profiles API (write) |
| api.profilesondemand.ccaccess | Access to plaintext credit card details. Requires attestation of PCI compliance as well as special handling for CC numbers to be exchanged via our parnter Midoco |
| api.profilesondemand.profilecenter.read | Access to (certain functions of) the Profile Center API (read only) |
| openid | Required scope when requesting an ID-Token for “Login using Faces” functionality |
| agencyid | Optional scope to be included in and ID-Token. Please see the section Usage of an ID token within this document. |
Optional scope to be included in and ID-Token. Please see the section Usage of an ID token within this document. | |
| profile | Optional scope to be included in and ID-Token. Please see the section Usage of an ID token within this document. |
Please let our friendly support-staff know which scopes you’ll be requiring in order to provide which desired functionality.
Supported OAuth2 Flows
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.
The implicit flow is considered deprecated / unsafe and should no longer be used https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics-09#section-2.1.2 Please consider using the Authorization Code Grant | |
| 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. |
Please let us know which OAuth flow you plan on supporting for your use case when requesting API credentials. If not otherwise specified, we’ll be supplying you with access to the Authorization Code flow.
Oauth2 Authorization Code Flow by example
Step 1: Request authorization code grant
The user is given a link to start the authorization process, including mandatory parameters
| Parameter | Description |
|---|---|
| response_type=code | Specifies the application is requesting an authorization code grant (value = always “code”) |
| client_id=CLIENT_ID | The clientId which has been setup for the application |
| redirect_uri=CALLBACK_URL | Where Faces redirects the user after an authorization code is granted (full URI, including http:// https:// or other prefix) |
https://hurricane.umbrellanet.ch/uf-test/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL
Step 2: User authorizes the application
Upon clicking the link, the user must first login to Faces (unless they are already logged in). Then they will be prompted by the service to authorize or deny the application access.
An example authorization prompt may look like this:
Step 3: Application receives authorization code
If the user clicks "Authorize", Faces redirects to the application redirect URI which was specified in the request, along with an authorization code.
The redirect would look something like this:
https://your.application.com/callback?code=THE_AUTH_CODE
Step 4: Application requests refresh and access token
The application requests an access token from the API, by passing the authorization code along with authentication details using HTTP POST:
| Parameter | Description |
|---|---|
| CLIENT_ID:CLIENT_SECRET | The clientId and clientSecret which has been setup for the application, sent as HTTP Basic authentication Please note that we only officially support client_id / client_secret being sent via HTTP Basic authentication header. |
| 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. |
Example Request using cURL
# https://CLIENT_ID:CLIENT_SECRET@hurricane.umbrellanet.ch/uf-test/oauth/token?grant_type=authorization_code&code=THE_AUTH_CODE&redirect_uri=CALLBACK_URL
curl -v -X POST \
-H "Content-type: application/x-www-form-urlencoded" \
-u client-id:client-secret \
-d "grant_type=authorization_code" \
-d "code=THE_AUTH_CODE" \
-d "redirect_uri=CALLBACK_URL" \
https://hurricane.umbrellanet.ch/uf-test/oauth/token
As a result, the application is granted short-lived access token used during API calls, as well as a long-lived refresh token which can be used for obtaining further access tokens:
{
"access_token": "eb0afd63-7ad3-4b0f-a3cb-bacbbf4cac7c",
"token_type": "bearer",
"refresh_token": "0561038e-02d3-48e4-a859-399acacad59c",
"expires_in": 3599
}
Please do only rely on the "access_token", "token_type", "refresh_token" and "expires_in" attributes within the token response payload.
There might be supplemental information in additional attributes which can change frequently and without any advance notice
Step 5: Get new access token
After the access token expires, a new one may be obtained similar to step 4:
Example Request using cURL
# https://CLIENT_ID:CLIENT_SECRET@hurricane.umbrellanet.ch/uf-test/oauth/token?grant_type=refresh_token&refresh_token=REFRESH_TOKEN
curl -v -X POST \
-H "Content-type: application/x-www-form-urlencoded" \
-u client-id:client-secret \
-d "grant_type=refresh_token" \
-d "refresh_token=REFRESH_TOKEN" \
https://hurricane.umbrellanet.ch/uf-test/oauth/token
As a result, a new access token will be issued. Our application may also issue a new refresh token in case the currently used one is due for expiration, which shall be stored upon reception and used from this point in time onwards.
Oauth2 Client Credentials Flow by example
When using the Client Credentials Flow, no user interaction is required, instead the authorization level of your application is directly configured within Umbrella Faces. As a result the Client Credentials Flow comprises of only a single step:
Step 1 out of 1: Get new access token
Whenever a new access token is needed (either because none is available or the old one has expired), a new one may be obtained by issuing a HTTP POST request to our token endpoint, supplying client_id and client_secret as HTTP Basic authentication, along with a grant_type of client_credentials:
Example Request using cURL
# https://CLIENT_ID:CLIENT_SECRET@hurricane.umbrellanet.ch/uf-test/oauth/token?grant_type=client_credentials
curl -v -X POST \
-H "Content-type: application/x-www-form-urlencoded" \
-u client-id:client-secret \
-d "grant_type=client_credentials" \
https://hurricane.umbrellanet.ch/uf-test/oauth/token
As a result, a new access token will be issued.
Please do only rely on the "access_token", "token_type", "expires_in" attributes within the token response payload.
There might be supplemental information in additional attributes which can change frequently and without any advance notice
ID token
In addition(or instead) of our OAuth API scopes, we do also support scopes resulting in generation of an ID-Token, which will be returned in Step 4 as well as Step 5 of the Authorization flow.
If only an ID-Token is desired, the OAuth process may be called with response_type=token which will trigger the OAuth 2.0 Implicit flow and only generate a short-lived access token without providing a refresh token.
| Scope | Description |
|---|---|
| openid | Required scope, triggers generation of an ID token containing the Faces-UUID of the profile in an “openid” attribute |
| profile | Outputs the user profile in a “profile” attribute containing a displayname and (depending on availability) firstname / name / phone |
| Outputs the users e-mail address as “email” attribute | |
| agencyid | Outputs the UUID of the associated users travel agency (the main agency if access to multiple agencies is granted in case of an administrator) in the “agencyid” attribute of the token |
The ID-Token will be presented in form of a JSON Web Token and will be cryptographically signed using our Service Provider Certificate available at <faces_url>/saml/metadata,
i.e. https://hurricane.umbrellanet.ch/uf-test/saml/metadata
Access Token with additional id_token
{
"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"
}
Please do only rely on the "access_token", "token_type", "refresh_token", "expires_in", "scope" and "id_token" attributes within the token response payload.
There might be supplemental information in additional attributes which can change frequently and without any advance notice
Decoded ID-Token
The following extract depicts a decoded ID-Token from the value of "id_token" in the response above
{
"openid": "3d9205ca-f264-4ad8-b1ac-e645557eaa99",
"profile": {
"firstname": "Remo",
"phone": "+41441234567",
"displayname": "Herr Remo Räber",
"name": "Räber"
},
"email": "remo.test@umbrella.ch"
}
Profiles API
Search company profile
| Scope | api.profilesondemand.read |
|---|---|
| Endpoint | api/v1/profiles/companies |
| Request method | GET |
Allows searching through a paged list of company profiles. This API can be used to narrow-down the traveler profile search by company.
Parameters
| Name | Description | Validation |
|---|---|---|
| q | Freetext query for finding matching profiles | Required parameter |
| page | Current page within the result set, starts at 0 | Optional, number >= 0 |
| pageSize | Maximum number of results per page. Default 10 | Optional, number > 0 and <= 100 |
| scope | Search scope | Optional, may be one of:
|
| p | Search scope parameter | Required if scope=GENERIC_FIELD: Name of the generic field to search in Optional for scope=RECORD_LOCATOR: System type or Label (e.g. “CSX”, “GALILEO_WS”, “My HR-System”) Prohibited otherwise |
| matchType | Search string match type | Optional parameter. Controls for certain scopes how the search string from "q" is matched against the profile database value
The parameter may be given for the following scopes and will be ignored if provided for any other scope not listed here:
|
| detailSections | Specify additional profile areas to be returned if includeDetails is set to true. Only explicitly specified sections will be included. | Any section may be specified, with more data-heavy sections only being allowed if pageSize is <= 25 The following sections are allowed regardless of page size:
|
Example Request
curl -v -H "Authorization: Bearer <token>" \
"https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/companies?q=acme&page=0&pageSize=10"
Get company profile
| Scope | api.profilesondemand.read |
|---|---|
| Endpoint | api/v1/profiles/company/<uuid> |
| Request method | GET |
Retrieves the details of a single company profile.
Parameters
| Name | Description | Validation |
|---|---|---|
| <uuid> | The UUID of the profile to retrieve | Required parameter |
| sections | Areas of the profile to be returned. Must be used to reduce the amount of data transferred
| Optional, no sections will be dumped if omitted |
Example request
curl -v -H "Authorization: Bearer <token>" \
"https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/company/b9321d7e-9d72-4e80-ac49-d3aa38169175?sections=CONTACT_DATA,MEMBERSHIPS"
Company profile sections overview
The following sections are currently available in accordance with our Swagger schema definition:
| Name | Contents |
|---|---|
| AGENCY_INFO | Agency information:
|
| CONTACT_DATA | Company contact data:
|
| PARENT_COMPANY | Parent company settings:
|
| MEMBERSHIPS | Corporate alliance Memberships
|
| GENERIC_FIELD_VALUES | Values (where filled) from the generic setup
Note: Updates to generic field values are possible using either the field name or field uuid. Using the uuid is preferred since it is guaranteed to be unique, whereas name may not be unique or simply not set in some edge cases. |
| CREDIT_CARDS | Credit card related information:
|
| COMMENT | Comment on profile - only available to agency managers |
| HISTORY | History (Read Only):
|
| PUBLISH_STATES | Publish States (Read Only):
The Fault indicator will be one of
|
| INTERFACE_SETUP | This section is read only and must not be included in updates.
|
| TRAVELLER_SETTINGS |
|
| GENERAL_SETTINGS |
|
Get subsidiaries of a company profile
| Scope | api.profilesondemand.read |
|---|---|
| Endpoint | api/v1/profiles/company/<uuid>/subsidiaries |
| Request method | GET |
Query subsidiaries for a given company
Parameters
| Name | Description | Validation |
|---|---|---|
| uuid | The company UUID for which subsidiaries should be queried | Mandatory parameter |
Example request
curl -v -H "Authorization: Bearer <token>" \
"https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/company/b9321d7e-9d72-4e80-ac49-d3aa38169175/subsidiaries"
Create new company profile
| Scope | api.profilesondemand.write |
|---|---|
| Endpoint | api/v1/profiles/company |
| Request method | POST |
Create a new company 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) |
curl -v -X POST \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
--data '{
"externalNr": "1337",
"name": "Umbrella Organisation U+O AG",
"shortname": "UMBRELLA",
"data": {
"contact": {
"street": "Binzstrasse 33",
"zipCode": "8620",
"place": "Wetzikon",
"countryCode": "CH"
},
"genericFieldValues": [
{
"field": {
"uuid": "180d6569-28d8-43e1-9599-ba520e6d1fec"
},
"value": "1230A"
}
],
"agency": {
"uuid": "52b166c5-4990-49bb-b1f1-d3aa38169175"
}
}
}' https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/company
Example response
The profile, including any sections populated by the request, will be reported back, including the newly generated UUID - see Get company profile
Implementation notes
The data structure is the same as is output in Get company profile with the following exceptions:
Company profile UUID cannot be provided in the JSON
For creating of a new profile, the following required properties must always be populated:
name
shortname
Faces will apply default validation logic as seen on our Web UI and CSV interfaces and will report validation errors to the caller without saving the profile.
Update existing company profile
| Scope | api.profilesondemand.write |
|---|---|
| Endpoint | api/v1/profiles/company/<uuid> |
| Request method | PATCH |
Updates (part of) the details of a single company 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) |
curl -v -X PATCH \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
--data '{
"externalNr": "0815",
"name": "ACME Incorporated",
"shortname": "ACME-INC",
"data": {
"memberships": {
"airline": [{
"alliance": "LH",
"memberNumber": "DEMODEMO123",
"type": "SPECIAL_KEYWORD"
}]
}
}
}' https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/company/b9321d7e-9d72-4e80-ac49-d3a
Implementation notes
Depending on the authorization level of the caller, it may not be possible to edit certain properties. Changes to unmodifiable properties will be silently ignored if sent.
Callers should include only the properties they wish to edit in the PATCH request. Due to underlying synchronization logic to third party systems, it is required to perform all profile modifications within one single PATCH call (I.e. do not first edit the shortname, then add a membership code as two separate API calls).
The following logic is applied when editing collections, such as memberships to allow for modification of single elements within the collection without having separate API calls for that purpose:
If an “uuid” is supplied, the corresponding collection element is being modified
If there is no matching element with the given UUID, the update is ignored
In order to remove a collection item, it’s UUID is supplied, along with a property “_operation”, which is set to “remove”
In order to remove generic values from a profile, please include the field uuid or name but set the field content to empty.
Delete company profile
| Scope | api.profilesondemand.write |
|---|---|
| Endpoint | api/v1/profiles/company/<uuid> |
| Request method | DELETE |
Delete a single company profile (along with all associated traveler profiles) from Faces as well as all downline systems.
Parameters
| Name | Description | Validation |
|---|---|---|
| <uuid> | The UUID of the profile to delete | Required parameter |
curl -v -X DELETE \
-H "Authorization: Bearer <token>" \
https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/company/b9321d7e-9d72-4e80-ac49-d3aa38169175
Example response
HTTP 204 “No Content” with empty body
Search traveler profile
| Scope | api.profilesondemand.read |
|---|---|
| Endpoint | api/v1/profiles/travellers |
| Request method | GET |
Allows searching through a paged list of traveler profiles
Parameters
| Name | Description | Validation |
|---|---|---|
| q | Freetext query for finding matching profiles | Required parameter |
| page | Current page within the result set, starts at 0 | Optional, number >= 0 |
| pageSize | Maximum number of results per page. Default 10 | Optional, number > 0 and <= 100 |
| c | Narrow down the search for travelers attached to a specific company profile | Optional, company UUID |
| scope | Search scope | Optional, may be one of:
|
| p | Search scope parameter | Required if scope=GENERIC_FIELD: Name of the generic field to search in Optional for scope=RECORD_LOCATOR: System type or Label (e.g. “CSX”, “GALILEO_WS”, “My HR-System”) Optional for scope=PAPER: Type of paper to search for, PASSPORT, ID_CARD or VISA Prohibited otherwise |
| matchType | Seach string match type | Optional parameter. Controls for certain scopes how the search string from "q" is matched against the profile database value
The parameter may be given for the following scopes and will be ignored if provided for any other scope not listed here:
|
| includeDetails | Specify whether the search response should include detailed profile data | Boolean value: true or false Optional, default: false |
| detailSections | Specify additional profile areas to be returned if includeDetails is set to true. Only explicitly specified sections will be included. | Any section may be specified, with more data-heavy sections only being allowed if pageSize is <= 25 The following sections are allowed regardless of page size:
|
Example request
curl -v -H "Authorization: Bearer <token>" \
"https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/travellers?q=bob&page=0&pageSize=10"
Example response
{
"moreResults": false,
"results": [{
"uuid": "065fe9e0-47b7-4d12-b3de-d3aa38169175",
"fullName": "Herr Bob Builder"
}]
}
Get traveler profile
| Scope | api.profilesondemand.read |
|---|---|
| Endpoint | api/v1/profiles/traveller/<uuid> |
| Request method | GET |
Parameters
| Name | Description | Validation |
|---|---|---|
| <uuid> | The UUID of the profile to retrieve | Required parameter |
| sections | Areas of the profile to be returned. Must be used to reduce the amount of data transferred
| Optional, no sections will be dumped if omitted |
Example request
curl -v -H "Authorization: Bearer <token>" \
"https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/traveller/065fe9e0-47b7-4d12-b3de-d3aa38169175?sections=GENERIC_FIELD_VALUES§ions=COMPANY_INFO§ions=MEMBERSHIPS"
Example response
{
"uuid": "065fe9e0-47b7-4d12-b3de-d3aa38169175",
"firstname": "Bob",
"middlename": "",
"name": "Builder",
"email": "bob.builder@umbrella.ch",
"data": {
"company": {
"externalNr": "12345",
"name": "Fix-It Inc",
"uuid": "52f2b2c0-4990-49bb-b1f1-d3aa38169175"
},
"genericFieldValues": [
{
"field": {
"uuid": "30713acf-71dc-42c8-825f-7e5be9e98fbe",
"namme": "HairColor"
,
"value": "Red"
},
{
"field": {
"uuid": "5aba8e80-4ae5-4efc-a5df-60303aede01e",
"name": "FirstClassTraveler"
},
"value": "Y"
}
],
"memberships": {
"flight": [{
"alliance": "LH",
"memberNumber": "9992123412341234",
"pin": "",
"uuid": "dbb387a9-b5e7-44d0-87bf-64432ee3e582"
}],
"rentalCar": [],
"hotel": []
}
}
}
Traveler profile sections overview
The following sections are currently available in accordance with our Swagger schema definition:
| Name | Contents |
|---|---|
| COMPANY_INFO | Information on the associated company:
|
| COMPANY_CONTACT_DATA | Contact information of the associated company (read only, provided for simplicity / reduce the need to talk to the company endpoint):
|
| GENERAL_DATA | General profile information:
|
| GENERIC_FIELD_VALUES | Values (where filled) from the generic setup
Note: Updates to generic field values are possible using either the field name or field uuid. Using the uuid is preferred since it is guaranteed to be unique, whereas name may not be unique or simply not set in some edge cases. |
| MEMBERSHIPS | Flight, Hotel and Rentalcar-Memberships with:
|
| PASSPORT | Passport(s) as shown in Faces UI |
| VISA | Visa information as shown in Faces UI |
| ID_CARD | Identification Cards as shown in Faces UI |
| EMERGENCY_CONTACT | Emergency contact:
|
| ARRANGER_CONTACTS | Arranger contact(s):
|
| APPROVER_CONTACTS | Approver contact(s):
|
| ROLES | Roles as show in Faces UI with the respective checkboxes (true/false):
|
| PREFERENCES | Preferences:
|
| CREDIT_CARDS | Credit card related information:
|
| RAIL_INFORMATION | Rail related information - only available if rail feature is active in agency configuration
|
| RESIDENT_INFORMATION | (Spanish) Resident Information - only available if spanish resident feature is active in agency configuration
|
| TRAVEL_GROUP_ASSIGNMENTS | Travel group assignments - will only be populated if profile is synchronized to Cytric:
|
| COMMENT | Comment on profile - only available to agency managers |
| HISTORY | History (Read Only):
|
| PUBLISH_STATES | Publish States (Read Only):
The Fault indicator will be one of
|
| UNUSED_TICKETS | Unused ticket information - only available if Magnatech is active on agency (Read Only):
|
Traveler "greeting" structure handling
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.
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:
| Formal Title | Title Structure "Default" | Title Structure "Compound" * |
|---|---|---|
| Master |  Not supported |  Supported |
| Mx | Not supported | Supported |
| DR | Supported | Supported |
| PROF | Supported | Supported |
| Rev | Not supported | Supported |
| Sir | Not supported | Supported |
| Lord | Not supported | Supported |
| Lady | Not supported | Supported |
* Titles are supported, if no commonTitle is set. Since for "Compound" the UI is only using a single drop-down it is not possible to display a title such as MR DR.
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).
When updating a profile in Umbrella Faces, it is important to only send either the compoundTitle or commonTitle / formalTitle but never both structures.
Greeting validation
It is important to note that the commonTitle is mandatory whenever sex is set to MALE or 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
Arranger
| 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 |
Example request
curl -v -H "Authorization: Bearer <token>" \
"https://hurricane.umbrellanet.ch/uf-test/api/v1/traveller/065fe9e0-47b7-4d12-b3de-d3aa38169175/arranger-contacts"
Approver
| 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 |
Example request
curl -v -H "Authorization: Bearer <token>" \
"https://hurricane.umbrellanet.ch/uf-test/api/v1/traveller/065fe9e0-47b7-4d12-b3de-d3aa38169175/approver-contacts"
Create new traveler profile
| Scope | api.profilesondemand.write |
|---|---|
| Endpoint | api/v1/profiles/traveller |
| Request method | POST |
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) |
Example request
curl -v -X POST \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
--data '{
"username": "bob.builder",
"firstname": "Bob",
"middlename": "",
"name": "Builder",
"data": {
"contacts": {
"emergencyContact": {
"firstname": "Dizzy",
"phone": "+414412355889",
"email": "dizzy@umbrella.ch",
"lastname": "Mixer"
}
},
"generalData": {
"birthdate": "03.05.1973",
"gender": "MR",
"mobilePhone": "",
"nationality": "CH",
"language": "de_CH",
"privatePhone": "",
"businessPhone": "",
"title": "",
"email": "bob.builder@umbrella.ch"
},
"company": {
"uuid": "52f2b2c0-4990-49bb-b1f1-d3aa38169175"
},
"papers": {
"visas": [{
"country": "US",
"number": "8123789",
"entryType": "MULTIPLE",
"expiration": "01.03.2020",
"issueDate": "01.09.2019"
},
{
"country": "AE",
"number": "XXEE1123",
"entryType": "",
"expiration": "31.10.2020",
"issueDate": "09.03.2020"
}
],
"idCards": [{
"country": "CH",
"number": "123456",
"expiration": "31.12.2030",
"issueDate": "01.01.2020"
}],
"passports": [{
"country": "CH",
"number": "X12345",
"issueCountry": "CH",
"expiration": "31.12.2029",
"issueDate": "01.01.2019",
"issuePlace": "Zurich",
"primary": true
},
{
"country": "CH",
"number": "X999999",
"issueCountry": "CH",
"expiration": "31.12.2029",
"issueDate": "01.01.2019",
"issuePlace": "Zurich",
"primary": false
}
]
},
"genericFieldValues": [
{
"field": {
"uuid": "afee4339-3c12-412a-9504-fb475bed71ab",
"name": "EmailPersonal"
},
"value": "bob@hasnoemail.com"
},
{
"field": {
"uuid": "5e4f3887-5a46-4625-9658-99e579f6c41b",
"name": "AARPRate"
},
"value": "false"
},
{
"field": {
"uuid": "5294be6b-b4d6-4890-8b1f-40e16ab37e25",
"name": "PreferWheelchairAccess"
},
"value": "false"
},
{
"field": {
"uuid": "da0de48e-70c8-4ddb-b334-f2de7bdb2109",
"name": "MilitaryRate"
},
"value": "false"
},
{
"field": {
"uuid": "4577bf5f-d3b3-4f2b-9b4e-5eff858dff77",
"name": "SectionPositionCode"
},
"value": "Bulkhead"
},
{
"field": {
"uuid": "173704e3-7d5c-492e-b206-3d4e2d50e45a",
"name": "RuleClass"
},
"value": "Default Travel Class"
}
],
"memberships": {
"flight": [{
"alliance": "EI",
"memberNumber": "1199223123"
},
{
"alliance": "LH",
"memberNumber": "999999912317"
}
],
"rentalCar": [{
"alliance": "EP",
"memberNumber": "E111221"
}],
"hotel": [{
"alliance": "AL",
"memberNumber": "LL18675"
},
{
"alliance": "RT",
"memberNumber": "A123F"
}
]
}
}
}' https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/traveller
Example response
The profile, including any sections populated by the request, will be reported back, including the newly generated UUID - see Get traveler profile
Implementation Notes
The data structure is the same as is output in Get traveler profile with the following exceptions:
Traveler profile UUID cannot be provided in the JSON
“email” has to be sent in generalData, values in the root-level propertiy “email” will be ignored
For creating of a new profile, the following required properties must always be populated:
company.uuid
username
firstname
name
generalData.gender
Faces will apply default validation logic as seen on our Web UI and CSV interfaces and will report validation errors to the caller without saving the profile.
When adding a passport which should at the same time be added on a visa as linkedPassport, the following format has to be used to reference the passport (as no UUID is yet available): newpp-<2-letter-country code>-<passport number>
Example: newpp-CH-X12345678
Update existing traveler profile
| Scope | api.profilesondemand.write |
|---|---|
| Endpoint | api/v1/profiles/traveller/<uuid> |
| Request method | PATCH |
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) |
Example request
curl -v -X PATCH \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
--data '{
"username": "bobby.builder",
"firstname": "Bobby",
"data": {
"contacts": {
"emergencyContact": {
"firstname": "",
"phone": "",
"email": "",
"lastname": ""
}
},
"generalData": {
"birthdate": "04.05.1973",
"email": "bobby.builder@umbrella.ch"
},
"papers": {
"visas": [{
"country": "US",
"number": "8123789",
"entryType": "MULTIPLE",
"expiration": "01.03.2020",
"issueDate": "01.09.2019",
"uuid": "44f2ee67-eba5-4b29-9dfa-76e7eb97de39"
},
{
"_operation": "remove",
"uuid": "1eed6a49-f8e8-4441-b3ce-312f4dd1cd73"
}
]
},
"genericFieldValues": [
{
"field": {
"uuid": "afee4339-3c12-412a-9504-fb475bed71ab",
"name": "EmailPersonal"
},
"value": "bobby@hasnoemail.com"
}
]
}
}' https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/traveller/ceb545fd-5000-4f44-93dd-47a272f6f25a
Example response
Example Response: The profile will be reported back, including information on all modified profile sections, see Get traveler profile
Implementation notes
Depending on the authorization level of the caller, it may not be possible to edit certain properties (e.g. a traveller may not edit the username, but an agency administrator may do so) - changes to unmodifiable properties will be silently ignored if sent.
Callers should include only the properties they wish to edit in the PATCH request. Due to underlying synchronization logic to third party systems, it is required to perform all profile modifications within one single PATCH call (I.e. do not first edit the username, then add a passport as two separate API calls).
The following logic is applied when editing collections, such as visas or passports to allow for modification of single elements within the collection without having separate API calls for that purpose:
If an “uuid” is supplied, the corresponding collection element is being modified
If there is no matching element with the given UUID, the update is ignored
In order to remove a collection item, it’s UUID is supplied, along with a property “_operation”, which is set to “remove”
In order to remove generic values from a profile, please include the field name or uuid but set the field content to empty.
When adding a passport which should at the same time be added on a visa as linkedPassport, the following format has to be used to reference the passport (as no UUID is yet available): newpp-<2-letter-country code>-<passport number>
Example: newpp-CH-X12345678
Delete traveler profile
| Scope | api.profilesondemand.write |
|---|---|
| Endpoint | api/v1/profiles/traveller/<uuid> |
| Request method | DELETE |
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 |
curl -v -X DELETE \
-H "Authorization: Bearer <token>" \
https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/traveller/ceb545fd-5000-4f44-93dd-47a272f6f25a
Example response
HTTP 204 “No Content” with empty body
Plaintext Credit Card API
This API is an extension to the Profiles API and allows to send and receive plaintext credit card information from / to Umbrella Faces.
Partners wishing to use these APIs will be required proof their adherance to the PCI DSS security standards and will receive a custom endpoint from our credit card tokenization partner Midoco, which will ensure PCI compliace and forward card data from / to Umbrella Faces.
PCI Compliance Concept
Umbrella Faces itself is not holding any plaintext credit card numbers. Only credit card tokens are stored and need to be forwarded via our partner Midoco, which handles the tokenization and detokenization from / to plaintext data.
As a direct result of this, any partners wanting to exchange credit card numbers with Umbrella Faces will need to direct any API-Calls containing plaintext card numbers in either the request or response via Midoco.
In order to facilitate this design, the Plaintext Credit Card API exposes credit card information within separate API-Calls, with our regular Profiles on Demand API only exposing masked card numbers at most
Retrieve plaintext credit card data
| Scopes | api.profilesondemand.read api.profilesondemand.ccaccess |
|---|---|
| Endpoints | {midoco_proxy_url}/traveller/<uuid>/creditcard/{ccUuid} {midoco_proxy_url}/company/<uuid>/creditcard/{ccUuid} |
| Request method | GET |
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 |
Example request
curl -v -H "Authorization: Bearer <token>" \
{midoco_proxy_url}/traveller/ceb545fd-5000-4f44-93dd-47a272f6f25a/creditcard/eff37a66-4217-4762-a3be-2a9177fba9fc
Example response
{
"uuid": "bd380903-2e49-4920-9823-45626357c367",
"type": "VI",
"maskedNumber": "4444XXXXXXXX1111",
"number": "4444333322221111",
"expiration": "12/25",
"remark": ""
"publishAsFop": false
}
Store credit card number
| Scopes | api.profilesondemand.write api.profilesondemand.ccaccess |
|---|---|
| Endpoints | {midoco_proxy_url}/creditcard/store |
| Request method | POST |
Send a new or updated credit card number and retrieve a transaction number to be used for company or traveller profile update via separate API call.
Example request
curl -v -X POST \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
--data '{
"type": "VI",
"number": "4444333322221111"
}' {midoco_proxy_url}/creditcard/store
Example response
{
"transactionId": "ccTok-75cb0e1c-6640-4622-82bd-fed07fd1ca59",
"validUntil": "10.09.2021T13:37:69Z"
}
Example: Add previously stored credit card number to traveler profile
After sending a credit card number to Faces and receiving a transactionId in return, the transactionId may be used exactly once (up until the time indicated by the "validUntil" field) in a request to add or update a credit card on a company or traveler profile.
Example request
curl -v -X PATCH \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
--data '{
"data": {
"creditCardInfo": {
"creditCards": [{
"updatedNumberReference": "ccTok-75cb0e1c-6640-4622-82bd-fed07fd1ca59",
"expiration": "12/25",
"publishAsFop": true
}],
"webCard": {
"@type": "own-card",
"uuid": "6e6259b9-4fa9-41c7-8a7b-f5d68df8f38b"
},
"hotelGuarantee": {
"@type": "own-card",
"uuid": "ccTok-75cb0e1c-6640-4622-82bd-fed07fd1ca59"
},
"carGuarantee": {
"@type": "company-card"
}
}
}
}' https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/traveller/ceb545fd-5000-4f44-93dd-47a272f6f25a
Example Response
{
"uuid": "ceb545fd-5000-4f44-93dd-47a272f6f25a",
"username": "demo.user",
"firstname": "Demo",
"name": "Traveller",
"email": "demo@umbrella.ch",
"data": {
"creditCardInfo": {
"creditCards": [{
"uuid": "bcf0cfc2-5262-4996-98fb-f9a2ca8dc7a4",
"type": "VI",
"maskedNumber": "4444XXXXXXXX1111",
"expiration": "12/25",
"remark": "",
"publishAsFop": true
}, {
"uuid": "6e6259b9-4fa9-41c7-8a7b-f5d68df8f38b",
"type": "VI",
"maskedNumber": "4242XXXXXXXX4242",
"expiration": "12/25",
"remark": "",
"publishAsFop": true
}],
"webCard": {
"@type": "own-card",
"uuid": "6e6259b9-4fa9-41c7-8a7b-f5d68df8f38b",
"maskedNumber": "4242XXXXXXXX4242"
},
"hotelGuarantee": {
"@type": "own-card",
"uuid": "bcf0cfc2-5262-4996-98fb-f9a2ca8dc7a4",
"maskedNumber": "4444XXXXXXXX1111"
},
"carGuarantee": {
"@type": "company-card",
"uuid": "0d67e63f-a8a6-4a73-b826-d815a04aaedd",
"maskedNumber": "5200XXXXXXXX0007"
}
}
}
}
Configuration management API
This API is complimentary to the Profiles API and allows to query Umbrella Faces for defined settings on company / agency level
Within the Swagger documentation you'll see additional parameters and/or methods for some of these APIs which are only to be used internally.
All APIs and parameters not documented on this page are for internal use only and will not be made publicly available
Get generic setup for travel agency
| Scopes | api.profilesondemand.read |
|---|---|
| Endpoints | api/v1/configuration/setup/agency/{uuid} |
| Request method | GET |
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
|
Example request
curl -v -H "Authorization: Bearer <token>" \
"https://hurricane.umbrellanet.ch/uf-test/api/v1/configuration/setup/agency/f4cbed76-873c-4499-be0c-f8f60745d529"
Get generic setup for company
| Scopes | api.profilesondemand.read |
|---|---|
| Endpoints | api/v1/configuration/setup/company/{uuid} |
| Request method | GET |
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 |
Example request
curl -v -H "Authorization: Bearer <token>" \
"https://hurricane.umbrellanet.ch/uf-test/api/v1/configuration/setup/company/76445ed3-cbd4-45f5-96fc-f8f60745d529?merged=false"
Profile Center API
This API allows access to "Profile Center" functions of Umbrella Faces
Get publish errors
| Scopes | api.profilesondemand.profilecenter.read |
|---|---|
| Endpoints | api/v1/profile-center/corporate-publish-errors api/v1/profile-center/traveller-publish-errors |
| Request method | GET |
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 |
Example request
curl -v -H "Authorization: Bearer <token>" \
"https://hurricane.umbrellanet.ch/uf-test/api/v1/profilecenter/traveller-publish-errors?since=2023-01-23T13:00:25.000Z"
Example Response
{
"moreResults": false,
"results": [
{
"agencyInterface": {
"uuid": "14d74036-2a97-47ab-939c-2acc2c658865",
"name": "GAL-GWS",
"targetSystem": "GALILEO_WS",
"sequence": 0
},
"company": {
"uuid": "52f2b2c0-4990-49bb-b1f1-d3aa38169175",
"name": "Fixham Inc"
},
"traveller": {
"uuid": "065fe9e0-47b7-4d12-b3de-d3aa38169175",
"name": "Bob Builder"
},
"publishState": "UNABLE TO PROCESS"
}
]
}
System reference data API
This API is complimentary to the Profiles API and allows to query Umbrella Faces for reference data, such as lists of known rentalcar providers.
Get frequent flyer options
| Scopes | (none needed) |
|---|---|
| Endpoints | api/v1/reference-data/air-providers |
| Request method | GET |
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 |
Example request
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
Example request
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 available rental car providers
Example request
curl -v -H "Authorization: Bearer <token>" \
"https://hurricane.umbrellanet.ch/uf-test/api/v1/reference-data/car-providers"
Get rail card types
| Scopes | (none needed) |
|---|---|
| Endpoints | api/v1/reference-data/rail-card-types |
| 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 |
Example request
curl -v -H "Authorization: Bearer <token>" \
"https://hurricane.umbrellanet.ch/uf-test/api/v1/reference-data/rail-card-types"