This section contains all the key information you need to know while using the REST API. You can find here how filtering, pagination, and sorting can be used but also how date fields, and header parameters work. It includes a list of all the error codes you can come across while using our API.

Besides this, we have created some flows on the most used scenarios. These flows define step by step how you can create a booking module or use the events from the REST API.

There is also a webhook available to push information to your system instead of using the REST API to pull information.

Host :

• Test/Acceptance: https://api-test.maxxton.net
• Production/Staging: https://api.maxxton.net

BasePath : /maxxton/v2 Schemes : HTTPS

Maxxton External APIs are secure RESTful web services and authentication(OAuth2) is required to access them, user will be authenticated based on the token passed in the request.

Generate access token

POST /maxxton/v2/authenticate

 
curl --location ‘https://api.maxxton.net/maxxton/v2/authenticate’ --header ‘Content-Type: application/x-www-form-urlencoded’ --header ‘locale: nl_NL’ --data-urlencode ‘grantType={grant type}’ --data-urlencode ‘clientId={client id}’ --data-urlencode ‘clientSecret={client secret}’ --data-urlencode ‘scope={concern code}’

Request body(x-www-form-urlencoded)

The responses that can be returned are:

Responses

After generating the token, the access token can be used by adding it to the header parameters with key: Authorization and value: {token_type} {access_token}

• The clientId and the clientSecret will be provided by Maxxton/Maxxton client as part of API credentials.
• Please contact the particular Maxxton client to request API credentials to access their Maxxton environment and data.
• Scope can be used for passing the concern parameter but scope is preferred as it is fully oauth2 compatible.

For more information: Login

The API costs are based on the number of requests per month, the first 750,000 requests per month(25,000 requests per day) are not charged. Subsequent requests are charged as per the API price calculator. The processes can be speeded up by making multiple API requests at the same time, this is called concurrent calls in the model. Concurrent calls have a bigger impact on the Maxxton API resources, therefore extra costs are charged.

Pricing-slider

Notes applicable to the API Pricing

• The number of concurrent calls is limited to the maximum number per IP, by default this is 15.
• The number of concurrent calls will be used as a logarithmic parameter in the pay-per-use model and will impact the charges on actual usage.
• The number of requests is not limited and will be charged based on actual usage.
• Costs only apply to the new Maxxton REST API.
• The number of requests only applies to the production API (api.maxxton.net).
• The acceptance (api-test.maxxton.net) API can be used free of charge, subject to adherence to the fair use policy.
• Fair use policy applies to both production and acceptance API.
• API Support is included for daily support questions
• Development of new features and project guidance/management are charged per hour.
• Clients can request new features to decrease the REST API usage. Maxxton will, commercially reasonable, develop new features on request to decrease API usage.

Fair Use Policy

On our API we do not have a fixed restriction on the number of API calls. However, a Fair Use Policy applies to the usage of the API.

Normal usage is permitted. Excessive usage is not permitted. Excessive usage means, the usage which has an impact on our server performance or impact on other customers who use the API.

Many calls contain filtering, this is a way to filter the output of the calls. In the REST documentation, it says filter parameter where this can be used. filtering means you can filter on any non-nested field in the output with the following features:

These are the operators you can use in the filtering of the filter:

Note: The above operators need to be encoded to work in some cases.

Pagination is used to divide large response into small response which leads minimizing the response time. General concept is separating a large page into small pages. Most of the Maxxton External API endpoints follow pagination. You can control the number of results returned in a single request by specifying the page number and page size. Page and Size are 2 request parameters that can be used with request to control pagination.

With every response, there are few parameters in response that gives information about the pagination followed in request.

Sorting is used to order the response based on the values of a particular field of the response. General concept is fetching a page/list of response in the ascending or descending order of the specified field. Sorting is possible in all the endpoints where pagination is supported.

This can be done by specifying the sort request parameter with the field name and order of descending, as follows: sort=fieldname,desc or sort=fieldname,asc

With every sorted response, there are few parameters under the section sort at the end of page that gives information about the sorting followed in request.

Following is the description of different date fields used in various domains of API endpoints.

Header parameters contain important meta-data related to the API request and response. These parameters can be used with Maxxton APIs to customize the behavior of the request and response. Below are the header parameters you can use:

Swagger enables the import of all endpoints into your preferred API tool based on the Open API specification, allowing for a comprehensive overview and streamlined integration. Additionally, the Swagger documentation provides a complete list of available endpoints.

Url: The Swagger UI Rest client

Location, Accommodation Type, Unit

Location: A location is a group of accommodation types at the same location which provides an array of accommodation types typically including entertainment and recreational activities. A location may contain one or multiple accommodation types.

Accommodation Type: An accommodation type is a group of similar units, where units are configured to define the type (Room, Bungalow, Chalet, etc.) and other configurations (Representation, Capacity, Cashflow, Rentability, Reservability, Amenities, etc.). An accommodation type may contain one or multiple units.

Unit: A unit is a room, group of rooms, or bungalow in which someone may live or stay. It can be a single room, bungalow, chalet, etc.

Diagrammatic representation of Location, Accommodation types, and Units:

Resources and Reserved Resources

