Skip to end of metadata
Go to start of metadata

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

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

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:

FieldDescription
Application NameApplication name, which will be shown to the user
Application PurposeShort description of what the application wants to achieve using the Oauth2 enabled APIs
Desired OAuth ScopesOAuth 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:

ScopeDescription
api.profilesondemand.readAccess to the Profiles API (read only)
api.profilesondemand.writeAccess to the Profiles API (write)
api.profilesondemand.ccaccessAccess 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
openidRequired 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.

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:

TypeDescriptionRestrictions
Authorization Code

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)
ImplicitSimilar 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 CredentialsCurrently 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.

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

ParameterDescription
response_type=codeSpecifies the application is requesting an authorization code grant (value = always “code”)
client_id=CLIENT_IDThe clientId which has been setup for the application
redirect_uri=CALLBACK_URLWhere 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:

ParameterDescription
CLIENT_ID:CLIENT_SECRETThe clientId and clientSecret which has been setup for the application, sent as HTTP Basic authentication
code=THE_AUTH_CODEThe authorization code received in step 3
redirect_uri=CALLBACK_URLThe same callback url as used in step 2
grant_type=authorization_codeSpecifies 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
} 

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.

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.

ScopeDescription
openidRequired scope, triggers generation of an ID token containing the Faces-UUID of the profile in an “openid” attribute
profileOutputs the user profile in a “profile” attribute containing a displayname and (depending on availability) firstname / name / phone
emailOutputs the users e-mail address as “email” attribute
agencyidOutputs 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"
} 

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

Scopeapi.profilesondemand.read
Endpointapi/v1/profiles/companies
Request methodGET

Allows searching through a paged list of company profiles. This API can be used to narrow-down the traveler profile search by company.

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

Only the following sections are currently supported:

  • AGENCY_INFO

  • CONTACT_DATA

Example Request
curl -v -H "Authorization: Bearer <token>" \
    "https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/companies?q=acme&page=0&pageSize=10"
Example Response
{
	"moreResults": false,
	"results": [{
		"uuid": "b9321d7e-9d72-4e80-ac49-d3aa38169175",
		"name": "ACME Inc."
	}]
}

Get company profile

Scopeapi.profilesondemand.read
Endpointapi/v1/profiles/company/<uuid>
Request methodGET

Retrieves the details of a single company profile.

Parameters

 

NameDescriptionValidation
<uuid>The UUID of the profile to retrieveRequired parameter
sections

Areas of the profile to be returned.

May be used to reduce the amount of data transferred, if only specific information is required

All sections will be dumped if omitted. Please identify the relevant sections for your application during development and use a restricted information subset before moving to production.

Optional

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"
Example response
{
	"uuid": "dba95fe6-873c-4499-be0c-d3aa38169175",
	"externalNr": "00001",
	"name": "Demo GmbH",
	"shortname": "DEMO-1",
	"data": {
		"contact": {
			"street": "Binzstrasse 33",
			"street2": null,
			"zipCode": "8620",
			"place": "Wetzikon",
			"countryCode": "CH"
		},
		"memberships": {
			"airline": [{
				"uuid": "6bd21d65-0671-4196-8fd1-4de9f4ce9071",
				"alliance": "LH",
				"memberNumber": "DEMODEMO123",
				"type": "SPECIAL_KEYWORD"
			}],
			"hotel": [],
			"rentalCar": []
		},
		"genericValues": {}
	}
} 

Company profile sections overview

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

NameContents
AGNCY_INFOAgency information:
  • uuid

  • name

CONTACT_DATA

Company contact data:

  • street

  • street2

  • zipCode

  • place

  • countryCode

  • phone

  • fax

  • E-Mail (email, email2, email3)

MEMBERSHIPS

Corporate alliance Memberships

  • airline

    • alliance (2-Letter code)

    • memberNumber

    • type

  • hotel

    • alliance (2-Letter code)

    • memberNumber

  • rentalCar

    • alliance (2-Letter code)

    • memberNumber

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

Create new company profile

Scopeapi.profilesondemand.write
Endpointapi/v1/profiles/company
Request methodPOST

Create a new company profile

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"
        },
        "genericValues": {
            "costCenter": "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

 

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
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 genericValues from a profile, please include the fieldname but set the field content to empty or null.

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

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

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

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.

Only the following sections are currently supported:

  • COMPANY_INFO

  • GENERAL_DATA

  • ROLES

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

Scopeapi.profilesondemand.read
Endpointapi/v1/profiles/traveller/<uuid>
Request methodGET
Retrieves the details of a single traveler profile.
Parameters
NameDescriptionValidation
<uuid>The UUID of the profile to retrieveRequired parameter
sections

Areas of the profile to be returned.

May be used to reduce the amount of data transferred, if only specific information is required

All sections will be dumped if omitted. Please identify the relevant sections for your application during development and use a restricted information subset before moving to production.

Optional
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_VALUES&sections=COMPANY_INFO&sections=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"
		},
		"genericValues": {
			"HairColor": "Red",
			"FirstClassTraveler": "Y"
		},
		"memberships": {
			"flight": [{
				"alliance": "LH",
				"memberNumber": "9992123412341234",
				"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:

NameContents
COMPANY_INFOInformation on the associated company:
  • UUID

  • name

  • Customer number (externalNr)

COMPANY_CONTACT_DATA

Contact information of the associated company:

  • Address (street, street2, zipCode, place, countryCode)

  • phone

  • fax

  • E-Mail (email, email2, email3)

GENERAL_DATA

General profile information:

  • gender

  • title

  • language

  • Phones (businessPhone, privatePhone, mobilePhone)

  • email

  • birhtdate

  • nationality

GENERIC_VALUESValues (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.
MEMBERSHIPSFlight, Hotel and Rentalcar-Memberships, each with alliance-code and membernumber
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

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
  • webCard reference
  • hotelGuarantee reference
  • carGuarantee reference

Create new traveler profile

Scopeapi.profilesondemand.write
Endpointapi/v1/profiles/traveller
Request methodPOST

Create a new traveler profile

 

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": {
        "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
                }
            ]
        },
        "genericValues": {
            "EmailPersonal": "bob@hasnoemail.com",
            "AARPRate": "false",
            "PreferWheelchairAccess": "false",
            "MilitaryRate": "false",
            "SectionPositionCode": "Bulkhead",
            "RuleClass": "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.

Update existing traveler profile

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

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

Parameters
NameDescriptionValidation
<uuid>The UUID of the profile to updateRequired parameter
Example request
curl -v -X PATCH \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    --data '{
    "username": "bobby.builder",
    "firstname": "Bobby",
    "data": {
        "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"
                }
            ]
        },
        "genericValues": {
            "EmailPersonal": "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 genericValues from a profile, please include the fieldname but set the field content to empty or null.

Delete traveler profile

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

Delete a single traveler profile from Faces as well as all downline systems.

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

This API is currently under development and not yet generally available

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 methodGET

Fetch plaintext credit card data from a company or traveler profile.

Parameters
NameDescriptionValidation
uuidOwning (company / traveler) profile UUIDRequired 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 methodPOST

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>" \
    --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>" \
    --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
  • No labels