My Account
These APIs cover a users 'profile'.
Linked/Unlinked accounts
When a account is first registered with Riviera Travel, it does not contain any profile data, and so will not show any bookings. In order to make sure that the account shows the correct bookings we ask that the user submit some basic data so we can attempt to match it to our existing records. This MUST be done before it is possible to retrieve any data from our API.
If an account is in the 'unlinked' state, then GET /api/myDetails will return a 404 response. If an account is correctly 'linked', then GET /api/myDetails will return a 200 response, with the associated profile data.
If an account is in the 'unlinked' state, then a POST to /api/myDetails/linkClient will attempt to locate the user. If they are not found, a new profile record will be created. If an account is already 'linked', then a POST to /api/myDetails/linkClient will return a 409 conflict response.
Fetching Data
A GET request to /api/myDetails will return the current users profile record. This will include all basic details such as Name(s), Postal Address and phone numbers, as well as information about the users account.
Whilst there are no strict requirements around which fields are displayed, it is recommended that the following should be included in any user interface exposing a users profile details.
| JSON path | Required on Update | Details |
|---|---|---|
| .title | Yes | |
| .forename | Yes | |
| .middleName | No | |
| .surname | Yes | |
| .account.username | No | This is the currently signed in username. This cannot be updated |
| .home | No | At least one phone number should be exposed, and any phone numbers must be correctly labeled |
| .mobile | No | |
| .office | No | |
| .address.line1 | Yes | |
| .address.line2 | No | |
| .address.city | Yes | |
| .address.state | Yes | |
| .address.zip | Yes | |
| .address.countryCode | Yes | Use the ISO 3166 defined country code when updating |
| .address.countryName | No | Use .address.countryName for display only |
Email addresses
It should be noted that the /api/myDetails response contains 2 email addresses.
| JSON path | Details |
|---|---|
| .account.username | This is the username used to log into the account. This is where any account related emails (i.e. password reset, or notification) will be sent. |
| This is the main contact email address, and is where any non-account related emails (i.e. booking documentation, or client correspondence) will be sent. |
Note: Whilst it should not happen, it is possible for the account email address (abridgedClient.account.username) and the profile email (abridgedClient.email) to get out of sync.
It is strongly recommended that when displaying, or using an email address, the above details are taken into account, and the correct email address show to the user.
Updating Data
Most fields of the users profile can be updated, however there are some exceptions which are detailed below.
| JSON path | Details |
|---|---|
| .id | This is an internal unique identifier. It cannot be updated by the user. Note it is not imutable, and over time can change if multiple back office records are merged into a single record. |
| .displayName | This is a calculated field, intended to allow for consistent formatting of the users name across multiple system. |
| .typeId | This is an internal ID, but can be used to differentiate the type of user. i.e. 'Direct' consumers (typeId 200) or 'Agent' (typeId 205). |
| .typeName | This is a human readable display version of the typeId. |
| .statusId | This is an internal ID. There should be no reason to use this. |
| .statusName | This is a human readable display version of the statusId. |
| .companyId | This is an internal ID. It shows which 'Company' the record belongs to. |
| .companyName | This is a human readable display version of the companyId. |
| .created | This is the ISO 8601 formatted datetime the profile record was created. it cannot be updated. |
| .updated | This is the ISO 8601 formatted datetime the profile record was last updated. it is reset on any update operation. |
| This currently read only. to change this users must call Riviera Travel by phone. | |
| .account | The account object is read-only. It is included for convenience only. |
| .lastEnquiryDate | This is the ISO 8601 formatted datetime of the last interaction with the user. |
Mapping to Legacy APIs
When using Riviera Travel's Legacy APIs which are not fully integrated into this RESTfull suite, please use the following mapping data.
| myDetailsGet | BrochureRequest | Booking4 (Customer) | Booking4 (Passenger) | Comments |
|---|---|---|---|---|
| .title | .msg.BrochureRequest.ClientDetails.Title | .msg.Booking4.Customer.Title | Passengers.Title | |
| .forename | .msg.BrochureRequest.ClientDetails.FirstName | .msg.Booking4.Customer.FirstName | Passengers.FirstName | |
| .middleName | .msg.Booking4.Customer.MiddleName | Passengers.MiddleName | BrochureRequest does not support Middle Name | |
| .surname | .msg.BrochureRequest.ClientDetails.LastName | .msg.Booking4.Customer.LastName | Passengers.LastName | |
| .dob | Passengers.DOB | The Profile Date of birth may not have been populated, and so the user must be prompted if it is missing | ||
| .msg.BrochureRequest.ContactDetails.Email | .msg.Booking4.Customer.EmailAddress | |||
| .home | .msg.BrochureRequest.AddressDetails.HomeTel | .msg.Booking4.Customer.TelephoneHome | ||
| .mobile | .msg.BrochureRequest.AddressDetails.MobileTel | Booking4 does not support Mobile phone number | ||
| .office | .msg.Booking4.Customer.TelephoneDay | BrochureRequest does not support the office phone number | ||
| .address.line1 | .msg.BrochureRequest.AddressDetails.Address1 | .msg.Booking4.Customer.Address1 | ||
| .address.line2 | .msg.BrochureRequest.AddressDetails.Address2 | .msg.Booking4.Customer.Address2 | ||
| .address.line3 | .msg.BrochureRequest.AddressDetails.Address3 | .msg.Booking4.Customer.Address3 | ||
| .address.city | .msg.BrochureRequest.AddressDetails.City | |||
| .address.state | .msg.BrochureRequest.AddressDetails.State | .msg.Booking4.Customer.State | ||
| .address.zip | .msg.BrochureRequest.AddressDetails.Postcode | .msg.Booking4.Customer.PostCode | ||
| .msg.BrochureRequest.AddressDetails.CountryCode | .msg.Booking4.Customer.CountryCode | Both BrochureRequest & Booking4 use non-standard codes (UK, IE, AUS, USA) which cannot be mapped from a logged in users profile |
Notes
- All APIs require an authenticated user.
- All datetimes are serialized in ISO 8601 format, UTC timezone ( 2019-02-01T03:45:27+00:00 ) unless otherwise noted.
- When updating an item (via a PUT or POST),
- the response will be the new state of the item. There is no need to perform a new GET request.
- updates to Read Only properties will be ignored.
- all properties MUST be included from the original GET request, or else properties could be deleted from the object
Multiple Companies
A single user can authenticate to each of the different Company configurations (see AccountManagement), however they will have a separate profile, list of bookings or each Company.