How to use the Hensel Hosting REST API

We recommend using curl for testing out the various features that the REST API offers.

We have created a small wrapper for PHP to get you started quickly.

Authentication is managed using HTTP authentication. Every request must include the Authorization HTTP header. A basic request to the API looks like this:

curl – u username:password URL

A customer can access the API if they provide a valid username and password and if they are allowed to access the API. To request permission to use the API, forward your request to support@hensel.nl
If you are not allowed to do a specific request, you will get back:

HTTP/1.0 404 Not Found.

The current API version allows the following actions:

  1. Domain availability
  2. New order
  3. Order list
  4. Order status

Please note: at this time it is only possible to add domains and/or webhosting to existing accounts.
Transferring domains and/or adding new accounts will be made available in next versions.

1. Domain availability

To check if a domain ”my-own-domain.eu” is available for registration, you can use a get request like this:

curl -u USERNAME:PASSWORD -X GET http://api.managedomain.nl/order/avail/my-own-domain.eu

Response:
– If you are not allowed to check domain availability you will get: HTTP/1.0 404 Not Found
– If the request was successful, you will get HTTP/1.0 200 OK and the XML may look something like this:

<domain>
<domain>my-own-domain.eu</domain>
<available>No</available>
</domain>

Possible return values for available are: “Yes” or “No”.

Please note: although availability is a good indication, it is by no means guaranteed that the domain is indeed free or that you are eligible to register the domainname.

2. New order

To place a new order you have to post a request to the REST API.
To place a new order (49 means registration product) for domain “my-own-domain.eu”, you can use this example:

curl -u USER:PASSWORD -H="Content-Type:application/xml" -d "<order><domain>my-own-domain.eu</domain>
<product_type_id>49</product_type_id>
<custom-ip>192.168.1.1</custom-ip>
</order>" -X POST http://api.managedomain.nl/order/ID

Where USER, PASSWORD should be your username and password, and ID should be your own account ID or the account ID from your customer (only possible if your account has reseller status).

  • The domain field is mandatory.
  • For the product-type choose one from the list below. If you don’t provide a product type, then by default it will be 49 registration-only.
  • 43 = small business
  • 50 = professional
  • 44 = personal
  • 45 = park plus (=deprecated)
  • 49 = register
  • 46 = forward (301/302/frame/docroot forwarding)
  • 47 = forward + email
  • 48 = forward IP (=deprecated)
  • custom-ip is optional and contains an IP address to use when the nameservers are setup. You can use this for example if you want the domain to point to that specific IP address.

Please note: only use custom-ip for registrations (49) because it does not make sense to pay for the added services and not use them because you host it yourself on the IP address specified.

Response:

  • If you are not allowed to post a new order you will get:
HTTP/1.0 404 Not Found
  • If the order was successfully created then you will get:
HTTP/1.0 201 Created

and the XML may look something like this:

<order>
<id>7206</id>
<domain>my-own-domain.eu</domain>
</order>
Where id is the id of the order just created. You can use this id to check the status of an order.

3. Order list

You can request the orders in your account or the orders of your customers.
To request a list of orders, you should make a request like:

curl –u USER:PASSWORD http://api.managedomain.nl/order/ID

Where USER, PASSWORD should be your username and password, and ID should be your own account ID or the account ID from your customer (only possible if your account has reseller status).
Response:

  • If there are no orders, you will get:
HTTP/1.0 404 Not Found
  • A valid request will return the header
HTTP/1.0 200 OK

and the XML may look something like this:

<orders>
<order>
<id>100</id>
<domain>my-own-domain.eu</domain>
</order>
<order>
<id>101</id>
<domain>my-other-domain.com</domain>
</order>
</orders>

Where id is the id of the order. You can use this id to check the status of an order.

4. Order status

You can check the status of an order using the domain name or the order id. You can check only the status of your own domains or the domains of your customers (if your account has reseller status).

curl -u USERNAME:PASSWORD -X GET http://api.managedomain.nl/order/status/my-own-domain.eu
OR
curl -u USERNAME:PASSWORD -X GET http://api.managedomain.nl/orde/status/7203

In the (unlikely) event, that multiple orders are present with the same domainname, only the status of the most recent, active order will be returned.

Response:

  • If you are not allowed to see the status of the order, you will get:
HTTP/1.0 404 Not Found
  • If you can get the status, then you will get
HTTP/1.0 200 OK

and the XML may look something like this:

<domain>
<orderid>7203</orderid>
<domain>my-own-domain.eu</domain>
<status>NEW</status>
</domain>

Possible return values for status are:

  • NEW (the order is waiting to be processed)
  • PENDING (the order is being processed)
  • WAITING-FORMS (we need forms to complete the order)
  • OK (the order is finished)