...
The interface is part of our standard web service offering and can be found in our swagger.yml documentation.
Table of Contents exclude (Example response)|(Parameters)
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:
Field | Description |
---|---|
Application Name | Application name, which will be shown to the user |
Application Purpose | Short description of what the application wants to achieve using the Oauth2 enabled APIs |
Desired OAuth Scopes | OAuth Scopes requested by the application see Available OAuth Data-Scopes |
Desired OAuth Flow(s) | One or more OAuth flows, see Supported OAuth2 Flows By default you will be granted access to the Authorization Code flow, which requires user interaction to authorize your application, however depending on your applications purpose it may be possible to setup a different flow (For example to allow unlimited access to all profiles belonging to your own travel agency in case you’re implementing an in-house application) |
...
Certification will be achieved by demonstrating the product accessing Faces using Oauth
Anchor OAuthScopes OAuthScopes
Available OAuth Data-Scopes
OAuthScopes | |
OAuthScopes |
Your application will be granted some or all of the following OAuth scopes for data access:
Scope | Description |
---|---|
api.profilesondemand.read | Access to the Profiles API (read only) |
api.profilesondemand.write | Access to the Profiles API (write) |
openid | Required scope when requesting an ID-Token for “Login using Faces” functionality |
agencyid | Optional scope to be included in and ID-Token. Please see the section Usage of an ID token within this document. |
Optional scope to be included in and ID-Token. Please see the section Usage of an ID token within this document. | |
profile | Optional scope to be included in and ID-Token. Please see the section Usage of an ID token within this document. |
Please let our friendly support-staff know which scopes you’ll be requiring in order to provide which desired functionality.
Anchor OAuthFlows OAuthFlows
Supported OAuth2 Flows
OAuthFlows | |
OAuthFlows |
Faces supports multiple Oauth2 grant flows, depending on the individual requirements of the client application. The following table lists possible flows:
...
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
...
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:
...
Code Block | ||
---|---|---|
| ||
{ "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:
...
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:
...
As a result, a new access token will be issued.
Anchor IDToken IDToken
ID token
IDToken | |
IDToken |
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.
...
Code Block | ||||
---|---|---|---|---|
| ||||
{ "access_token": "f88a7119-b585-4c9c-9867-88a40aae41f8", "token_type": "bearer", "refresh_token": "bab32afe-acf8-4a8e-ba7c-ed567daa0ee4", "expires_in": 3599, "scope": "email openid profile", "id_token": "eyJhbGciOiJSUzI1NiJ9.eyJvcGVuaWQiOiIzZDkyMDVjYS1mMjY0LTRhZDgtYjFhYy1lNjQ1NTU3ZWFhOTkiLCJwcm9maWxlIjp7ImZpcnN0bmFtZSI6IlJlbW8iLCJwaG9uZSI6Iis0MTQ0MTIzNDU2NyIsImRpc3BsYXluYW1lIjoiSGVyciBSZW1vIFLDpGJlciIsIm5hbWUiOiJSw6RiZXIifSwiZW1haWwiOiJyZW1vLnRlc3RAdW1icmVsbGEuY2gifQ.ni2_4eszvqV5JgWBzJNmQ8jq225_7i-TiMAFzSGDSkPt6J5CTPSQF5wsq_Og5tOzd39nybGfwRzDyAkAOWinU2_djUv58gMx095U77ccSlSVYca6sn8t8WL62v8AOPSO9h8ok52nQpjtZFWcni4KABlcCKd_feT_5KjAmsRQwf7NZ0gqkoP3Y4Ymo454N8ezu822slF-ub4UdA1VBHDZuCJtQWbdsT2Cfep1NWRf3by_uP2s6yxHcHmQ0R_kYwXKMW2SbxyGo821cN-sxXYmppb4ipDtPKC7ANUYc5wZQ2Gp0gAenMIfxooz0njkEWKKMq3pwZWNJnWHDwVsluqI_w" } |
Decoded ID-Token
The following extract depicts a decoded ID-Token from the value of "id_token" in the response above
Code Block | ||
---|---|---|
| ||
{ "openid": "3d9205ca-f264-4ad8-b1ac-e645557eaa99", "profile": { "firstname": "Remo", "phone": "+41441234567", "displayname": "Herr Remo Räber", "name": "Räber" }, "email": "remo.test@umbrella.ch" } |
Anchor ProfilesAPI ProfilesAPI
Profiles API
ProfilesAPI | |
ProfilesAPI |
Search company profile
Scope | api.profilesondemand.read |
---|---|
Endpoint | api/v1/profiles/companies |
Request method | GET |
Allows searching through a paged list of company profiles. This API can be used to narrow-down the traveler profile search by company.
Parameters
Name | Description | Validation |
---|---|---|
q | Freetext query for finding matching profiles | Required parameter |
page | Current page within the result set, starts at 0 | Optional, number >= 0 |
pageSize | Maximum number of results per page. Default 10 | Optional, number > 0 and <= 100 |
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 following sections are currently supported:
|
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "moreResults": false, "results": [{ "uuid": "b9321d7e-9d72-4e80-ac49-d3aa38169175", "name": "ACME Inc." }] } |
Anchor GetCompanyProfile GetCompanyProfile
Get company profile
GetCompanyProfile | |
GetCompanyProfile |
Scope | api.profilesondemand.read |
---|---|
Endpoint | api/v1/profiles/company/<uuid> |
Request method | GET |
Retrieves the details of a single company profile.
Parameters
Name | Description | Validation |
---|---|---|
<uuid> | The UUID of the profile to retrieve | Required parameter |
sections | Areas of the profile to be returned. 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 |
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "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:
Name | Contents |
---|---|
AGNCY_INFO | Agency information:
|
CONTACT_DATA | Company contact data:
|
MEMBERSHIPS | Corporate alliance Memberships
|
GENERIC_VALUES | 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. |
Create new company profile
Scope | api.profilesondemand.write |
---|---|
Endpoint | api/v1/profiles/company |
Request method | POST |
...
Code Block | ||
---|---|---|
| ||
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:
...
Faces will apply default validation logic as seen on our Web UI and CSV interfaces and will report validation errors to the caller without saving the profile.
Update existing company profile
Scope | api.profilesondemand.write |
---|---|
Endpoint | api/v1/profiles/company/<uuid> |
Request method | PATCH |
Updates (part of) the details of a single company profile.
Parameters
Name | Description | Validation |
---|---|---|
<uuid> | The UUID of the profile to update | Required parameter |
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 genericValues from a profile, please include the fieldname but set the field content to empty or null.
Delete company profile
Scope | api.profilesondemand.write |
---|---|
Endpoint | api/v1/profiles/company/<uuid> |
Request method | DELETE |
Delete a single company profile (along with all associated traveler profiles) from Faces as well as all downline systems.
Parameters
Name | Description | Validation |
---|---|---|
<uuid> | The UUID of the profile to delete | Required parameter |
Code Block |
---|
curl -v -X DELETE \ -H "Authorization: Bearer <token>" \ https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/company/b9321d7e-9d72-4e80-ac49-d3aa38169175 |
Example response
HTTP 204 “No Content” with empty body
Search traveler profile
Scope | api.profilesondemand.read |
---|---|
Endpoint | api/v1/profiles/travellers |
Request method | GET |
Parameters
Name | Description | Validation |
---|---|---|
q | Freetext query for finding matching profiles | Required parameter |
page | Current page within the result set, starts at 0 | Optional, number >= 0 |
pageSize | Maximum number of results per page. Default 10 | Optional, number > 0 and <= 100 |
c | Narrow down the search for travelers attached to a specific company profile | Optional, company UUID |
scope | Search scope | Optional, may be one of:
|
p | Search scope parameter | Required if scope=GENERIC_FIELD: Name of the generic field to search in Optional for scope=RECORD_LOCATOR: System type or Label (e.g. “CSX”, “GALILEO_WS”, “My HR-System”) Optional for scope=PAPER: Type of paper to search for, PASSPORT, ID_CARD or VISA Prohibited otherwise |
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 following sections are currently supported:
|
Code Block | ||||
---|---|---|---|---|
| ||||
curl -v -H "Authorization: Bearer <token>" \ "https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/travellers?q=bob&page=0&pageSize=10" |
Code Block | ||||
---|---|---|---|---|
| ||||
{ "moreResults": false, "results": [{ "uuid": "065fe9e0-47b7-4d12-b3de-d3aa38169175", "fullName": "Herr Bob Builder" }] } |
Anchor | ||||
---|---|---|---|---|
|
Scope | api.profilesondemand.read |
---|---|
Endpoint | api/v1/profiles/traveller/<uuid> |
Request method | GET |
Parameters
Name | Description | Validation |
---|---|---|
<uuid> | The UUID of the profile to retrieve | Required 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 |
Code Block | ||||
---|---|---|---|---|
| ||||
curl -v -H "Authorization: Bearer <token>" \ "https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/traveller/065fe9e0-47b7-4d12-b3de-d3aa38169175?sections=GENERIC_VALUES§ions=COMPANY_INFO§ions=MEMBERSHIPS" |
Code Block | ||||
---|---|---|---|---|
| ||||
{ "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:
Name | Contents |
---|---|
COMPANY_INFO | Information on the associated company:
|
COMPANY_CONTACT_DATA | Contact information of the associated company:
|
GENERAL_DATA | General profile information:
|
GENERIC_VALUES | 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. |
MEMBERSHIPS | Flight, Hotel and Rentalcar-Memberships, each with alliance-code and membernumber |
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:
|
ROLES | Roles as show in Faces UI with the respective checkboxes (true/false):
|
PREFERENCES | Preferences:
|
Create new traveler profile
Scope | api.profilesondemand.write |
---|---|
Endpoint | api/v1/profiles/traveller |
Request method | POST |
Create a new traveler profile
...
Code Block | ||||
---|---|---|---|---|
| ||||
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:
...
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
Scope | api.profilesondemand.write |
---|---|
Endpoint | api/v1/profiles/traveller/<uuid> |
Request method | PATCH |
Updates (part of) the details of a single traveler profile.
Parameters
Name | Description | Validation |
---|---|---|
<uuid> | The UUID of the profile to update | Required parameter |
Code Block | ||||
---|---|---|---|---|
| ||||
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.
...
In order to remove genericValues from a profile, please include the fieldname but set the field content to empty or null.
Delete traveler profile
Scope | api.profilesondemand.write |
---|---|
Endpoint | api/v1/profiles/traveller/<uuid> |
Request method | DELETE |
Delete a single traveler profile from Faces as well as all downline systems.
Parameters
Name | Description | Validation |
---|---|---|
<uuid> | The UUID of the profile to delete | Required parameter |
Code Block |
---|
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