...

The interface is part of our standard web service offering and can be found in our swagger.yml documentation. documentation.

View file

name	swagger.yaml
height	250

Panel

title	Table of Contents

Table of Contents

exclude	(Example response)\|(Parameters)

...

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.While the Profiles on Demand API does not currently support all data fields and entity types available in Umbrella Faces, the

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.

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.

Note
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:

Info
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

...

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.
email	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.

...

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.

Note

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.

...

Code Block

language	js

{
    "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. There might be supplemental information in additional attributes which can change frequently and without any advance notice

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. There might be supplemental information in additional attributes which can change frequently and without any advance notice

Anchor
IDToken
IDToken
ID token

...

Code Block

language	js
title	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"
}

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. 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

...

Anchor
ProfilesAPI
ProfilesAPI
Profiles API

Search company profile

Scope	api.profilesondemand.read
Endpoint	api/v1/profiles/companies
Request method	GET

...

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: DEFAULT (Applies default search options as is within the Faces UI) SHORTNAME (To look for profiles with a specific shortname set; partial matches are returned) EXTERNAL_NR (To look for profiles with a specific externalNr set; only exact matches are returned) GENERIC_FIELD (To look in a specific field from the agencies generic setup) RECORD_LOCATOR (To look for profiles with matching record locator only) PHONE_NUMBER (To look for profiles based on a full phone number; must be provided in international format, e.g. +41449335390) Note: Please make sure to properly encode the "+" within the query string (as %2B) and do not include any formatting in the number. Faces will silently fail and return zero results if the phone number is supplied in an invalid format.
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 EXACT_MATCH: Exact match (case sensitive) CASE_INSENSITIVE_MATCH: Exact match (case insensitive) PARTIAL_MATCH: Split the search string at each whitespace and search using "contains" for each substring (case insensitive). The parameter may be given for the following scopes and will be ignored if provided for any other scope not listed here: SHORTNAME (defaults to PARTIAL_MATCH if not provided, EXACT_MATCH is not supported) GENERIC_FIELD (defaults to PARTIAL_MATCH if not provided)
detailSections	Specify additional profile areas to be returned if includeDetails is set to true. Only explicitly specified sections will be included.	Only the Any section may be specified, with more data-heavy sections only being allowed if pageSize is <= 25 The following sections are currently supportedallowed regardless of page size: AGENCY_INFO CONTACT_DATA PARENT_COMPANY COMMENT HISTORY TRAVELLER_SETTINGS GENERAL_SETTINGS

Code Block

language	bash
title	Example Request

curl -v -H "Authorization: Bearer <token>" \
    "https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/companies?q=acme&page=0&pageSize=10"

...

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

Note

Currently all profile sections are dumped if this parameter is omitted.

However, we'll be removing this behaviour and you'll be required to demonstrate usage of the "sections" paraemeter along with how and why each section is processed during certification.

Optional

Optional, no sections will be dumped if omitted

Code Block

language	bash
title	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"

...

The following sections are currently available in accordance with our Swagger schema definition:

Name

Contents

AGNCYAGENCY_INFO

Agency information:

uuid
name

CONTACT_DATA

Company contact data:

street
street2
zipCode
place
countryCode
phone
fax
E-Mail (email, email2, email3)
receiveDocs

PARENT_COMPANY

Parent company settings:

company (reference)
adminShareOption (only relevant if parent company is set)

MEMBERSHIPS

Corporate alliance Memberships

DEPRECATED - use GENERIC_FIELD_VALUES instead

Values (where filled) from the generic setup, output as key-value pairs where the key is the fieldname and the value is the value entered on the profile.

airline

alliance (2-Letter code)
memberNumber
type

hotel

alliance (2-Letter code)
memberNumber
customerRequest

rentalCar

alliance (2-Letter code)
memberNumber

GENERIC_VALUES

customerRequest
billingNumber
preferredProvider (boolean, can only be set on one at a time)

