Maxihost Developer Hub

Welcome to Maxihost's Developer Hub. Here you'll find comprehensive guides and documentation to help you start working with Maxihost as quickly as possible, as well as support if yo u get stuck. Let's jump right in!


Welcome to our API documentation! You can view code examples in the area to the right.

For more information about Maxihost products, you can visit our product documentation.

Suggest Edits

API Summary


JSON is returned in all responses.

The API also uses common approaches for the following:



API data is JSON encoded with UTF-8. API JSON is either a single object or a list of objects.


Access control using API Access Tokens.


4xx and 5xx responses returning JSON with error codes


Methods are used in accordance with HTTP (GET POST and DELETE are the primary methods used) and resources are identified using URIs. All API requests are sent over HTTPS.

Suggest Edits

Access Tokens


You'll need an Access Token if you want to use the API to access your own Maxihost data – for example, if you use the API with your own scripts to get data from your Maxihost account.

Setting up Access Tokens

Access Tokens should never be shared outside of your company

Access Tokens allow access to your private customer data in Maxihost. They should not be shared outside of your company. We cannot stress enough how important it is for you not to share your Token with anyone.

Creating your Access Token is simple and you can get a Token instantly.

To create your Access Token, go to the API page on the dashboard by clicking here or by clicking on API on the main menu.

Using your Access Token

Once you have created your Access Token you will see it in the same section of your Dashboard. You can edit or delete the token from here.

You can copy your token and use it in much the same way as you would use an API Key. The specifics will depend on how you are integrating with Maxihost.

To use your Access Token simply provide it as part of the authorization header when you make a request. Access Tokens use the bearer authorization header when you make a request. This just means you need to specify the bearer type in the header.

For more info on the bearer token framework please see the official spec.

$ curl \
-s \
-H "Authorization: Bearer <access_token>" \
-H 'Accept:application/json'
Suggest Edits



In order to use version 1.1, all you have to do is send the following header on your request:

Accept: application/vnd.maxihost.v1.1+json

Suggest Edits

Error Objects


The API will return an Error List for a failed request, which will contain one or more Error objects.

Error List Attributes

Each error has the following attributes



The status is false


General context about the error. See Error Codes.


An array of one or more error objects.

Error Object Attributes

Each Error Object has the following attributes



Human readable description of the error

