Common elements

The API has a number of elements that are common to all API endpoints.


Request format

An example API call URL is shown below. The API call is to an API called ‘TestRequest’, which is in API group ‘System’.

URL Part Description The registered domain of the customer.
/API/V40/ The version of the API that the customer is using.
System An API group. All API calls referring to the same topic will be grouped together to make it easier to find and manage.
Session The API Topic
TestRequest The name of the API call to be invoked.
sessionToken The session token is an encoded identity context that allows the API to operate in a stateless manner. It is obtained at the beginning of the session and needs to be passed with every API call.


Response format

In the new API, calls will be responded to with messages that are designed to be composed of multiple parts (composite messages). An example is shown below.
    "responsesIncluded": "TestResponse", 
    "responses": [
            "TestResponse": {
                "content": { 
                    "Name": "John Smith", 
                    "Age": 21, 
                    "Registered": "2013-02-05T12:35:21.3286245+01:00" 
            "succeeded": true, 
        } ],
    "status": Success, 
    "errorCode": None 
Property Description
sessionToken The session token is also returned as part of every response message and should be updated at the called end with newer versions, as it may be modified during API usage.
responsesIncluded The responses included contains a list of the actual messages contained in the composite message, for easier filtering. Be aware, that sometimes this list can contain messages that were not requested, if the API needs to update the caller with additional information.
responses This block contains a list of the actual response messaged. These can vary depending on the API that was called.
succeeded A simple true/false indicator to show if the response succeeded.
errorCode (message level) A generic indicator for any error that may have occurred during response execution.
  • None
  • Unauthorized
  • Error
This is not intended to be an exhaustive list, but will contain any event that effects the operational flow (for example, needing to log in).
areaErrorCode A more detailed error code that is specific to the response.
Status An indicator of the composite message state.
  • Success
  • Mixed
  • Failure

HTTP Response Codes

Status HTTP Status Code Description
Success 200 OK

Basic success code. Works for the general cases.

Especially used on successful first GET requests or PUT/PATCH updated content.

201 Created Indicates that a resource was created. Typically responding to PUT and POST requests.
202 Accepted

Indicates that the request has been accepted for processing.

Typically responding to an asynchronous processing call (for a better UX and good performances).

204 No Content The request succeeded but there is nothing to show. Usually sent after a successful DELETE.
206 Partial Content The returned resource is incomplete. Typically used with paginated resources.
Client Error 400 Bad Request

General error for a request that cannot be processed.

GET /bookings?paid=true

400 Bad Request

{"error":"invalid_request", "errorDescription":"There is no ‘paid’ property"}

401 Unauthorized

I do not know you, tell me who you are and I will check your permissions.

GET /bookings/42

401 Unauthorized

{"error”:"no_credentials", "errorDescription":"You must be authenticated"}

403 Forbidden

Your rights are not sufficient to access this resource.

GET /bookings/42

403 Forbidden

{"error":"protected_resource", "error_description":"You need sufficient rights"}

404 Not Found

The resource you are requesting does not exist.

GET /hotels/999999

404 Not Found

{"error":"not_found", "error_description": "The hotel ‘999999’ does not exist"}

405 Method Not Allowed

Either the method is not supported or relevant on this resource or the user does not have the permission.

PUT /hotels/999999

405 Method Not Allowed

{"error":”not_implemented", "error_description":"Hotel creation not implemented"}

406 Not Acceptable

There is nothing to send that matches the Accept-* headers.

For example, you requested a resource in XML but it is only available in JSON.

GET /hotels

Accept-Language: cn

406 Not Acceptable

{"error": "not_acceptable", "error_description":"Available languages: en, fr"}

Server Error 500 Internal Server Error

The request seems right, but a problem occurred on the server. The client cannot do anything about that.

GET /users

500 Internal server error

{"error":"server_error", "error_description":"Oops! Something went wrong…"}

Response Types

Success All of the elements of a composite message have been processed successfully
Mixed Part of the elements of a composite message have been processed successfully
Failure The composite message could not be processed or all elements of the composite message failed.

Response error codes


HTTP Header – Cache Control

On all GET calls, a Cache-Control header is included.


API interface token

The API interface token is a token generated by the customer, using the Manager application that permits the customer to use the API. Without this token none of the API calls will work and as such this token must be passed as one of the first initialisation calls.

Initialise Session

The API v4 has one mandatory call to initialise a session called InitialiseSession. This call uses an application token configured in GXP v4 and links the session to a property, also configured in GXP v4.

To link the session to a property the caller has two options to set the property code:

  • Hotel property identifier. The format of this is for example, H9999.
  • Use the numeric value of the hotel property identifier. The format is 9999.

The initialise session will return a sessionToken if the property has been identified correctly. The sessionToken needs to be sent with every call and will be returned with every call. The sessionToken contains context about the session such as language, content version, user identification.

After successful initialisation the application can utilise all calls in the unauthorised part of the API.

Identity context

The identity context is established on the initialisation of a session. However, during the session some calls modify the identity context depending on authorisation, content version language, etc. At this point the API takes the following information in the identity context:

Element Description
group_code The group_code is set from the API Token and links the session to a particular group
property_code The property_code links the session to a particular property
guest_id The identification of the guest after being authorised.
cms_content_version The version of the content that is retrieved from the CMS.
language_code The language selected by the guest.


The GXP API v4 has two calls for managing languages used in the application:

  • Settings/Languages
    This call gets all languages that have been configured for the property
  • Session/Language
    This call will set the language for the application user and stores this in the sessionToken.

If no language has been set, the API will deliver content in the default language that was configured in GXP v4.