Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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 NameValue
X-Rate-Limit-RemainingNumber 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

...

Faces supports multiple Oauth2 grant flows, depending on the individual requirements of the client application. The following table lists possible flows:

TypePurposeDescriptionRestrictions
Authorization CodeInteract 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 CredentialsMachine-to-Machine communicationCurrently allows a specific OAuth2 Client to be linked to a specific travel agency in Faces. No end-user interaction is requiredID-Tokens cannot be requested since the access is not tied to a specific user.

...

Code Block
languagejs
{
    "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
languagejs
titleAccess 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

...

NameDescriptionValidation
qFreetext query for finding matching profilesRequired parameter
pageCurrent page within the result set, starts at 0Optional, number >= 0
pageSizeMaximum number of results per page. Default 10Optional, number > 0 and <= 100
scopeSearch 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.
pSearch 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

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

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:

  • AGENCY_INFO

  • CONTACT_DATA

  • PARENT_COMPANY

  • COMMENT

  • HISTORY

  • TRAVELLER_SETTINGS

  • GENERAL_SETTINGS

...

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

NameContents
AGNCYAGENCY_INFOAgency 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

  • airline

    • alliance (2-Letter code)

    • memberNumber

    • type

  • hotel

    • alliance (2-Letter code)

    • memberNumber

    • customerRequest

  • rentalCar

    • alliance (2-Letter code)

    • memberNumber

    • 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
COMMENTComment 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

  • 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 "desired" fault state (Publishing rejected / Profile processed by remote endpoint with warnings))
  • 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

...

 

Scopeapi.profilesondemand.write
Endpointapi/v1/profiles/company/<uuid>
Request methodPATCH

Updates (part of) the details of a single company profile.

Parameters
NameDescriptionValidation
<uuid>The UUID of the profile to updateRequired parameter
returnAddSectionsList of additional profile sections which should be included in the response, even if not modified by the current operationOptional 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

Scopeapi.profilesondemand.write
Endpointapi/v1/profiles/company/<uuid>
Request methodDELETE

Delete a single company profile (along with all associated traveler profiles) from Faces as well as all downline systems.

Parameters
NameDescriptionValidation
<uuid>The UUID of the profile to deleteRequired 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

Scopeapi.profilesondemand.read
Endpointapi/v1/profiles/travellers
Request methodGET
Allows searching through a paged list of traveler profiles
Parameters
NameDescriptionValidation
qFreetext query for finding matching profilesRequired parameter
pageCurrent page within the result set, starts at 0Optional, number >= 0
pageSizeMaximum number of results per page. Default 10Optional, number > 0 and <= 100
cNarrow down the search for travelers attached to a specific company profileOptional, company UUID
scopeSearch 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.

pSearch 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

matchTypeSeach 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)
includeDetailsSpecify 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:

  • COMPANY_INFO

  • COMPANY_CONTACT_DATA

  • GENERAL_DATA

  • ROLES

  • PREFERENCES

  • COMMENT
  • HISTORY

Code Block
languagebash
titleExample 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
languagejs
titleExample response
{
	"moreResults": false,
	"results": [{
		"uuid": "065fe9e0-47b7-4d12-b3de-d3aa38169175",
		"fullName": "Herr Bob Builder"
	}]
}

Anchor
GetTravelerProfile
GetTravelerProfile
Get traveler profile

Scopeapi.profilesondemand.read
Endpointapi/v1/profiles/traveller/<uuid>
Request methodGET
Retrieves the details of a single traveler profile.

...

NameContents
COMPANY_INFOInformation 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:

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)
PASSPORTPassport(s) as shown in Faces UI
VISAVisa information as shown in Faces UI
ID_CARDIdentification Cards  as shown in Faces UI
EMERGENCY_CONTACT

Emergency contact:

  • firstname, lastname

  • phone

  • email

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

  • 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 "desired" fault state (Publishing rejected / Profile processed by remote endpoint with warnings))
  • 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
titleFormal Titles
Formal TitleTitle Structure "Default"Title Structure "Compound" *
Master(error) Not supported(tick) Supported
Mx(error) Not supported(tick) Supported
DR(tick) Supported(tick) Supported
PROF(tick) Supported(tick) Supported 
Rev(error) Not supported(tick) Supported
Sir(error) Not supported(tick) Supported
Lord(error) Not supported(tick) Supported
Lady(error) Not supported(tick) 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
titleAPI Request Examples
compoundTitle in API requestresulting commonTitleresulting formalTitleRemarks
MSMS  
MR DRMRDRIf the travel agency is using title structure "Compound", the stored value will not be visible in the UI since "MR DR" is unsupported
MISS LadyMISSLady

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 MRSUNDEFINEDPROF MRS

Invalid request results in incorrect parsing since the commonTitle is to be sent as the first part of the compoundTitle

PROFUNDEFINEDPROF 
RevUNDEFINEDRevIf 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

...

Code Block
languagebash
titleExample 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 methodGET

Fetch a list of available hotel chain code options

Code Block
languagebash
titleExample 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 methodGET

...