...
Note |
---|
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. |
...
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. |
...
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
...
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:
|
...
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) |
Code Block |
---|
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 |
Code Block |
---|
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 |
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:
|
Code Block | ||||
---|---|---|---|---|
| ||||
curl -v -H "Authorization: Bearer <token>" \ "https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/travellers?q=bob&page=0&pageSize=10" |
Code Block | ||||
---|---|---|---|---|
| ||||
{ "moreResults": false, "results": [{ "uuid": "065fe9e0-47b7-4d12-b3de-d3aa38169175", "fullName": "Herr Bob Builder" }] } |
Anchor | ||||
---|---|---|---|---|
|
Scope | api.profilesondemand.read |
---|---|
Endpoint | api/v1/profiles/traveller/<uuid> |
Request method | GET |
...
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):
|
Anchor TravelerGreetingStructure TravelerGreetingStructure
Traveler "greeting" structure handling
TravelerGreetingStructure | |
TravelerGreetingStructure |
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).
When updating a profile in Umbrella Faces, it is important to only send either the compoundTitle or commonTitle / formalTitle but never both structures.
Expand | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||
|
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.
Create new traveler profile
...
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 |
...