GENERIC_FIELD_VALUES

Values (where filled) from the generic setup

field (name, uuid)
value

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:

creditCards
- type (DC, AX, VI, CA, TP, JC, DS)
- maskedNumber
- expiratoin
- remark
- publishAsFop
webCard reference
hotelGuarantee reference
carGuarantee reference
railFormOfPayment reference - only available if rail feature is active in agency configuration
additionalFormOfPayment
travellerCardOptions
- fopOption
- hotelGuaranteeUsage
- carGuaranteeUsage
- webPaymentUsage

COMMENT

Comment on profile - only available to agency managers

HISTORY

History (Read Only):

lastModified (timestamp)
history (Only available to agency managers)

PUBLISH_STATES

Publish States (Read Only):

label
lastPublished (timestamp)
recordLocator
lastPublishState
faultIndicator

The Fault indicator will be one of

UNDEFINED - Default; check lastPublishState for text indication of status
SOFT_FAULT - OK (Everything in order, no special state)
QUEUED (Everything in order, but profile is currently queued for publishing)
INTENTIONALLY_NOT_PUBLISHED (Profile is in a (known) "desired" fault state (Publishing rejected / Profile processed by remote endpoint with warnings) and hence not listed in the profile center
HARD_FAULT - Profile is in a (known) fault state which cannot be resolved simply be re-publishing it (without any change to agency setup or manual profile safe)
)
TIMESTAMP_ISSUE (Profile has an error which is based on timestamp mismatches)
GENERAL_ERROR (The publish state is in error.)

INTERFACE_SETUP

Note
This section is read only and must not be included in updates. Sensitive properties (i.e. Concur Refresh Tokens) will not be returned by the API

travelGroups (only relevant for Cytric)
- id
- name
targetSystems
- agencyInterface
- attribute1 (interface-specific configuration; available depending on interface type)
- attribute2 (interface-specific configuration; available depending on interface type)
- attribute3 (interface-specific configuration; available depending on interface type)
- attribute4 (interface-specific configuration; available depending on interface type)
reportingOfficeId
gwsAgencyLocation

TRAVELLER_SETTINGS

defaultArranger
defaultTraveller
selfApprovalAllowed
approverSelectableByTraveller

GENERAL_SETTINGS

emailDelivery
profileRemindersOption - only available if profile reminders feature is active on agency
enableSelfRegistration - only available if self registration feature is active on agency

Get subsidiaries of a company profile

Scope	api.profilesondemand.write
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

Code Block

language	bash
title	Example request

curl -v -H "Authorization: Bearer <token>" \
    "https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/company/b9321d7e-9d72-4e80-ac49-d3aa38169175/subsidiaries"

Code Block

language	js
title	Example Response
collapse	true

[
	{
		"uuid": "da5a20c7-08db-42ae-a5e7-72737e9eb647",
		"name": "Hierarchy Child Company 2"
	},
	{
		"uuid": "2b8c21de-8e74-4d8d-b836-e904e4977c61",
		"name": "Hierarchy Child Company 1"
	}
]

Create new company profile

...

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)

...

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

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: DEFAULT (Applies default search options as is within the Faces UI) EMAIL (To look for profiles with matching E-Mail only - must be an exact match) USERNAME (To look for profiles with matching Username only - must be an exact match) GENERIC_FIELD (To look in a specific field from the agencies generic setup) RECORD_LOCATOR (To look for profiles with matching record locator only) PAPER (to look for profiles with a matching paper, e.g. a passport by number) PHONE_NUMBER (To look for profiles based on a full phone number; must be provided in international format, e.g. +41449335390) Note: Please make sure to properly encode the "+" within the query string (as %2B) and do not include any formatting in the number. Faces will silently fail and return zero results if the phone number is supplied in an invalid format.
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 EXACT_MATCH: Exact match (case sensitive) CASE_INSENSITIVE_MATCH: Exact match (case insensitive) PARTIAL_MATCH: Split the search string at each whitespace and search using "contains" for each substring (case insensitive). The parameter may be given for the following scopes and will be ignored if provided for any other scope not listed here: GENERIC_FIELD (defaults to PARTIAL_MATCH if not provided) PAPER (defaults to PARTIAL_MATCH if not provided)
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.Only the	Any section may be specified, with more data-heavy sections only being allowed if pageSize is <= 25 The following sections are currently supportedallowed regardless of page size: COMPANY_INFO COMPANY_CONTACT_DATA GENERAL_DATA ROLES PREFERENCESROLES COMMENT HISTORY