In the Maxxton system, resources (items) are available in multiple types such as Accommodation type, add-on, or offers. These resources can be booked when creating a reservation, where a reserved resource is added to the reservation as a booked version of the actual resource. A resource is unique in the system and used across multiple reservations, while a reserved resource is unique to the reservation.

Diagrammatic representation of Resources and Reserved resources:

The Flows section provides a detailed breakdown of the most common integration processes for the REST API, offering step-by-step guidance on how to seamlessly incorporate API functionalities into your project. Users can gain a comprehensive understanding of the most common integration scenarios, enabling them to efficiently navigate and implement API interactions within their applications.

Introduction

The webhook solution is integrated into Maxxton Software's Integration Manager and will push data when certain configured data changes are triggered. Unlike the REST API, webhooks cannot be polled but will push data to the subscribed endpoint. Maxxton’s webhook implementation follows standard webhook guidelines. The data structures used are the same as those for the REST API, meaning the REST API documentation applies, and any adjustments made to the REST API will also apply to the webhooks.

Concept

There are three main concepts in the Maxxton webhook system:

1. Context: High-level entities in the Maxxton system, such as reservations, determine the context for the events and data that can be configured in the webhook request.
2. Events: Events that trigger the webhook (e.g., a change in reservation status).
3. Data: The actual data structure (fields) that are included in the webhook request.

How the Webhook Works

1. You configure your webhook in the Maxxton Software Integration Manager.
2. Once enabled, if any of the entities/data configured as a trigger is changed (i.e., there is new, changed, or removed data in the respective entity), the webhook will be triggered.
3. The webhook engine is triggered, and if the change meets the configured events, it will initiate a request.
4. For every change, the relevant data is fetched from the REST API. After that, the webhook container, which includes all the data, is created.
5. Optionally, the receiving endpoints may have authentication. If authentication is configured, the request will include authentication details or request a valid token first.
6. The webhook container, including all the data, is then pushed to the external URL configured in the webhook.
7. The receiving system (the webhook subscriber) can then process the data further.

Request Structure

Every webhook request will have the following structure:

 
{
    "notificationId": "2342040", // unique id of the webhook request
    "webhookId": 1, // unique id of the configured webhook
    "webhookName": "Maxxton test service", // webhook name as configured in Maxxton software integration manager
    "eventOccurred": "2024-07-31T08:39:44.709527Z", // date and time when the event occurred
    "sentDate": "2024-07-31T08:39:46.203144Z", // the date and time when the webhook request was sent out to push the event
    "type": "reservation.status.changed", // type of event to identify what event triggered the webhook
    "data": { // data structure as configured for this webhook
        ...
    }
}

Available Context & Events

Events are organized by context and type. The context determines the available events and data for the webhook request. The specific event that triggered the webhook request can be identified by the “type” field in the webhook request. The following contexts and events are currently supported:

Reservations

• Status Change (type: reservation.status_change): The status of the reservation changed (e.g., provisional, definitive, or canceled).
• Stay Period Change (type: reservation.stay_period_change): The arrival and/or departure date of the reservation changed.
• Bill Change (type: reservation.bill_change): There was a change to the total bill amount for the customer, paying customer, or agent.
• Payment Received (type: reservation.payment_received): Triggered when a payment is received.
• Refund Given (type: reservation.refund_given): Triggered when a refund is issued.

Available Data

The data available depends on the selected context. All data is populated through the REST API, and the data structure is the same as that of the REST API. For specific field and entity descriptions, please refer to the REST API documentation.

Example Data for Webhooks

Security

Authentication

The endpoint used to send the webhook requests can optionally require authentication. The following authentication types are supported:

• Basic Authentication:plaintextCopy codeAuthorization: Basic {credentials}
• OAuth 2.0 (Client Credential Grant):plaintextCopy codeAuthorization: Bearer {token}
• No Authentication: The endpoint is freely accessible from the internet or has IP whitelisting applied.

Sender Validation

The receiving party can use a webhook secret to verify that the delivered message is from Maxxton. During webhook setup, the user can provide a secret token, which must be stored securely on their server. Each incoming webhook payload must be validated against the token.

Maxxton will use HMAC-SHA256 (Hash-based Message Authentication Code) to generate a hash signature. The signature is generated using the payload content and the provided webhook secret. The signature is sent in the webhook-signature HTTP header.

Example:

 
codewebhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

Access & Usage

Webhooks can be configured through the Maxxton Software Integration Manager under the Webhooks tab. Access to this module is required to set up new webhooks or view statistics. Please note that Maxxton does not grant access to this module; it is managed by our clients, who are responsible for configuring the webhooks.

To receive requests, you do not need access to Maxxton software.

API Pricing and Fair Use Policies apply to the usage of webhooks.

Support

If you have questions, please contact the party who configured the webhooks for you (usually the Maxxton client). In case of technical queries, a ticket can be created in the Maxxton ticket system or an email can be sent to api@maxxton.com.

In case of questions, feedback, or issues you can contact the Maxxton API support by creating a ticket through the Maxxton ticket system (you need an account for this) or reach out to our support team by using the email address below:

Contact Email: api@maxxton.com

Ticket system: https://support.maxxton.com