ExUsing 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.
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 ----todo OauthScopes --- |
| Desired OAuth Flow(s) | One or more OAuth flows, see ....todo OAuthFlows... 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:
| Scope | Description |
|---|---|
| api.profilesondemand.read | |
| api.profilesondemand.write | |
| openid | |
| agencyid | |
| profile |
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:
| Type | Description | Restrictions |
|---|---|---|
| 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) |
| Implicit | Similar to the Authorization Code flow, with the difference that no refresh-token will be issued and thus only temporary access of maximum one hour is possible before re-confirmation is needed. | Same as for Authorization Code. |
| Client Credentials | 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. |
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
TODO
ID token
TODO
Profiles API
Search company profile
| Scope | api.profilesondemand.read |
|---|---|
| Endpoint | api/v1/profiles/companies |
| TODO |
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:
|
Example Request
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
TODO