Simply API Documentation v

General information

This API can be used by anybody who wants to:
  • Order SimplyHosting Products
  • Manage their orders
  • Manage their servers
  • Manage their IPs
  • Manage their R1Soft Backup products
  • Manage their clients (resellers only)
  • Manage their private networks (via VLAN’s)
  • Manage their support tickets
We have two types of users in our systems
  • Customer - anyone who wants to use our API to order products and manage them.
  • Reseller - users who are reselling our products to their own customers and may require extended product list.
Making a request:
  • Most requests are sent using POST method unless otherwise specified.
  • api_key is a mandatory URL parameter required for all requests.
  • Arguments for all requests must be sent as POST arguments.
  • The Simply Hosting API only supports the JSON data serialisation format (i.e. the Content-Type and Accept headers are ignored)


To communicate with Simply Hosting services by using the REST API you will first need to be authenticated.
There are two ways to authenticate with the Simply Hosting API: using your Simply Hosting Portal Account (username and password) or using secret keys.
SimplyHosting Portal account authentication process as follows:
  • User authenticates themselves using the /user/auth/ API request.
  • Successful authentication provides a response with a hash, which is used as an authentication token.
  • Subsequent API requests must include this authentication token (api_key)in subsequent API calls.
SimplyHosting Secret key authentication process is as follows:
  • User creates a secret key via the Simply Hosting portal (or alternatively, using the /user/generateSecretKey/ after successful portal account authentication).
  • Subsequent API requests must include a generated authentication hash (i.e. a SHA256 hash of the secret key and timestamp) in subsequent API calls.
Note: A sample implementation for Simply Hosting API authentication is shown in the Sample Implementation chapter.

Synchronous and asynchronous responses

Some of the API requests are synchronous and others are asynchronous. If an API request is retrieving existing information, then this would normally be a synchronous call. With these requests, the caller waits until the call returns with the specified code and response body.
Some calls are asynchronous, since they may take some time to process. Therefore, they return 202 ACCEPTED responses containing information with a location URL, which allows the progress, status, or response information of the call to be retrieved at a later point in time.
When the status of an asynchronous request is queried using the API /tool/queue/ (via a location url supplied by the API) information regarding the status (i.e. Pending, Success or Failure) of the job is returned along with a 200 OK.
The results of asynchronous calls are retained for up to 7 days, once deleted, a 404 NOT FOUND will be returned for subsequent /tool/queue/ requests for a specific location URL.
If a request body does not pass initial validation or an error condition arises, you may receive an immediate error response from the request. 

Response format

  • All successful requests produce a HTTP 200 OK or HTTP 202 ACCEPTED status code.
  • All unsuccessful (or partially successful) requests produce a HTTP 50x or HTTP 404 NOT FOUND status code.
  • The HTTP response has the format below: 

Error handling

  • All unsuccessful (or partially successful) requests produce a HTTP 50x or HTTP 404 NOT FOUND status code.
  • Partially successful requests throw a HTTP 50x for the first detected error.
  • Partially successful requests provide more detailed error information in the status and errorMessage fields of the HTTP response body's responseType.

Implementation notes

Ordering Process

All orders are processed internally and until a product is ready (e.g. a server may need time to be built with the correct configuration), it will NOT be accessible via the Simply Hosting API or Portal. Even if the productID attribute has been allocated and returned in the API response, the product may be available only after some time (up to 30 minutes), awaiting internal processes to finish.

OS Installations

OS Installation can be carried out via the /server/install api.

You can only install the OS that you have requested when you purchased your server. If you wish to change to a different OS then you can do this by using the /server/upgrade API.

It’s also possible to specify the OS version you wish to install, but if you have an OS version that has reached its End of Life then you may need to install a later OS version (if a later version is supported). If there are no later versions available then you will need to raise a support ticket with our Support Team.

Partition Scheme

During OS installations (via /server/install), the Partition Scheme (partition_scheme) can be specified for a dedicated server Linux distribution . The partition scheme must be defined in JSON format and a example is shown below:

      "mount": "/",
      "size": 20,
      "expand": 0
      "mount": "swap",
      "size": 16,
      "expand": 0
      "mount": "/home/partition",
      "size": 250,
      "expand": 1
If the partition_scheme is not specified, then by default it will be configured with an expandable root (i.e. ‘/‘) partition of at least 4GB and a swap partition of 32GB.

Sandbox Environment

Sandbox environment is an isolated copy of the API environment, which doesn't have any data from the LIVE environment. Anything created in the LIVE environment will never get into the Sandbox environment and vice versa. To get access to our Sandbox environment, please contact our Support team.

Sample Implementation

Version change log

API Operations index

API Operations details