Versions Compared

Old Version 6

changes.mady.by.user Remo Räber

Saved on

compared with

New Version 7

changes.mady.by.user Remo Räber

Saved on

Key

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

...

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

...

Code Block
languagebash
titleExample 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"
Code Block
languagejs
titleExample response
collapsetrue
{
	"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": {}
	}
} 

...

 

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
Code Block
curl -v -X PATCH \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    --data '{
    "externalNr": "0815",
    "name": "ACME Incorporated",
    "shortname": "ACME-INC”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
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)

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

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

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.
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
Code Block
languagebash
titleExample 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"
Code Block
languagejs
titleExample 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)

Create new traveler profile

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

Create a new traveler profile

 

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