Error List Object

  "status": "error.list",
  "errors": [
      "code": "not_found",
      "message": "No such user_id[494817923]",
      "field": "user_id"
      "code": "not_found",
      "message": "No such email[john@doe.acme]",
      "field": "email"
Suggest Edits

Error Codes


The API may send the following error codes. Other codes may be added in the future.



Generic server error


Timeout error


The request was not authorized. Check your token.


The request was forbidden. Check your token.


The credentials are invalid. Check your data.


Cannot process the request. Check your data.


The token is invalid. Request a new token.


The token is revoked. Request a new token.


The token is missing. Check your token.


The token is expired. Request a new token.


Failure to log in. Check your credentials.


Your payload is wrong. Check your data.


Cannot update the primary user. Select another user to update.


<ITEM> not found. Check your data.


Failure updating a contact. Check your data.


Generic error when the subject is not found


Failure updating the subject. Check your data.


Failure listing available <ITEM>. Try again later.


Failure updating <ITEM>. Try again later.


Failure creating <ITEM>. Try again later.

Suggest Edits

HTTP Responses


The API returns HTTP responses on each request to indicate the success or otherwise of API requests. The codes listed below are often used, and the API may use others. Note that 4xx and 5xx responses may be returned for any request and clients should cater for them.

Response Code


Ok -- The request was successful.


Created -- The request was successful.


Bad Request -- General client error, possibly malformed data.


Unauthorized -- The API Key was not authorised (or no API Key was found).


Forbidden -- The request is not allowed.


Not Found -- The resource was not found.


Unprocessable Entity -- The data was well-formed but invalid.


Too Many Requests -- The client has reached or exceeded a rate limit, or the server is overloaded.


Server errors - something went wrong with Maxihost's servers.

This response is most likely a momentary operational error (e.g. temporary unavailability), and, as a result, requests should be retried once.

Suggest Edits

Object Model


Commond Fields

API objects have a type field indicating their object type. Each object in the API may be given an identifier, indicated via its id field, and will typically be addressable via a URI. Many objects will also have a created field indicating the object's creation date as a UTC Unix timestamp.

Dates and Timestamps

All temporal fields in the API are encoded as Unix timestamps and are by definition always treated as UTC. The most common time fields in the API are created and updated.



The time the object was created. In most, but not all cases, this is the time the object was created according to the API server.


The time the object was last updated according to the API server.

Optional Fields

Unpopulated optional data is returned as follows

  • Number, String, and Boolean types may be returned as having null values.
  • Arrays and Objects may be returned as empty ([] {})

In general clients should be able to handle null and empty fields.

Metadata and Custom Attributes

Some object types, such as Devices, have a metadata field that allows clients to set custom-defined data about an object.


Data is encoded as defined by JSON in RFC4627. The default encoding for APIs is UTF-8. Certain characters, such as Emoji may be handled as surrogate unicode pairs (see section '2.5. Strings' of RFC4627).

Some query parameters may need to be url encoded when sending - for example, the email parameter value used to query users should be encoded.

HTML Encoding

It should be noted that the following identifiers are encoded to protect from potential cross-site scripting attacks: 'name', 'user_id', 'company_id' and 'email'. As a result you may see these identifiers in their encoded format when you retrieve them via the API.
Note that the characters we encode are double quote, single quote, ampersand, less than and greater than symbols i.e " ' & < >

Let's say you have a company name like "BL&T's". 
Then when you retrieve it from the API it will look like this:
Suggest Edits

Identifiers and URLs


All objects in the API have an id field indicating their logical identifier. Some objects may optionally also have a self field that indicates a URL or canonical address for the object.



A string that identifies the object within the API. The id field will not be larger than 128 characters (in SQL it corresponds to a varchar(128)).


A URL that addresses the object within the API. The self field will not be larger than 255 characters (in SQL it corresponds to a varchar(255)).

These fields must always be treated as opaque strings - no guarantees are made about the internal structure of the id or self fields for an object.

The id field is always defined by the API server and is guaranteed to be unique relative to the type field - this means no two user objects will have the same id field, but a user and a company may have the same value for their id fields.

Suggest Edits



List resources in the API are paginated by default to allow clients to traverse data over multiple requests. In most cases we're geared towards a default pagination limit of 10 resources per page which can be overridden via ?limit=<number>&page=<page number> query parameters. Pagination can also be toggled off via ?limit=0 query string

List resources in the API are paginated by default to allow clients to traverse data over multiple requests. In most cases we're geared towards a default pagination limit of 10 resources per page which can be overridden via ?limit=<number>&page=<page number> query parameters.

The Maxihost API provides a Link header according to RFC5988 that can be used to retrieve the next page.

Here's an example response header from requesting the third page of servers:
Link: <>; rel="next"

If the Link header is blank, that's the last page. The Maxihost API also provides the following pagination totals



Total number of resources you're fetching


The total number of pages

The API also provides links and meta/pages nodes that provide additional pagination data. Here's an example from requesting ?page=2 of devices

"links": {
        "first": "",
        "last": "",
        "next": "",
        "prev": "",
        "self": ""
    "meta": {
        "pages": {
            "count": 2,
            "total": 10


The first page. Included when the current page is greater than 1


The last page


The next page. Included when there's a next page


The previous page. Included when there's a previous page


The current page


The total number of resources


The total number of pages

Suggest Edits

Use of HTTP


Request methods are used in accordance with HTTP

  • GET is used to access resources and perform queries. The API does not allow modifications (creates, updates, deletes) to occur via GET.
  • POST is used to create or update resources. The preferred model for creation is to post JSON to a 'collections' resource - for example the collections resource for users is PATCH is not currently used by the API.
  • DELETE is used to delete resources.

Responses use standard HTTP codes. Where there are client or server errors, a list of of one or more errors in JSON format is returned in the body - see "Errors" for more details.

The API may send cache directives where suitable, notably the ETag, Last-Modified and If-Modified-Since headers.

The Accept header must be used by a client used to indicate a preferred response for GET/HEAD requests. Requests without an Accept header of application/json may be rejected with a client error of 404 or 406. The Content-Type header should be used by clients to indicate the submitted format for POST/PUT requests.

Suggest Edits



JSON objects in the API follow a must ignore processing model, where clients are expected to ignore data fields they don't understand.

For example if the client saw the JSON as shown in the example on the right ('Unknown Field')
and did not understand the such_key field, it must pretend the field wasn't there and will process the object as if it looked liked the object shown in 'Must Ignore'.

When fetching content, fields that are optional for API objects are indicated in the documentation - clients must not assume they will always be present. When submitting content, fields that are required to be sent by client are also indicated in the documentation - if these are not sent the API may reject the request.

In general the API may reject JSON where data is not valid or incomplete with a 422 Unprocessable Entity response and an error message explaining the issue.

Unknown Field

  "type": "user",
  "user_id" : "456456",
  "email" : "",
  "such_key": "so_value"

Must Ignore Interpretation

  "type": "user",
  "user_id" : "456456",
  "email" : ""