Code Block

language	bash
title	Example request

curl -v -H "Authorization: Bearer <token>" \
    "https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/travellers?q=bob&page=0&pageSize=10"

Code Block

language	js
title	Example response

{
	"moreResults": false,
	"results": [{
		"uuid": "065fe9e0-47b7-4d12-b3de-d3aa38169175",
		"fullName": "Herr Bob Builder"
	}]
}

Anchor
GetTravelerProfile
GetTravelerProfile
Get traveler profile

Scope	api.profilesondemand.read
Endpoint	api/v1/profiles/traveller/<uuid>
Request method	GET

Retrieves the details of a single traveler 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

Note

Currently all profile sections are dumped if this parameter is omitted.

However, we'll be removing this behaviour and you'll be required to demonstrate usage of the "sections" paraemeter along with how and why each section is processed during certification.

Optional

Optional, no sections will be dumped if omitted

Code Block

language	bash
title	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&sections=COMPANY_INFO&sections=MEMBERSHIPS"

Code Block

language	js
title	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": []
		}
	}
}

...

Name

Contents

COMPANY_INFO

Information on the associated company:

UUID
name (read only)
Customer number (externalNr, read only)

COMPANY_CONTACT_DATA

Contact information of the associated company (read only, provided for simplicity / reduce the need to talk to the company endpoint):

Address (street, street2, zipCode, place, countryCode)
phone
fax
E-Mail (email, email2, email3)

GENERAL_DATA

General profile information:

gender
title
sex
greeting (see: Traveler "greeting" structure handling)
- commonTitle
- formalTitle
- compundTitle
language
Phones (businessPhone, privatePhone, mobilePhone)
email
birhtdate
nationality

GENERIC_VALUESDEPRECATED - use GENERIC_FIELD_VALUES instead

Values (where filled) from the generic setup, output as key-value pairs where the key is the fieldname and the value, the value entered on the profile.

GENERIC_FIELD_VALUES

Values (where filled) from the generic setup

field (name, uuid)
value

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:

alliance-code
membernumber
pin (Flight memberships only)

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:

firstname, lastname
phone
email

Note

The informaton in this section will be duplicated in JSON Path "data.emergencyContact" as well as "data.contacts.emergencyContact"

Please update your implementation to only use "data.contacts.emergencyContact" - the old location "data.emgerencyContact" is deprecated and will be removed in the near future!

ARRANGER_CONTACTS

Arranger contact(s):

displayText
contactUuid: (Referenced Traveller UUID) - may be empty in case Faces is still awaiting the profile to be delivered rom an external system

APPROVER_CONTACTS

Approver contact(s):

displayText
contactUuid: (Referenced Traveller UUID) - may be empty in case Faces is still awaiting the profile to be delivered from an external system

ROLES

Roles as show in Faces UI with the respective checkboxes (true/false):

traveller
arranger
approver

PREFERENCES

Preferences:

smoker
preferredSeat (A or W)
preferredFood (4-Letter code)

CREDIT_CARDS

Credit card related information:

creditCards
- type (DC, AX, VI, CA, TP, JC, DS)
- maskedNumber
- expiratoin
- remark
- publishAsFop
- nameOnCard
webCard reference
hotelGuarantee reference
carGuarantee reference
railFormOfPayment reference - only available if rail feature is active in agency configuration

RAIL_INFORMATION

Rail related information - only available if rail feature is active in agency configuration

preferredClass
preferredSeat (A or W)
railCards
- type
- number
- expiration
- class
- collectBonusPoints
- validFromStation
- validToStation

RESIDENT_INFORMATION

(Spanish) Resident Information - only available if spanish resident feature is active in agency configuration

area
areaCode
cardType
cardNumber
firstname
firstSurname
secondSurname

TRAVEL_GROUP_ASSIGNMENTS

Travel group assignments - will only be populated if profile is synchronized to Cytric:

groupId (Note: Will be the same for all group assignments)
role

COMMENT

Comment on profile - only available to agency managers

HISTORY

History (Read Only):

lastModified (timestamp)
history (Only available to agency managers)

PUBLISH_STATES

Publish States (Read Only):

label
lastPublished (timestamp)
recordLocator
lastPublishState
faultIndicator

The Fault indicator will be one of

UNDEFINED - Default; check lastPublishState for text indication of status
SOFT_FAULT - OK (Everything in order, no special state)
QUEUED (Everything in order, but profile is currently queued for publishing)
INTENTIONALLY_NOT_PUBLISHED (Profile is in a (known) "desired" fault state (Publishing rejected / Profile processed by remote endpoint with warnings) and hence not listed in the profile centerHARD_FAULT - Profile is in a (known) fault state which cannot be resolved simply be re-publishing it (without any change to agency setup or manual profile safe)
TIMESTAMP_ISSUE (Profile has an error which is based on timestamp mismatches)
GENERAL_ERROR (The publish state is in error.)

UNUSED_TICKETS

Unused ticket information - only available if Magnatech is active on agency (Read Only):

carrier
expiryDate
fare
pnr
ticketNumber

Anchor
TravelerGreetingStructure
TravelerGreetingStructure
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.

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:

Expand

title	Formal Titles

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.

Expand

title	API Request Examples

compoundTitle in API request	resulting commonTitle	resulting formalTitle	Remarks
MS	MS
MR DR	MR	DR	If the travel agency is using title structure "Compound", the stored value will not be visible in the UI since "MR DR" is unsupported
MISS Lady	MISS	Lady	Not supported by the Faces UI - would show as follows: Title Structure Default: "Lady" would not be visible in the UI Title Structure Compound: Title in the UI would be shown as "-" since a combination of "MISS Lady is unsupported
PROF MRS	UNDEFINED	PROF MRS	Invalid request results in incorrect parsing since the commonTitle is to be sent as the first part of the compoundTitle
PROF	UNDEFINED	PROF
Rev	UNDEFINED	Rev	If the travel agency is using title structure "Default", the stored value will not be visible in the UI

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

...

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

...

This API is an extension to the Profiles API and allows to send and receive plaintext credit card information from / to Umbrella Faces.

Info
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.

...

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

...

Code Block

language	js
title	Example Response
collapse	true

{
	"groups": [
		{
			"uuid": "8744e74c-29c9-4009-8629-036d01d5f2cd",
			"groupType": {
				"@type": "integrated",
				"key": "general.header_prefs"
			},
			"sequence": 7,
			"defaultLabel": "Preferences",
			"labels": {
				"sv_SE": "Önskemål",
				"es_ES": "Preferencias",
				"fr_BE": "Préférences",
				"nl_NL": "Präferenzen",
				"hu_HU": "Felhasználói beállítások",
				"de_CH": "Präferenzen",
				"it_CH": "Preferenze",
				"de_DE": "Präferenzen",
				"kl_GL": "Sallinngortitat",
				"cs_CZ": "Preference",
				"da_DK": "Præferencer",
				"pl_PL": "Preferencje",
				"sk_SK": "Preferencie",
				"it_IT": "Preferenze",
				"pt_PT": "Präferenzen",
				"fr_FR": "Préférences",
				"en_US": "Preferences",
				"de_AT": "Präferenzen",
				"fr_CH": "Préférences",
				"en_GB": "Preferences",
				"nl_BE": "Präferenzen"
			},
			"fields": [
				{
					"uuid": "390c82f6-22fb-48c5-a82e-337b62a2afd8",
					"name": "OptInNewsletter",
					"sequence": 0,
					"internalCode": "",
					"profileType": "TRAVELLER",
					"editable": true,
					"defaultLabel": "Für Newsletter anmelden",
					"labels": {
						"en_US": "Opt-In to Newsletter",
						"en_GB": "Opt-In to Newsletter"
					},
					"fieldType": "INPUT",
					"elective": "OPTIONAL",
					"validation": {
						"@type": "none"
					}
				}
			]
		}
	],
	"standardFieldDefinitions": [
		{
			"uuid": "d2484146-b681-11ec-9e61-482ae368e12c",
			"collectionName": null,
			"fieldName": "email",
			"profileType": "CORPORATE",
			"affectedUserGroup": "ENTIRE_AGENCY",
			"fieldDisplayType": "MANDATORY"
		},
		{
			"uuid": "d2481a36-b681-11ec-9e60-482ae368e12c",
			"collectionName": null,
			"fieldName": "phoneMobile",
			"profileType": "TRAVELLER",
			"affectedUserGroup": "COMPANY_ADMIN_AND_TRAVELLER",
			"fieldDisplayType": "MANDATORY"
		},
		{
			"uuid": "d2486860-b681-11ec-9e62-482ae368e12c",
			"collectionName": "flightmemberships",
			"fieldName": "additionalinfo",
			"profileType": "TRAVELLER",
			"affectedUserGroup": "ENTIRE_AGENCY",
			"fieldDisplayType": "HIDDEN"
		},
		{
			"uuid": "d247cc20-b681-11ec-9e5f-482ae368e12c",
			"collectionName": "hotelmemberships",
			"fieldName": "alliance",
			"profileType": "TRAVELLER",
			"affectedUserGroup": "ENTIRE_AGENCY",
			"fieldDisplayType": "MANDATORY"
		}
	]
}

Anchor
ProfileCenterAPI
ProfileCenterAPI
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

Code Block

language	bash
title	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"

Code Block

language	js
title	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

...

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:

TRAVELLER
CORPORATE

Will return all frequent flyer options (unfiltered) if omitted

Code Block

language	bash
title	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

Code Block

language	bash
title	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 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

...

Page History

Versions Compared

Old Version 41

New Version 88

Key

Rate Limiting

Authentication

Application registration and certification

Step 5: Get new access token

AnchorIDTokenIDTokenID token

Decoded ID-Token

AnchorProfilesAPIProfilesAPIProfiles API

Search company profile

Get subsidiaries of a company profile

Parameters

Create new company profile

Parameters

Parameters

Implementation notes

Delete company profile

Parameters

Example response

Search traveler profile

Parameters

AnchorGetTravelerProfileGetTravelerProfileGet traveler profile

Parameters

AnchorTravelerGreetingStructureTravelerGreetingStructureTraveler "greeting" structure handling

Using compoundTitle vs commonTitle & formalTitle

Greeting validation

Create new traveler profile

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

AnchorProfileCenterAPIProfileCenterAPIProfile Center API

Get publish errors

Parameters

System reference data API

Parameters

Get hotel chain codes

Get rental car providers

Parameters

Anchor
IDToken
IDToken
ID token

Anchor
ProfilesAPI
ProfilesAPI
Profiles API

Anchor
GetTravelerProfile
GetTravelerProfile
Get traveler profile

Anchor
TravelerGreetingStructure
TravelerGreetingStructure
Traveler "greeting" structure handling

Anchor
ProfileCenterAPI
ProfileCenterAPI
Profile Center API