NAV
json xml

Introduction

Welcome to the API documentation of hosting.de.

How to navigate the API documentation:

The left column functions as an overview of our services. You can use it as an intuitive navigation. Click on a topic and find specific information for that service, object, or method. The middle column provides you with the information you are looking for. The column on the right shows you examples in JSON as well as in XML format.

What the API can do for you:

Our API allows you to manage your resources and those of your subaccounts’ in an easy way, using HTTP requests. Various document formats like JSON or XML are supported. Each resource type is managed in a service (e.g.: domain, DNS, SSL, etc.) with its own endpoint that provides default methods like listings as well as specific methods for the service.

One of the core principles of our platform system is to offer the same access level to every user. For example, the platform ‘web control panel’ uses the JSON-API, so everything you do with the panel can also be done using the API. This concept allows you to program and script very complex applications and to tailor them to your needs.

First, the API documentation gives you a general overview of the design and technology that has been implemented, followed by reference information about specific services.

Requests and Authentication

In order to communicate with the API, you simply have to use the right endpoint and a tool that is able to understand HTTP. Every request has to contain an appropriate Accept and Content-Type header.

The supported HTTP methods are POST and OPTIONS.

To access a specific service, you have to use the right endpoint. They are built in the following manner:

https://secure.hosting.de/api/{service}/{api-version}/{format}/{method}

So, an exemplary URL could look like this:

https://secure.hosting.de/api/account/v1/json/subaccountCreate.

This structure is valid for all document formats except for SOAP. In that case, the {method} parameter is embedded within the request document. This is what an equivalent SOAP request URL looks like:

https://secure.hosting.de/api/account/v1/soap/

Our goal is to keep code snippets clean and simple. The majority of developers using SOAP also use a generator for the WSDL file anyway. Please take a look at the JSON or XML examples, because we will not provide examples for SOAP.

Authentication

{
    "authToken": "$$YOUR API KEY$$"
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
</request>

Every request you send must contain the authToken parameter which has to be set to your API key. You can generate API keys in the web control panel.

Remember that API keys might have their own set of rights. This allows you to give your API key exactly the rights that you need for your application.

Request Delegation

{
    "authToken": "$$YOUR API KEY$$",
    "ownerAccountId": "$$ID OF YOUR SUBACCOUNT$$"
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <ownerAccountId>$$ID OF YOUR SUBACCOUNT$$</ownerAccountId>
</request>

Since subaccount handling is an important feature of the platform system, you can execute every request in the name of your account or any of your subaccounts. To execute a request as a subaccount, you need to add an ownerAccountId parameter containing the ID of the desired subaccount.

Thus the access and right validation will be performed as if the subaccount itself made the request. If your subaccount does not have the right or access to perform the operation, the request will fail - even if your main account or you have this right or access.

Responses

Sample single object response
{
    "responses": [
        "text list element 1",
        "text list element 2"
    ],
    "status": "success",
    ...
}
<response>
    <responses>
        <item>text list element 1</item>
        <item>text list element 2</item>
    </responses>
    <status>success</status>
    ...
</response>

Every request will return a response body in the same format of you request. A list of elements contains a responses object and a single element contains a response object.

Sample list response
{
    "authToken": "$$YOUR API KEY$$",
    "ownerAccountId": "$$ID OF YOUR SUBACCOUNT$$"
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <ownerAccountId>$$ID OF YOUR SUBACCOUNT$$</ownerAccountId>
</request>

If you receive a response body, it will contain a status element that specifies the result in general. The status may have one of the three following values:

Status Description
success The request was successful and processed in a synchronous manner. This usually applies to listings or requests which do not need to access a third party interface.
pending The request was successful but could not be processed in a synchronous manner. This applies to requests which need to access a third party interface in order to be completed, or to requests which may take a long time to complete. You will be informed of the result of these requests via poll messages.
error This status will occur, if there are any problems while processing your request. This could be a data or access violation or an error in a third party interface.

Metadata Object

{
    "metadata": {
       "clientTransactionId": "$$CLIENT STRING ID$$",
       "serverTransactionId": "UNIQUE SERVER TRANSACTION ID"
   },
    ...
}
<response>
    <metadata>
      <clientTransactionId>$$CLIENT STRING ID$$</clientTransactionId>
      <serverTransactionId>A UNIQUE SERVER TRANSACTION ID</serverTransactionId>
   </metadata>
    ...
</response>

Every developer faces the problem of matching responses or poll messages to requests. To simplify this process for you as much as possible, we provide a metadata object. This object contains a clientTransactionId element and a serverTransactionId element which will help you to keep track of your communication with the API.

Every request may contain an optional clientTransactionId parameter. You can fill this element with any string up to a length of 127 characters. The response and polls associated with your request will contain the same string. The serverTransactionId element is filled by the server and will be present in the response. This ID is unique throughout the whole system. It will also be present in every poll message you receive that is associated with that request.

HTTP Status Codes

While most errors will be communicated via API error codes, some low level issues may cause transport level errors. You should handle the following error codes with an application:

Code Meaning
200 OK
400 The HTTP request was malformed
404 Method, format, or entry point not found
405 Method not allowed
500 Internal server error
502 Server temporarily not available
503 Server temporarily not available due to maintenance
504 Backend timeout

Warnings and Errors

Request contactCreate
{
    "authToken": "$$YOUR API KEY$$",
    "contact": {
        "type": "asd",
        "phone": "+49",
        ...
    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <contact>
  <type>asd</type>
  <phone>+49</phone>
   ...
 </contact>
</request>
Response
{
    "status": "error",
    "errors": [
        {
            "code": 32002,
            "contextObject": "",
            "contextPath": "/contact/type",
            "details": [],
            "text": "Handle type is invalid",
            "value": "asd"
        },
        {
            "code": 32022,
            "contextObject": "",
            "contextPath": "/contact/phone",
            "details": [],
            "text": "Format of the phone number is invalid. The E.123 international notation is required",
            "value": "+49"
        }
    ],
    ...
}
<response>
 <status>error</status>
 <errors>
  <item>
   <code>32002</code>
   <contextObject></contextObject>
   <contextPath>/contact/type</contextPath>
   <details/>
   <text>Handle type is invalid</text>
   <value>asd</value>
  </item>
  <item>
   <code>32022</code>
   <contextObject></contextObject>
   <contextPath>/contact/phone</contextPath>
   <details/>
   <text>Format of the phone number is invalid. The E.123 international notation is required</text>
   <value>+49</value>
  </item>
 </errors>
 ...
</response>

If an error occurs, you will receive detailed information. To speed up the development process and to help prevent a try and error approach, the API collects all errors and warnings related to your request. The response will contain a list of error objects.

Your request may also contain an error that the API will automatically fix. In that case, the response will contain a list of warnings as well. The warnings tell you what was wrong and what the API did to fix the problem (for example a TTL value was too small, so it was raised to the minimum value).

The error object contains a code element which masks the specific error code. The code consists of multiple digits: The last four digits specify the occured error. The digits further up front specify the respective service.

The text contains a human-readable error description. This text can be used to give feedback to users of your application.

If you modify an existing object, the contextObject will be set to its ID. In case of a create request, the field will be empty. In case of a data violation error, the value property shows you the content of the member that caused the error.

details is a list of key/value objects which provide additional information about the specific error. This might help you with debugging or presenting a more detailed error to your user.

The contextPath is a value which points to the element that caused the error. This will help you to easily identify this element in your request document. For JSON requests we use JSON-Pointers (RFC 6901), for XML and SOAP we use XPath (RFC 5261).

Filtering and Sorting

{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "subFilterConnective": "OR",
        "subFilter": [
            {
                "field": "domainNameAce",
                "value": "$$DOMAIN NAME 1$$"
            },
            {
                "field": "domainNameAce",
                "value": "$$DOMAIN NAME 2$$"
            }
        ]
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "domainNameAce",
        "order": "ASC"
    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <subFilterConnective>OR</subFilterConnective>
  <subFilter>
   <item>
    <field>domainNameAce</field>
    <value>$$DOMAIN NAME 1$$</value>
   </item>
   <item>
    <field>domainNameAce</field>
    <value>$$DOMAIN NAME 2$$</value>
   </item>
  </subFilter>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>domainNameAce</field>
  <order>ASC</order>
 </sort>
</request>

Each service offers listing methods for the resources it manages. These methods are identical throughout the whole system. Different are the fields you can search in or sort by. The signature of each listing method accepts the following parameters:

Parameter Type Required Description
filter Filter or Chain opt Filter object for the request
limit number opt Maximal number of records that should be returned (Defaults to 25)
page number opt Translates to an offset in the record list.
sort SortOptions opt Fields the result is sorted by

Filter Object

{
    "field": "domainName",
    "value": "example.com"
}
<filter>
 <field>domainName</field>
 <value>example.com</value>
</filter>
Property Type Required Description
field string req Field name
value string req Contains the search string

In its simplest form, the filter parameter takes a field and a value parameter. The result will match to this condition. The field element refers to the field you want to filter. value is the argument for that field. By default, the value is a case-insensitive exact match. An asterisk (*) can be used to match an arbitrary number of characters (including zero characters).

The field element is restricted to a list of field names which vary from listing to listing. You can find lists of available and valid fields throughout the API. Please refer to specific documentation sections for the respective finding methods. Field names are case insensitive.

{
    "subFilterConnective": "OR",
    "subFilter": [
        {"field": "domainName", "value": "*.de"},
        {"field": "domainName", "value": "*.com"}
    ]
}
<filter>
 <subFilterConnective>OR</subFilterConnective>
 <subFilter>
  <item>
   <field>domainName</field>
   <value>*.de</value>
  </item>
  <item>
   <field>domainName</field>
   <value>*.com</value>
  </item>
 </subFilter>
</filter>

Complex queries can be created by chaining condition objects with a chain object. Chain objects can contain further chain objects.

Chain Object

Property Type Required Description
subFilter list<Filter or Chain> req Contains other filter objects
subFilterConnective string req AND or OR

If you are using the SOAP API you have to use the Filter SOAP type for both Filter and Chain objects.

Response

The response will contain an object wrapping the results and some meta information for pagination.

{
    "data": [
        ...
    ],
    "limit": 10,
    "page": 1,
    "totalEntries": 50,
    "totalPages": 5,
    "type": "FindDomainsResult"
}
<response>
 <data>
  ...
 </data>
 <limit>10</limit>
 <page>1</page>
 <totalEntries>50</totalEntries>
 <totalPages>5</totalpages>
 <type>FindDomainsResult</type>
</response>
Property Type Direction Description
page int out-only Page number as requested
limit int out-only Limit as requested
totalEntries int out-only Total number of results
totalPages int out-only Total number of result pages
data list<…> out-only Found objects

Domains

The domain part of the API allows to create and maintain domains in a wide variety of domain name registries.

Each domain requires contact information of the owner as well as other individuals and organizations involved in maintaining the domain.

Allocation Description
owner Legal owner of domain name
admin Administrative contact
tech Technical contact
zone Contact for issues regarding the DNS servers or DNS setup of the domain

If a registry has a separate billing contact, the admin contact will be used as billing contact in registry operations.

Each domain requires two or more name servers. They need to serve authoritative answers regarding host names in the DNS zone corresponding to the domain.

The Contact Object

{
    "accountId": "15010100000001",
    "id": "15010100000010",
    "handle": "JS15",
    "type": "person",
    "name": "John Smith",
    "organization": "",
    "street": [
        "Happy ave. 42"
    ],
    "postalCode": "12345",
    "city": "Where ever",
    "state": "",
    "country": "de",
    "emailAddress": "john@example.com",
    "phoneNumber": "+49 1234 567890",
    "faxNumber": "",
    "sipUri": "",
    "hidden": false,
    "usableBySubAccount": false,
    "addDate": "2015-01-01T00:00:00",
    "lastChangeDate": "2015-01-01T00:00:00"
}
<id>15010100000000</id>
<accountId>15010100000000</accountId>
<handle>JS15</handle>
<type>person</type>
<name>John Smith</name>
<organization></organization>
<street>
    <item>Happy ave. 42</item>
</street>
<postalCode>12345</postalCode>
<city>Where ever</city>
<state></state>
<country>de</country>
<emailAddress>john@example.com</emailAddress>
<phoneNumber>+49 1234 567890</phoneNumber>
<faxNumber></faxNumber>
<sipUri></sipUri>
<hidden>false</hidden>
<usableBySubAccount>false</usableBySubAccount>
<addDate>2015-01-01T00:00:00</addDate>
<lastChangeDate>2015-01-01T00:00:00</lastChangeDate>

The contact object is used for managing domains. It can have one of three types:

Contact Object

Property Type Required / Direction Description
accountId string out-only ID of contact managing account. Field never used in requests.
id string see description Contact ID. Ignored in contact create requests. Either id or handle is required in all other requests.
handle string see description Contact handle. Ignored in contact create requests. Either id or handle is required in all other requests.
type string req Valid types are person, org, and role
name string req Full contact name. For organizations this is the name of a contact in the organization.
organization string see description Is a required field for org handles. Name of the organization
Example: Beispiel Ltd.
street list<string> req List of address entries. Contains up to three entries.
postalCode string opt Postal code (address)
city string req City (address)
state string opt State (address)
country string req Country code in ISO 3166-1 alpha-2 (see iso.org or Wikipedia). Will always be returned in lower case.
Example: de
emailAddress string req Must be a valid email address
phoneNumber string req The phone number consists of country code, area code and the local number. These three parts are separated by spaces. Additional spaces are not allowed.
example: +49 123 4567890.
faxNumber string opt Fax number (same rules apply as for the phone number)
Example: +49 123 4567899
sipUri string opt SIP URI
hidden bool opt Can be used to mark unwanted contacts that are still in use. If a hidden contact is used as domain handle, the API will warn you.
usableBySubAccount bool opt Allows direct subaccounts to use this contact
addDate datetime out-only Date and time of contact creation
lastChangeDate datetime out-only Date and time the contact was last modified

Listing Contacts

POST https://secure.hosting.de/api/domain/v1/jsonxml/contactsFind
{
    "authToken": "$$YOUR API KEY$$",
    "clientTransactionId": "",
    "filter": {
        "field": "ContactName",
        "value": "*Smith*"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "ContactName",
        "order": "asc"
    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <clientTransactionId></clientTransactionId>
 <filter>
  <field>ContactName</field>
  <value>*Smith*</value>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>ContactName</field>
  <order>asc</order>
 </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // contact objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindContactsResult"
    },
    ...
}
<response>
 <response>
  <data/>
     // contact objects
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindContactsResult</type>
 </response>
</response>
RequestcontactsFind
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/contactsFind
Processingsynchronous
ResponseFindContactsResult

Listing contacts uses the generic filtering and sorting API with the method contactsFind. The response will contain a list of Contact objects.

The following fields are available for filtering and sorting:

Field Description
AccountId Managing account ID
ContactId ID of contact
ContactHandle Handle of contact
ContactType Type of contact (cf. Contact object)
ContactName Name of contact
ContactOrganization Organization of contact
ContactStreet All street entries (contact address)
ContactPostalCode Postal code (contact address)
ContactCity City (contact address)
ContactState State (contact address)
ContactCountry Country of address in ISO 3166-1 alpha-2 (cf. Contact objects)
ContactEmailAddress Email address of contact
ContactPhoneNumber Phone number of contact (format, cf. Contact objects)
ContactFaxNumber Fax number of the contact (format, cf. Contact objects)
ContactSipUri SIP URI of contact
ContactUsableBySubAccount Contact is usable by subaccounts
ContactHidden Contact is hidden
UsableForDomainInAccount Must be an account ID. If set, the listing will only return contacts that are usable for domain operations for that specific account.

Retrieving Specific Contacts

POST https://secure.hosting.de/api/domain/v1/jsonxml/contactInfo
{
    "authToken": "$$YOUR API KEY$$",
    "contactId": "15010100000010"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <contactId>15010100000010</contactId>
</request>
Response
{
    ...
    "response": {
        // contact object
    },
    ...
}
<response>
 ...
 <response>
     // contact object
 </response>
 ...
</response>
RequestcontactInfo
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/contactInfo
Processingsynchronous
ResponseContact object
Parameter Type Required Description
contactId string req ID of contact

In order to retrieve a specific contact, you can either use the contactsFind method and use the ContactId filter or you can use the contactInfo method which uses a contact ID as input and returns the contact object, if it exists.

Creating New Contacts

POST https://secure.hosting.de/api/domain/v1/jsonxml/contactCreate
{
    "authToken": "$$YOUR API KEY$$",
    "contact": {
        "type": "person",
        "name": "John Smith",
        "organization": "",
        "street": [
            "Happy ave. 42"
        ],
        "postalCode": "12345",
        "city": "Where ever",
        "country": "de",
        "emailAddress": "john@example.com",
        "phoneNumber": "+49 1234 567890"
    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <contact>
  <type>person</type>
  <name>John Smith</name>
  <organization></organization>
  <street>
   <item>Happy ave. 42</item>
  </street>
  <postalCode>12345</postalCode>
  <city>Where ever</city>
  <country>de</country>
  <emailAddress>john@example.com</emailAddress>
  <phoneNumber>+49 1234 567890</phoneNumber>
 </contact>
</request>
Response
{
    ...
    "response": {
        "accountId": "15010100000001",
        "id": "15010100000010",
        "handle": "JS15",
        "addDate": "2015-01-01T00:00:00",
        "lastChangeDate": "2015-01-01T00:00:00",
        ...
    },
    ...
}
<response>
 <response>
  <id>15010100000010</id>
  <accountId>15010100000001</accountId>
  <handle>JS15</handle>
  <addDate>2015-01-01T00:00:00</addDate>
  <lastChangeDate>2015-01-01T00:00:00</lastChangeDate>
 </response>
</response>
RequestcontactCreate
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/contactCreate
Processingsynchronous
ResponseContact object
Parameter Type Required Description
contact Contact object req Complete contact object

This method is used to create a new contact in the system. The object must contain all required fields. id and handle fields can be filled, but will be ignored. The response will contain the newly created contact object.

Updating Contacts

POST https://secure.hosting.de/api/domain/v1/jsonxml/contactUpdate
{
    "authToken": "$$YOUR API KEY$$",
    "contact": {
        "handle": "JS48", // or "id": "15010100000010"
        ...
        "emailAddress": "jane@example.com",
        ...
    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <contact>
 <handle>JS48</handle> // or <id>15010100000010</id>
  ...
  <emailAddress>jane@example.com</emailAddress>
  ...
 </contact>
</request>
Response
{
    ...
    "response": {
        ...
        "emailAddress": "jane@example.com",
        "lastChangeDate": "2015-01-01T12:00:00",
        ...
    },
    ...
}
<response>
 ...
 <response>
  ...
  <emailAddress>jane@example.com</emailAddress>
  <lastChangeDate>2015-01-01T12:00:00</lastChangeDate>
  ...
 </response>
 ...
</response>
RequestcontactUpdate
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/contactUpdate
Processingasynchronous
ResponseContact object
Parameter Type Required Description
contact Contact object req Complete contact object

The contact to update can either be identified by id or by handle. All fields not marked ‘out-only’ are set to the values in the contact argument. Optional fields that are not specified in this request are reset to their default values.

The update is pushed to every registry the contact is connected to. This will result in seperate jobs for every registry.

Please note that type, name, and organization of a contact cannot be changed. Some registries do not allow changing phone numbers as well. In case the contact is used in a domain from these registries, the API will return a synchronous error.

Deleting Contacts

Deleting contacts via API is not possible at the moment and might never be. Unused contacts will automatically be deleted after a while. In that case, an automatic poll message will inform you.

If you want to hide a contact, you can set the hidden parameter to true. Then, the contact will not be shown in the web control panel for registering new domains. Also, the contactsFind method will not return the contact any longer, if you use the filter UsableForDomainInAccount.

The Domain Object

{
    "id": "150101000000010",
    "accountId": "150101000000001",
    "name": "example.com",
    "nameUnicode": "example.com",
    "status": ["ok"],
    "transferLockEnabled": false,
    "authInfo": "1234,ABCD+xyz",
    "contacts": [
        {
            "contact": "150101000000021",
            "type": "owner"
        },
        {
            "contact": "150101000000020",
            "type": "admin"
        },
        {
            "contact": "150101000000022",
            "type": "tech"
        },
        {
            "contact": "150101000000023",
            "type": "zone"
        }
    ],
    "nameservers": [
        {
            "ips": [],
            "name": "ns.example.net"
        },
        {
            "name": "ns.example.com",
            "ips": ["192.0.2.1", "2001:db8:3fe:1001:7777:772e:2:85"]
        }
    ],
    "createDate": "2014-01-01",
    "currentContractPeriodEnd": "2015-12-31",
    "nextContractPeriodStart": "2016-01-01",
    "deletionType": "",
    "deletionDate": "",
    "addDate": "2015-01-01T00:00:00",
    "lastChangeDate": "2014-12-15T00:00:00"
}
<domainObject>
 <id>150101000000010</id>
 <accountId>150101000000001</accountId>
 <name>example.com</name>
 <nameUnicode>example.com</nameUnicode>
 <status>
  <item>ok</item>
 </status>
 <transferLockEnabled>false</transferLockEnabled>
 <authInfo>1234,ABCD+xyz</authInfo>
 <contacts>
  <item>
   <contact>150101000000021</contact>
   <type>owner</type>
  </item>
  <item>
   <contact>150101000000020</contact>
   <type>admin</type>
  </item>
  <item>
   <contact>150101000000022</contact>
   <type>tech</type>
  </item>
  <item>
   <contact>150101000000023</contact>
   <type>zone</type>
  </item>
 </contacts>
 <nameservers>
  <item>
   <ips/>
   <name>ns.example.net</name>
  </item>
  <item>
   <ips>
    <item>192.0.2.1</item>
    <item>2001:db8:3fe:1001:7777:772e:2:85</item>
   </ips>
   <name>ns.example.com</name>
  </item>
 </nameservers>
 <createDate>2014-01-01</createDate>
 <currentContractPeriodEnd>2015-12-31</currentContractPeriodEnd>
 <nextContractPeriodStart>2016-01-01</nextContractPeriodStart>
 <deletionDate></deletionDate>
 <deletionType></deletionType>
 <addDate>2015-01-01T00:00:00</addDate>
 <lastChangeDate>2014-12-15T00:00:00</lastChangeDate>
</domainObject>

Domain Object

Property Type Required / Direction Description
id string out-only Domain ID
accountId string out-only ID of account managing domain (field is never used in requests)
name string req Domain name. (Unicode or ASCII format). The name will always be returned in ASCII/ACE format.
nameUnicode string out-only Domain name in Unicode/international format
status string out-only Domain status, cf. below for explanation of statuses
transferLockEnabled bool req If set to true, outgoing transfers will be blocked. Please keep in mind that not every TLD supports this feature.
authInfo string out-only The domain transfer authorisation code for this domain. Only contains a value if transferLockEnabled is not set.
contacts list<DomainContact> req List of contacts for this domain, cf. Domain Contact Object for details
nameservers list<Nameserver> req List of name servers for this domain, cf. Name Server Object for details.
createDate date out-only Date of domain creation. If the domain is transferred in and the registry does not support getting the original creation date, it will be the date of the transfer.
currentContractPeriodEnd date out-only End date of current contract period
nextContractPeriodStart date out-only Start date of next contract period
deletionType string out-only Removal mode (delete or withdraw). Empty when domain is not scheduled for removal.
deletionDate datetime out-only Date the domain is scheduled for deletion or withdrawal. Is empty if domain is not scheduled for removal.
addDate datetime out-only Date and time this domain was created in or transferred into our system.
lastChangeDate datetime out-only Date and time of last modification of any domain data in our system.

DomainContact Object

Property Type Required Description
type string req owner, admin, tech, or zone
contact string req Contact handle or ID in our system. The contact will always be returned as an ID.

Nameserver Object

Property Type Required Description
name string req Fully qualified domain name of name server.
Example: ns1.example.net
ips list<string> cf. description List of IP addresses of this name server. Required for name servers that are subdomains of the domain itself. Otherwise it is ignored.
Examples: “192.0.2.15”, “2001:db8::cafe”, “2001:db8:3fe:1001:7777:772e:2:85”

Domain Status

The following domain statuses are defined:

Domain status Description
ordered Domain is ordered but create or transfer process is not completed yet
ok Domain is in customer’s account
restorable Domain was deleted and is in restore grace period
prereg Domain is pre-registered
failed Domain is failed; registry will delete the domain if no action is taken

Listing Domains

POST https://secure.hosting.de/api/domain/v1/jsonxml/domainsFind
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "domainNameUnicode",
        "value": "*example.com*"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "domainNameUnicode",
        "order": "asc"
    }
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <field>domainNameUnicode</field>
  <value>*example.com*</value>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>domainNameUnicode</field>
  <order>asc</order>
 </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // domain objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindDomainsResult"
    },
    ...
}
<response>
 <response>
  <data>
   ...
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindDomainsResult</type>
 </response>
 ...
</response>
RequestdomainsFind
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/domainsFind
Processingsynchronous
ResponseFindDomainsResult

When listing domains, you use the generic filtering and sorting API with the method domainsFind. The response will contain a list of Domain objects.

The following fields are available for filtering and sorting:

Field Description
DomainId ID of domain
AccountId ID of domain’s managing account
DomainName Domain name in ACE format
DomainNameUnicode Domain name in Unicode format
DomainStatus Domain Status
DomainCreateDate Domain creation date (in registry)
DomainCurrentContractPeriodEnd End date of current domain contract period
DomainNextContractPeriodStart Start date of next domain contract period
DomainTransferLockEnabled Activate blocking transfer outs
DomainDeletionType Delete or withdraw domain. Empty, if domain is not scheduled for removal.
DomainDeletionDate Withdrawal/Deletion date. Empty, if domain is not scheduled for removal.
DomainAddDate Date and time the domain was created in our system or transferred into into it.
DomainLastChangeDate Date and time of last domain data modification in our system
ContactId Match domains using this contact
DomainContactAllocation Match domains that use ContactId for this allocation

Registering New Domains

POST https://secure.hosting.de/api/domain/v1/jsonxml/domainCreate
{
    "authToken": "$$YOUR API KEY$$",
    "domain": {
        "name": "example.com",
        "transferLockEnabled": true,
        "contacts": [
            {
                "contact": "150101000000021",
                "type": "owner"
            },
            {
                "contact": "150101000000020",
                "type": "admin"
            },
            {
                "contact": "150101000000022",
                "type": "tech"
            },
            {
                "contact": "150101000000023",
                "type": "zone"
            }
        ],
        "nameservers": [
            {
                "name": "ns1.example.net"
            },
            {
                "name": "ns2.example.net"
            },
            {
                "name": "ns3.example.com",
                "ip": ["192.0.2.1", "192.0.2.200", "2001:db8:3fe:1001:7777:772e:2:85"]
            }
        ]
    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domain>
  <name>example.com</name>
  <transferLockEnabled>true</transferLockEnabled>
  <contacts>
   <item>
    <contact>150101000000021</contact>
    <type>owner</type>
   </item>
   <item>
    <contact>150101000000020</contact>
    <type>admin</type>
   </item>
   <item>
    <contact>150101000000022</contact>
    <type>tech</type>
   </item>
   <item>
    <contact>150101000000023</contact>
    <type>zone</type>
   </item>
  </contacts>
  <nameservers>
   <item>
    <name>ns1.example.net</name>
   </item>
   <item>
    <name>ns2.example.net</name>
   </item>
   <item>
    <ip>
    <name>ns3.example.com</name>
     <item>192.0.2.1</item>
     <item>192.0.2.200</item>
     <item>2001:db8:3fe:1001:7777:772e:2:85</item>
    </ip>
   </item>
  </nameservers>
 </domain>
</request>
Response
{
    ...
    "response": {
        "id": "150101000000010",                    // newly generated id
        "accountId": "150101000000001",             // account id used for creation
        "name": "example.com",                      // domain name translated to Ace form
        "nameUnicode": "example.com",               // domain name translated to Unicode form
        "status": ["api-create-pending"],           // domain registration is running
        // ... as supplied in request, contact handles will be translated to ids
        "createDate": "2014-01-01",                 // always current date for create
        "currentContractPeriodEnd": "2015-12-31",   // provisional value
        "nextContractPeriodStart": "2016-01-01",    // provisional value
        "addDate": "2015-01-01T00:00:00",           // always current date for create
        "lastChangeDate": "2015-01-01T00:00:00"     // always current date and time
    }
}
<response>
 <response>
  <id>150101000000010</id>                                          // newly generated id
  <accountId>150101000000001</accountId>                            // account id used for creation
  <name>example.com</name>                                          // domain name translated to Ace form
  <nameUnicode>example.com</nameUnicode>                            // domain name translated to Unicode form
  <status>                                                          // domain registration is running
   <item>api-create-pending</item>
  </status>
  // ... as supplied in request, contact handles will be translated to ids
  <createDate>2014-01-01</createDate>                               // always current date for create
  <currentContractPeriodEnd>2015-12-31</currentContractPeriodEnd>   // provisional value
  <nextContractPeriodStart>2016-01-01</nextContractPeriodStart>     // provisional value
  <addDate>2015-01-01T00:00:00</addDate>                            // always current date for create
  <lastChangeDate>2015-01-01T00:00:00</lastChangeDate>              // always current date and time
 </response>
</response>
RequestdomainCreate
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/domainCreate
Processingasynchronous
ResponseDomain object
Parameter Type Required Description
domain Domain object req Data for to be created domain

In order to create a domain, you need to send a domainCreate request. This request takes one parameter domain which contains all required information of a domain object.

Each allocation (owner, tech, admin, zone) requires one contact. The system will ensure that only supported contact allocations will be used for registry operations.

The contractPeriod details are provisional values. If the actual registration of the domain is delayed, the contract period will be adjusted accordingly.

Updating Domains

POST https://secure.hosting.de/api/domain/v1/jsonxml/domainUpdate
{
    "authToken": "$$YOUR API KEY$$",
    "clientTransactionId": "",
    "domain": {
        "name": "example.com",
        "transferLockEnabled": false,
        "contacts": [
            {
                "contact": "150101000000025",
                "type": "owner"
            },
            {
                "contact": "150101000000024",
                "type": "admin"
            },
            {
                "contact": "150101000000026",
                "type": "tech"
            },
            {
                "contact": "150101000000027",
                "type": "zone"
            }
        ],
        "nameservers": [
            {
                "name": "ns1.great-domains.net"
            },
            {
                "name": "ns2.great-domains.net"
            }
        ]

    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <clientTransactionId></clientTransactionId>
 <domain>
  <name>example.com</name>
  <transferLockEnabled>false</transferLockEnabled>
  <contacts>
   <item>
    <contact>150101000000025</contact>
    <type>owner</type>
   </item>
   <item>
    <contact>150101000000024</contact>
    <type>admin</type>
   </item>
   <item>
    <contact>150101000000026</contact>
    <type>tech</type>
   </item>
   <item>
    <contact>150101000000027</contact>
    <type>zone</type>
   </item>
  </contacts>
  <nameservers>
   <item>
    <name>ns1.great-domains.net</name>
   </item>
   <item>
    <name>ns2.great-domains.net</name>
   </item>
  </nameservers>
 </domain>
</request>
RequestdomainUpdate
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/domainUpdate
Processingasynchronous
ResponseDomain object
Parameter Type Required Description
domain Domain object req Updated domain data

In order to update a domain, you send a domainUpdate request with a domain object containing the modified properties.

Usually, you need to send a modified version of an object you received from domainInfo or domainsFind.

The modified domain is identified by the id or name property in the supplied domain object. All fields not marked ‘out-only’ are set to the values in the contact argument. Optional fields that are not specified in this request are reset to their default values.

The response will contain the modified domain object.

Retrieving Specific Domains

POST https://secure.hosting.de/api/domain/v1/jsonxml/domainInfo
{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "example.com"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>example.com</domainName>
</request>
RequestdomainInfo
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/domainInfo
Processingsynchronous
ResponseDomain object
Parameter Type Required Description
domainName string req Domain name (ACE or Unicode)

The domainInfo is a shortcut to retrieve data of a domain with a specific name.

Checking Domain Name Availability

POST https://secure.hosting.de/api/domain/v1/jsonxml/domainStatus
{
    "authToken": "$$YOUR API KEY$$",
    "domainNames": [
        "somedomain.com"
    ]
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainNames>
  <item>somedomain.com</item>
 </domainNames>
</request>
Response
{
    "metadata": { ... },
    "responses": [
        {
            "domainName": "example.com",
            "domainNameUnicode": "example.com",
            "domainSuffix": "com",
            "status": "available",
            "transferMethod": "authInfo"
        }
    ],
    "status": "success",
    "warnings": [ ]
}
<response>
 <metadata>...</metadata>
 <responses>
  <item>
   <domainName>example.com</domainName>
   <domainnameUnicode>example.com</domainNameUnicode>
   <domainSuffix>com</domainSuffix>
   <status>available</status>
   <transferMethod>authInfo</transferMethod>
  </item>
 </responses>
 <status>success</status>
 <warnings/>
</response>
RequestdomainStatus
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/domainStatus
Processingsynchronous
ResponseDomainStatusResult object
Parameter Type Required Description
domainNames list req Domain names to check either in Unicode or ASCII format.

In order to check whether one or more domain names are available for registration, you only need to pass a list of the domain names you want to check as domainNames parameter.

The response will contain a list of objects of the following type:

DomainStatusResult Object

Property Type direction Description
domainName string out Name of checked domain in ACE format
domainNameUnicode string out Name of checked domain in Unicode format
domainSuffix string out Domain suffix
status string out Result of check
transferMethod string out Transfer method if domain is already registered

The possible domain statuses can be returned to you:

status Description
alreadyRegistered You (or a sub account) already registered the domain
registered Somebody else registered domain
nameContainsForbiddenCharacter Domain name contains invalid characters
available Domain is available for registration
suffixDoesNotExist Domain suffix does not exist
suffixCannotBeRegistered You are not allowed to register a domain with this suffix
canNotCheck System is currently unable to check availability
unknown Other problems or difficulties occured

If the status is registered, the transferMethod will further specify how you can start a transfer in:

transferMethod Description
“” (empty string) Transfer uses out-of-band authentication. In that case, do not specify authInfo in domainTransfer request.
authInfo Transfer uses authInfo. Supply it in domainTransfer request.
push Domain uses push. First start a domainTransfer to pre-authorize domain transfer to your account and then push to our registrar’s tag with the domain’s current supplier.

Deleting Domains

POST https://secure.hosting.de/api/domain/v1/jsonxml/domainDelete
{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "somedomain.de"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>somedomain.de</domainName>
</request>
RequestdomainDelete
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/domainDelete
Processingasynchronous
Responsenone
Parameter Type Required Description
domainName string req Name of the domain to be deleted (Unicode or ASCII format)
execDate string opt Scheduled deletion date

In order to delete a domain, you can use the domainDelete request. Its simplest form only requires domainName as parameter. The domain’s scheduled deletion date is set immediately.

Scheduled delete

POST https://secure.hosting.de/api/domain/v1/jsonxml/domainDelete
{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "somedomain.de",
    "execDate": "2015-01-01T00:00:00Z"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>somedomain.de</domainName>
 <execDate>2015-01-01T00:00:00Z</execDate>
</request>

If you also specify an execDate, it will be scheduled for deletion on execDate. This will change the domain object’s deletionType to delete and set its deletionDate.

Withdrawing Domains

POST https://secure.hosting.de/api/domain/v1/jsonxml/domainWithdraw
{
    "authToken": "$$YOUR API KEY$$",
    "disconnect": false,
    "domainName": "somedomain.de"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <disconnect>false</disconnect>
 <domainName>somedomain.de</domainName>
</request>
RequestdomainWithdraw
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/domainWithdraw
Processingasynchronous
Responsenone
Parameter Type Required Description
domainName string req Name of the domain to be withdrawn (Unicode or ASCII format)
disconnect bool req Disconnect the domain from name servers after withdrawal
execDate string opt Scheduled withdrawal date

In order to withdraw a domain, you can use the request domainWithdraw. Its simplest form only requiresdomainName and disconnect as parameter. The domain’s withdrawal date is set immediately.

Scheduled withdraw

POST https://secure.hosting.de/api/domain/v1/jsonxml/domainWithdraw
{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "example.de",
    "execDate": "2015-01-01T00:00:00Z"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>example.de</domainName>
 <execDate>2015-01-01T00:00:00Z</execDate>
</request>

If you also specify an execDate, it will be scheduled for withdrawal on execDate. This will set the domain object’s deletionType to withdraw and set its deletionDate.

Starting Transfer-Ins

POST https://secure.hosting.de/api/domain/v1/jsonxml/domainTransfer
{
    "authToken": "$$YOUR API KEY$$",
    "domain": {
        "name": "example.org",
        "transferLockEnabled": true,
        "contacts": [
            {
                "contact": "150101000000021",
                "type": "owner"
            },
            {
                "contact": "150101000000020",
                "type": "admin"
            },
            {
                "contact": "150101000000022",
                "type": "tech"
            },
            {
                "contact": "150101000000023",
                "type": "zone"
            }
        ],
        "nameservers": [
            {
                "name": "ns1.example.net"
            },
            {
                "name": "ns2.example.net"
            },
            {
                "name": "ns3.example.net"
            }
        ]
    },
    "transferData": {
        "authInfo": "1234,ABCD+xyz"
    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domain>
  <name>example.org</name>
  <contacts>
   <item>
    <contact>150101000000021</contact>
    <type>owner</type>
   </item>
   <item>
    <contact>150101000000020</contact>
    <type>admin</type>
   </item>
   <item>
    <contact>150101000000022</contact>
    <type>tech</type>
   </item>
   <item>
    <contact>150101000000023</contact>
    <type>zone</type>
   </item>
  </contacts>
  <nameservers>
   <item>
    <name>ns1.example.net</name>
   </item>
   <item>
    <name>ns2.example.net</name>
   </item>
   <item>
    <name>ns3.example.net</name>
   </item>
  </nameservers>
  <transferLockEnabled>true</transferLockEnabled>
 </domain>
 <transferData>
  <authInfo>1234,ABCD+xyz</authInfo>
 </transferData>
</request>
RequestdomainTransfer
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/domainTransfer
Processingasynchronous
ResponseDomain object
Parameter Type Required Description
domain Domain object req Data for transferred domain
transferData TransferData object req Additional transfer settings

TransferData Object

Property Type Required Description
authInfo string opt authInfo / Password for domain Transfer
foaRecipient string opt admin, owner, or both: Which contacts should receive the FOA mail.

Transferring domains with the API is a similar process to registering new domains. Please refer to domainCreate for further details on the domain parameter.

When transferring domains, your request needs a transferData object. For most domains you need to fill the authInfo field with a transfer password obtained from the registrar currently managing that domain.

You can check whether this field is required by using the response from the domainStatus request. If the response’s transferMethod is authInfo, it is needed.

Before requests for certain domain suffixes are processed, the registrar has to check with the current owner and/or administration contact whether the transfer is authorized. For these domain suffixes you can specify which contact shall receive an email to pre-confirm the transfer.

Acknowledging Transfer-Out Requests

POST https://secure.hosting.de/api/domain/v1/jsonxml/domainTransferOutAck
{
    "authToken": "$$YOUR API KEY$$",
     "domainName": "example.com"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>example.com</domainName>
</request>
RequestdomainTransferOutAck
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/domainTransferOutAck
Processingasynchronous
ResponseDomain object
Parameter Type Required Description
domainName string req Name of domain to acknowledge transfer for (Unicode or ASCII format)

The outgoing transfers of certain domain suffixes can be aborted by the registrar currently managing the domain. In that case, a poll message will notify you about the requested transfer. Usually, if you do not send a domainTransferOutNack or domainTransferOutAck in a time period specified by the registry, the transfer out will automatically be approved.

To reject the transfer out, you can simply send a domainTransferOutNack request for the domain. Keep in mind that there are registry-specific restrictions which specify the permitted cases.

POST https://secure.hosting.de/api/domain/v1/jsonxml/domainTransferOutNack
{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "example.com"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>example.com</domainName>
</request>
RequestdomainTransferOutNack
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/domainTransferOutNack
Processingasynchronous
ResponseDomain object
Parameter Type Required Description
domainName string req Name of the domain to reject transfer for (Unicode or ASCII format)

If you want the outgoing transfer to proceed, you can explicitly send a domainTransferOutAck request to reduce the time until the transfer out is completed.

Restoring Deleted Domains

POST https://secure.hosting.de/api/domain/v1/jsonxml/domainRestore
{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "example.com"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>example.com</domainName>
</request>
RequestdomainRestore
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/domainRestore
Processingasynchronous
Response-
Parameter Type Required Description
domainName string req Name of the domain you want to restore (Unicode or ASCII format)

When a domain is in restorable state, you can restore it by using the domainRestore request.

Requesting Auth-Info2 (.de)

POST https://secure.hosting.de/api/domain/v1/jsonxml/domainCreateAuthInfo2
{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "example.com"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>example.com</domainName>
</request>
RequestdomainCreateAuthInfo2
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/domainCreateAuthInfo2
Processingasynchronous
Response-
Parameter Type Required Description
domainName string req Name of the domain that the auth-info 2 is requested for (Unicode or ASCII format)

For .de domains there is an additional transfer authorization password. DeNIC will send it via mail to the current domain owner. It can be requested by any registrar. If you want to initiate this process, you need to send a domainCreateAuthInfo2 request.

You can even send this request for domains that are not in your account.

Job Object

{
    "id": "150223248499677",
    "accountId": "15010100000001",
    "displayName": "example.org",
    "domainNameAce": "example.org",
    "domainNameUnicode": "example.org",
    "handle": "",
    "type": "domainTransferIn",
    "state": "error",
    "subState": "",
    "comments": "",
    "errors": "[{\"code\":30003,\"context\":\"example.org\",\"details\":[],\"text\":\"The provided Authinfo is wrong\"}]",
    "executionDate": "2015-02-23T17:39:23Z",
    "addDate": "2015-01-01T00:00:00Z",
    "lastChangeDate": "2015-01-01T00:00:00Z"
}
<job>
 <id>150223248499677</id>
 <accountId>1</accountId>
 <displayName>example.org</displayName>
 <domainNameAce>example.org</domainNameAce>
 <domainNameUnicode>example.org</domainNameUnicode>
 <handle></handle>
 <type>domainTransferIn</type>
 <state>error</state>
 <subState></subState>
 <comments></comments>
 <errors>[{"code":30003,"context":"example.org","details":[],"text":"The provided Authinfo is wrong"}]</errors>
 <executionDate>2015-02-23T17:39:23Z</executionDate>
 <addDate>2015-01-01T00:00:00Z</addDate>
 <lastChangeDate>2015-01-01T00:00:00Z</lastChangeDate>
</job>

Job Object

Property Type Required / Direction Description
id string out-only Job ID
accountId string out-only ID of account, the job was executed for (usually owner of the object the job belongs to)
type string out-only Type of job
displayName string out-only Either domainNameUnicode or handle, depending on which is set
domainNameAce string out-only Domain name in ACE format
domainNameUnicode string out-only Domain name in Unicode format
handle string out-only Contact Handle
state string out-only State of job
errors string out-only JSON encoded list of errors encountered while executing this job
clientTransactionId string out-only Client transaction ID used in request
serverTransactionId string out-only Server transaction ID created for request
executionDate datetime out-only Date and time job was or will be executed
addDate datetime out-only Date and time job object was created
lastChangeDate datetime out-only Date and time job was last modified

Listing Jobs

RequestjobsFind
Urlhttps://secure.hosting.de/api/domain/v1/jsonxml/jobsFind
Processingsynchronous
ResponseFindJobsResult

In order to list jobs, you use the generic filtering and sorting API with the jobsFind method. The response will contain a list of Job objects.

The following fields are available for filtering and sorting:

Field Description
AccountId Account ID associated with job
JobId ID of job
JobType Job type, e.g. domainCreate or contactUpdate
JobDisplayName May contain handle or domainNameUnicode (cf. Job object)
JobDomainName Domain name in ACE format
JobDomainNameUnicode Domain name in Unicode format
JobHandle Contact handle string
JobState State of job
JobSubState Substate of job
JobComments Comments of job
JobAddDate Date and time job was created
JobLastChangeDate Date and time job was last modified
JobExecutionDate Date and time job was or will be executed
JobClientTransactionId Client transaction ID used in request
JobServerTransactionId Server transaction ID created for request

DNS

The ZoneConfig Object

ZoneConfig Object

The ZoneConfig object defines a zone.

Property Type Required Description
id string see description ID of this zoneConfig. Ignored in zone create requests. Either id or name is required in all other requests.
accountId string out-only ID of the account that manages the zone. This property is never used in requests.
status string out-only Current status of the Zone
name string see description The zone name in ACE format. name is always required in zone create requests and all other requests if no id is provided. While you may use this property for a Unicode zone name, the responses will always contain the ACE encoded zone.
nameUnicode string opt The zone name in Unicode. If it is left empty it will be filled automatically based on name.
masterIp string see description A valid IPv4 or IPv6 must be provided if the type is SLAVE. If the type is NATIVE or MASTER the field must be empty.
type string req Valid types are NATIVE, MASTER, and SLAVE
emailAddress string opt The hostmaster email address. Only relevant if the type is NATIVE or MASTER. If the field is left empty, the default is hostmaster@name.
zoneTransferWhitelist list<string> opt List of IP addresses whitelisted for zone transfers. Only allowed if the type is MASTER. Must contain valid IPv4 or IPv6 addresses.
lastChangeDate datetime out-only Date and time the zone was last modified
soaValues SoaValues opt Values for the SOA record of the zone. If it is left empty an SOA record with default values will be created.
templateValues TemplateValues opt This property can be used if you want to create the zone with a template.

The Template Values Object

TemplateValues Object

The template values object can be used to create or recreate a zone using a template.

All record templates connected to the template will be converted into records for the zone. These record templates may contain placeholders. A replacement value has to be provided for each placeholder that is used in the template. Otherwise you will receive an error.

The zone may be tied to the used template. A zone that is tied to a template will receive updates automatically.

Cf. The Template Object for more details.

Property Type Required Description
templateId string opt ID of the template
templateName string out-only Name of the used template
tieToTemplate bool opt Tie the zone to the template
templateReplacements TemplateReplacements opt Replacement values for the placeholders

The Template Replacements Object

TemplateReplacements Object

The template replacements object is used for recreating and updating templates.

Whenever a template is changed, all zones that are tied to the template are changed as well. If, for example, you add a new record template that contains a placeholder that has not been used in the template before, the zones tied to the template might not have a replacement value for the placeholder.

In that case the replacement value provided with the Template Replacements Object will be used as a default.

Property Type Required Description
ipv4Replacement string opt
ipv6Replacement string opt
mailIpv4Replacement string opt
mailIpv6Replacement string opt

The SOA Values Object

SoaValues Object

The SOA values object contains the time (seconds) used in a zone’s SOA record. The maximum number of seconds is 31556926 which equals one year. Exceeding the maximum and uncercutting the minimum values will cause the request to be aborted and create an error.

Property Type Required Description
refresh int req Refresh for the SOA record. Default: 86400, minimum: 3600.
retry int req Retry for the SOA record. Default: 7200, minimum: 600.
expire int req Expire for the SOA record. Default: 3600000, minimum: 86400.
ttl int req TTL for the SOA record. Default: 172800, minimum: 60.
negativeTtl int req Negative TTL for the SOA record. Default: 3600, minimum: 60.

The Record Object

DnsRecord Object

The DNS Record object is part of a zone. It is used to manage DNS resource records.

Property Type Required Description
id string see description Record ID. Ignored in create zone requests. Either id or zoneId, name, type, and content are required in all other requests.
zoneId string out-only ID of zone that the record belongs to.
recordTemplateId string opt ID of record template the record is tied to. If empty, record has to be managed manually. If tied to record template, record will be removed or updated whenever record template is removed or updated.
name string see description Name of the record. Example: mail.example.com. Always required in create requests and in all other requests if no id is provided.
type string see description Type of the record. Valid types are A, AAAA, MX, NS, CNAME, PTR, and SRV. Always required in create requests and in all other requests if no id is provided.
content string see description Content of the record. Always required in create requests and in all other requests if no id is provided.
ttl int opt TTL of the record in seconds. Minimum value: 60. Maximum value: 31556926 (one year). Exceeding the maximum or undercutting the minimun value will abort the request and result in an error.
priority int opt Priority of record. Only relevant if type is MX or SRV. Must be positive.
lastChangeDate datetime out-only Date and time of last record modification

The Zone Object

Zone Object

A Zone consists of a Zone Configuration and a list of DNS records and represents the DNS zone.

A Zone object is the result of a zonesFind request.

Property Type Required Description
zoneConfig ZoneConfig out-only
records list<DnsRecord> out-only

List ZoneConfigs

POST https://secure.hosting.de/api/dns/v1/jsonxml/zoneConfigsFind
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "ZoneNameUnicode",
        "value": "*example.com*"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "ZoneNameUnicode",
        "order": "asc"
    }
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <item>
   <field>ZoneNameUnicode</field>
   <value>*example.com*</value>
  </item>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>ZoneNameUnicode</field>
  <order>asc</order>
 </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // zoneConfig objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindZoneConfigsResult"
    },
    ...
}
<response>
 <response>
  <data>
   ...
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindZoneConfigsResult</type>
 </response>
 ...
</response>
RequestzoneConfigsFind
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/zoneConfigsFind
Processingsynchronous
ResponseFindZoneConfigsResult

Listing zoneConfigs uses the generic filtering and sorting API with the method zoneConfigsFind. The response will contain a list of ZoneConfig objects.

The following fields are available for filtering and sorting:

Field Description
AccountId ID of the account that the zone belongs to
ZoneConfigId ZoneConfig object ID
ZoneName Zone name in ACE format
ZoneNameUnicode Zone name in Unicode format
ZoneMasterIp Master IP address of the zone
ZoneType Zone type (“MASTER”, “NATIVE”, or “SLAVE”)
ZoneEmailAddress Email address of hostmaster
ZoneLastChangeDate Date and time of last zone update
ZoneSoaRefresh SOA refresh interval of slaves (seconds)
ZoneSoaRetry SOA retry interval of slaves (seconds)
ZoneSoaExpire SOA deactivation timeout of slaves (seconds)
ZoneSoaTtl SOA time to live for negative caching (seconds)
ZoneIpv4Replacement Replacement value for ##IPv4## placeholder in template
ZoneIpv6Replacement Replacement value for ##IPv6## placeholder in template
ZoneMailIpv4Replacement Replacement value for ##IPv4## mail addresses in template
ZoneMailIpv6Replacement Replacement value for ##IPv6## mail addresses in template
TemplateName Name of template associated with zone
TemplateId ID of template associated with zone

Listing Records

POST https://secure.hosting.de/api/dns/v1/jsonxml/recordsFind
{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "zoneConfigId",
        "value": "15010100000010"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "recordName",
        "order": "asc"
    }
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <item>
   <field>zoneConfigId</field>
   <value>15010100000010</value>
  </item>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>recordName</field>
  <order>asc</order>
 </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // record objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindRecordsResult"
    },
    ...
}
<response>
 <response>
  <data>
   ...
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindRecordsResult</type>
 </response>
 ...
</response>
RequestrecordsFind
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/recordsFind
Processingsynchronous
ResponseFindRecordsResult

Listing DNS records uses the generic filtering and sorting API with the method recordsFind. The response will contain a list of record objects.

The following fields are available for filtering and sorting:

Field Description
ZoneConfigId ID of the zoneConfig object to which the record belongs
RecordId Record object ID
RecordName Name of the record
RecordType Type of the record
RecordContent Content of the record
RecordTtl Time to live (in seconds)
RecordPriority Priority of the record (integer)
RecordLastChangeDate Date and time of last modification

Listing Zones

POST https://secure.hosting.de/api/dns/v1/jsonxml/zonesFind
{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "accountId",
        "value": "150101000000001"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "zoneName",
        "order": "asc"
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <filter>
    <field>accountId</field>
    <value>150101000000001</value>
  </filter>
  <limit>10</limit>
  <page>1</page>
  <sort>
    <field>zoneName</field>
    <order>asc</order>
  </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // zone objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindZonesResult"
    },
    ...
}
<response>
 <response>
  <data>
   ...
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindZonesResult</type>
 </response>
 ...
</response>
RequestzonesFind
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/zonesFind
Processingsynchronous
ResponseFindZonesResult

Listing zones uses the generic filtering and sorting API with the method zonesFind. The response will contain a list of Zone Objects that consist of a zoneConfig and all its records.

The following fields are available for filtering and sorting:

Field Description
AccountId ID of the account to which the zone belongs
ZoneConfigId ID of the zoneConfig object
ZoneName Zone name in ACE format
ZoneNameUnicode Zone name in Unicode format
ZoneMasterIp Master IP address of the zone
ZoneType Zone type (“MASTER”, “NATIVE”, or “SLAVE”)
ZoneEmailAddress Email address of the zone
ZoneLastChangeDate Time and date of last modification
ZoneSoaRefresh SOA refresh interval of slaves (seconds)
ZoneSoaRetry SOA retry interval of slaves (seconds)
ZoneSoaExpire SOA deactivation timeout of slaves (seconds)
ZoneSoaTtl SOA time to live for negative caching (seconds)
ZoneIpv4Replacement Replacement value for IPv4 addresses in template
ZoneIpv6Replacement Replacement value for IPv6 addresses in template
ZoneMailIpv4Replacement Replacement value for IPv4 mail addresses in template
ZoneMailIpv6Replacement Replacement value for IPv6 mail addresses in template
TemplateName Name of template associated with zone
TemplateId ID of template associated with zone
RecordId ID of record in zone
RecordName Name of record in zone
RecordType Type of record in zone
RecordContent Content of record in zone
RecordTtl Time to live (in seconds)
RecordPriority Priority of record in zone (integer)
RecordLastChangedate Date and time of last modification in zone

Creating New Zones

POST https://secure.hosting.de/api/dns/v1/jsonxml/zoneCreate
{
    "authToken": "$$YOUR API KEY$$",
    "nameserverSetId": "15010100000020",
    "useDefaultNameserverSet": false,
    "zoneConfig": {
            "name": "example.com",
            "type": "NATIVE",
            "emailAddress": "admin@example.com"
    },
    "records": [
        {
            "name": "www.example.com",
            "type": "A",
            "content": "172.27.171.106",
            "ttl": 86000
        },
        {
            "name": "example.com",
            "type": "MX",
            "content": "smtp.example.com",
            "ttl": 86000
        }
    ]
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <nameserverSetId>15010100000020</nameserverSetId>
  <records>
    <item>
      <content>172.27.171.106</content>
      <name>www.example.com</name>
      <ttl>86000</ttl>
      <type>A</type>
    </item>
    <item>
      <content>smtp.example.com</content>
      <name>example.com</name>
      <ttl>86000</ttl>
      <type>MX</type>
    </item>
  </records>
  <useDefaultNameserverSet>false</useDefaultNameserverSet>
  <zoneConfig>
    <emailAddress>admin@example.com</emailAddress>
    <name>example.com</name>
    <type>NATIVE</type>
  </zoneConfig>
</request>
Response
{
    ...
    "response": {
        "records": [
            {
                "content": "172.27.171.106",
                "id": "15010100000020",
                "lastChangeDate": "2015-09-02",
                "name": "www.example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 86000,
                "type": "A",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "smtp.example.com",
                "id": "15010100000021",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": 0,
                "recordTemplateId": null,
                "ttl": 86000,
                "type": "MX",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "ns2.example.com",
                "id": "15010100000022",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "NS",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "ns1.example.com",
                "id": "15010100000023",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "NS",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "ns1.example.com. admin.example.com. 2015090201 86400 7200 3600000 172800",
                "id": "15010100000024",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "SOA",
                "zoneConfigId": "15010100000010"
            }
        ],
        "zoneConfig": {
            "accountId": "15010100000001",
            "emailAddress": "admin@example.com",
            "id": "15010100000010",
            "lastChangeDate": "2015-09-02T09:42:08Z",
            "masterIp": "",
            "name": "example.com",
            "nameUnicode": "example.com",
            "soaValues": {
                "expire": 3600000,
                "negativeTtl": 3600,
                "refresh": 86400,
                "retry": 7200,
                "serial": null,
                "ttl": 172800
            },
            "status": "blocked",
            "templateValues": null,
            "type": "NATIVE",
            "zoneTransferWhitelist": [
            ]
        }
    },
    ...
}
<response>
  ...
  <response>
    <records>
      <item>
        <content>172.27.171.106</content>
        <id>15010100000020</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>www.example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>86000</ttl>
        <type>A</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>smtp.example.com</content>
        <id>15010100000021</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority>0</priority>
        <recordTemplateId null="true" />
        <ttl>86000</ttl>
        <type>MX</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>ns2.example.com</content>
        <id>15010100000022</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>NS</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>ns1.example.com</content>
        <id>15010100000023</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>NS</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>ns1.example.com. admin.example.com. 2015090201 86400 7200 3600000 172800</content>
        <id>15010100000024</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>SOA</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
    </records>
    <zoneConfig>
      <accountId>15010100000001</accountId>
      <emailAddress>admin@example.com</emailAddress>
      <id>15010100000010</id>
      <lastChangeDate>2015-09-02T09:42:08Z</lastChangeDate>
      <masterIp />
      <name>example.com</name>
      <nameUnicode>example.com</nameUnicode>
      <soaValues>
        <expire>3600000</expire>
        <negativeTtl>3600</negativeTtl>
        <refresh>86400</refresh>
        <retry>7200</retry>
        <serial null="true" />
        <ttl>172800</ttl>
      </soaValues>
      <status>blocked</status>
      <templateValues null="true" />
      <type>NATIVE</type>
      <zoneTransferWhitelist />
    </zoneConfig>
  </response>
  ...
</response>
RequestzoneCreate
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/zoneCreate
Processingsynchronous
ResponseZone
Parameter Type Required Description
zoneConfig ZoneConfig req zoneConfig of the zone
records list<Record> req Records of the zone
nameserverSetId string opt NameserverSet to use for automatic creation of NS records. Default: 0
useDefaultNameserverSet bool opt Use your account’s default nameserver set. Default: false

To create a zone, you need at least a zoneConfig.

A zone may be created manually or from a template. If you want to use a template, you have to at least provide a template ID in the zoneConfig’s template values property. See template object for more details.

See NameserverSet object for more details on using nameserver sets.

Recreating Existing Zones

POST https://secure.hosting.de/api/dns/v1/jsonxml/zoneRecreate
{
    "authToken": "$$YOUR API KEY$$",
    "nameserverSetId": "15010100000020",
    "useDefaultNamserverSet": false,
    "zoneConfig": {
            "name": "example.com",
            "nameUnicode": "example.com",
            "type": "NATIVE",
            "emailAddress": "admin@example.com"
    },
    "records": [
        {
            "name": "www.example.com",
            "type": "A",
            "content": "172.27.171.106",
            "ttl": 86000
        },
        {
            "name": "example.com",
            "type": "MX",
            "content": "smtp.example.com",
            "ttl": 86000
        }
    ]
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <nameserverSetId>15010100000020</nameserverSetId>
  <records>
    <item>
      <content>172.27.171.106</content>
      <name>www.example.com</name>
      <ttl>86000</ttl>
      <type>A</type>
    </item>
    <item>
      <content>smtp.example.com</content>
      <name>example.com</name>
      <ttl>86000</ttl>
      <type>MX</type>
    </item>
  </records>
  <useDefaultNamserverSet>false</useDefaultNamserverSet>
  <zoneConfig>
    <emailAddress>admin@example.com</emailAddress>
    <name>example.com</name>
    <nameUnicode>example.com</nameUnicode>
    <type>NATIVE</type>
  </zoneConfig>
</request>
Response
{
    ...
    "response": {
        "records": [
            {
                "content": "ns1.example.com. admin.example.com. 2015090202 86400 7200 3600000 172800",
                "id": "15010100000020",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "SOA",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "ns1.example.com",
                "id": "15010100000021",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "NS",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "ns2.example.com",
                "id": "15010100000022",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "NS",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "smtp.example.com",
                "id": "15010100000023",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": 0,
                "recordTemplateId": null,
                "ttl": 86000,
                "type": "MX",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "172.27.171.106",
                "id": "15010100000024",
                "lastChangeDate": "2015-09-02",
                "name": "www.example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 86000,
                "type": "A",
                "zoneConfigId": "15010100000010"
            }
        ],
        "zoneConfig": {
            "accountId": "15010100000001",
            "emailAddress": "admin@example.com",
            "id": "15010100000010",
            "lastChangeDate": "2015-09-02T09:50:48Z",
            "masterIp": "",
            "name": "example.com",
            "nameUnicode": "example.com",
            "soaValues": {
                "expire": 3600000,
                "negativeTtl": 3600,
                "refresh": 86400,
                "retry": 7200,
                "serial": null,
                "ttl": 172800
            },
            "status": "blocked",
            "templateValues": null,
            "type": "NATIVE",
            "zoneTransferWhitelist": [
            ]
        }
    },
    ...
}
<response>
  ...
  <response>
    <records>
      <item>
        <content>ns1.example.com. admin.example.com. 2015090202 86400 7200 3600000 172800</content>
        <id>15010100000020</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>SOA</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>ns1.example.com</content>
        <id>15010100000021</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>NS</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>ns2.example.com</content>
        <id>15010100000022</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>NS</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>smtp.example.com</content>
        <id>15010100000023</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority>0</priority>
        <recordTemplateId null="true" />
        <ttl>86000</ttl>
        <type>MX</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>172.27.171.106</content>
        <id>15010100000024</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>www.example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>86000</ttl>
        <type>A</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
    </records>
    <zoneConfig>
      <accountId>15010100000001</accountId>
      <emailAddress>admin@example.com</emailAddress>
      <id>15010100000010</id>
      <lastChangeDate>2015-09-02T09:50:48Z</lastChangeDate>
      <masterIp />
      <name>example.com</name>
      <nameUnicode>example.com</nameUnicode>
      <soaValues>
        <expire>3600000</expire>
        <negativeTtl>3600</negativeTtl>
        <refresh>86400</refresh>
        <retry>7200</retry>
        <serial null="true" />
        <ttl>172800</ttl>
      </soaValues>
      <status>blocked</status>
      <templateValues null="true" />
      <type>NATIVE</type>
      <zoneTransferWhitelist />
    </zoneConfig>
  </response>
  ...
</response>
RequestzoneRecreate
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/zoneRecreate
Processingsynchronous
ResponseZone
Parameter Type Required Description
zoneConfig zoneConfig object req ZoneConfig of the zone you want to recreate
records list<Record> req New records of the zone
nameserverSetId string opt NameserverSet to use for automatic creation of NS records. Default: 0
useDefaultNameserverSet bool opt Use your accounts default nameserver set. Default: false

Recreating an existing zone will cause it (ie. the zoneConfig and all records) to be deleted and then created anew with the values and records provided with the request. That means, the zoneConfig has to exist. Calling zoneRecreate with a zoneConfig that does not exist will result in an error.

As in creating a zone, a template may be used. Cf. template object for more details.

See NameserverSet object for more details on using NameserverSets.

Updating Zones

POST https://secure.hosting.de/api/dns/v1/jsonxml/zoneUpdate
{
    "authToken": "$$YOUR API KEY$$",
    "zoneConfig": {
        "name": "example.com"
    },
    "recordsToAdd": [
        {
            "name": "www.example.com",
            "type": "AAAA",
            "content": "2001:db8::1",
            "ttl": 86000
        },
        {
            "name": "example.com",
            "type": "MX",
            "content": "newmailserver.example.com",
            "ttl": 86000
        }
    ],
    "recordsToDelete": [
        {
            "name": "example.com",
            "type": "MX",
            "content": "smtp.example.com"
        }
    ]
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <recordsToAdd>
    <item>
      <content>2001:db8::1</content>
      <name>www.example.com</name>
      <ttl>86000</ttl>
      <type>AAAA</type>
    </item>
    <item>
      <content>newmailserver.example.com</content>
      <name>example.com</name>
      <ttl>86000</ttl>
      <type>MX</type>
    </item>
  </recordsToAdd>
  <recordsToDelete>
    <item>
      <content>smtp.example.com</content>
      <name>example.com</name>
      <type>MX</type>
    </item>
  </recordsToDelete>
  <zoneConfig>
    <name>example.com</name>
  </zoneConfig>
</request>
Response
{
    ...
    "response": {
        "records": [
            {
                "content": "ns1.example.com",
                "id": "15010100000020",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "NS",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "ns1.example.com. admin.example.com. 2015090203 86400 7200 3600000 172800",
                "id": "150902246197317",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "SOA",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "ns2.example.com",
                "id": "15010100000021",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "NS",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "2001:db8::1",
                "id": "15010100000022",
                "lastChangeDate": "2015-09-02",
                "name": "www.example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 86000,
                "type": "AAAA",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "newmailserver.example.com",
                "id": "15010100000023",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": 0,
                "recordTemplateId": null,
                "ttl": 86000,
                "type": "MX",
                "zoneConfigId": "15010100000010"
            }
        ],
        "zoneConfig": {
            "accountId": "15010100000001",
            "emailAddress": "admin@example.com",
            "id": "15010100000010",
            "lastChangeDate": "2015-09-02T10:14:02Z",
            "masterIp": "",
            "name": "example.com",
            "nameUnicode": "example.com",
            "soaValues": {
                "expire": 3600000,
                "negativeTtl": 3600,
                "refresh": 86400,
                "retry": 7200,
                "serial": null,
                "ttl": 172800
            },
            "status": "blocked",
            "templateValues": null,
            "type": "NATIVE",
            "zoneTransferWhitelist": [
            ]
        }
    },
    ...
}
<response>
 ...
  <response>
    <records>
      <item>
        <content>ns1.example.com</content>
        <id>15010100000020</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>NS</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>ns1.example.com. admin.example.com. 2015090203 86400 7200 3600000 172800</content>
        <id>150902246197317</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>SOA</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>ns2.example.com</content>
        <id>15010100000021</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>NS</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>2001:db8::1</content>
        <id>15010100000022</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>www.example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>86000</ttl>
        <type>AAAA</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>newmailserver.example.com</content>
        <id>15010100000023</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority>0</priority>
        <recordTemplateId null="true" />
        <ttl>86000</ttl>
        <type>MX</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
    </records>
    <zoneConfig>
      <accountId>15010100000001</accountId>
      <emailAddress>admin@example.com</emailAddress>
      <id>15010100000010</id>
      <lastChangeDate>2015-09-02T10:14:02Z</lastChangeDate>
      <masterIp />
      <name>example.com</name>
      <nameUnicode>example.com</nameUnicode>
      <soaValues>
        <expire>3600000</expire>
        <negativeTtl>3600</negativeTtl>
        <refresh>86400</refresh>
        <retry>7200</retry>
        <serial null="true" />
        <ttl>172800</ttl>
      </soaValues>
      <status>blocked</status>
      <templateValues null="true" />
      <type>NATIVE</type>
      <zoneTransferWhitelist />
    </zoneConfig>
  </response>
  ...
</response>
RequestzoneUpdate
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/zoneUpdate
Processingsynchronous
ResponseZone
Parameter Type Required Description
zoneConfig zoneConfig object req zoneConfig to be updated
recordsToAdd list<Record> req Records to be added
recordsToDelete list<Record> req Records to be deleted

You can use zoneUpdate to make adjustments to the zone’s zoneConfig, to remove records, or to add new records. All records in recordsToAdd will be added to the zone, while all records in recordsToDelete will be deleted. If you insert a record that does not exist into recordsToDelete, an error will occur.

Existing records that are not contained in either list will not be changed. So, in order to make adjustments to a record, the original record has to be contained in recordsToDelete and the adjusted version in recordsToAdd.

Deleting Zones

POST https://secure.hosting.de/api/dns/v1/jsonxml/zoneDelete
{
    "authToken": "$$YOUR API KEY$$",
    "zoneConfigId": "15010100000010"
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <zoneConfigId>15010100000010</zoneConfigId>
</request>
Response
{
    ...
    "status": "success",
    ...
}
...
    <status>success</status>
    ...
RequestzoneDelete
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/zoneDelete
Processingsynchronous
Responseempty
Parameter Type Required Description
zoneConfigId string opt ID of ZoneConfig to be deleted
zoneConfigName string opt Name of ZoneConfig to be deleted

The complete zone, ie. the zoneConfig and all records, will be deleted. Either the ID or the name has to be provided. If both are set, an error will be returned.

Changing Content of Records

POST https://secure.hosting.de/api/dns/v1/jsonxml/changeContent
{
    "authToken": "$$YOUR API KEY$$",
    "recordType": "MX",
    "oldContent": "mail.mailserver.com",
    "newContent": "mail.smtpservice.com",
    "includeTemplates": false,
    "includeSubAccounts": true
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <includeSubAccounts>true</includeSubAccounts>
  <includeTemplates>false</includeTemplates>
  <newContent>mail.smtpservice.com</newContent>
  <oldContent>mail.mailserver.com</oldContent>
  <recordType>MX</recordType>
</request>
Response
{
    ...
    "status": "success",
    ...
}
...
    <status>success</status>
    ...
RequestchangeContent
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/changeContent
Processingasynchronous
Responseempty
Parameter Type Required Description
recordType string req Type of the records to be changed
oldContent string req Search string for record content
newContent string req Replacement content
includeTemplates bool req Replace content of matching record templates as well
includeSubAccounts bool req Replace values in records of zones belonging to subaccounts

changeContent is a tool for bulk updates to multiple zones.

An example: You use the same mailserver for all your zones and it changed. Instead of performing an update of each zone you just use changeContent with the recordType set to MX, oldContent to the old mailserver, and newContent to the new one.

The change will affect all zones with records that match the recordType and oldContent, but no records that were created with templates. If you want those records and their record templates to be affected as well, you just need to set includeTemplates to true.

If includeSubAccounts is true, the change will affect all matching zones managed by your account and the respective subaccounts as well.

Please note that changeContent is currently asynchronous and may take several minutes, depending on how many zones contain a matching record.

Untying Zones From Their Templates

POST https://secure.hosting.de/api/dns/v1/jsonxml/zonesUntieFromTemplates
{
    "authToken": "$$YOUR API KEY$$",
    "zoneConfigIds": [
        "15010100000010"
    ]
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <zoneConfigIds>
    <item>15010100000010</item>
  </zoneConfigIds>
</request>
Response
{
    ...
    "status": "success",
    ...
}
...
    <status>success</status>
    ...
RequestzonesUntieFromTemplates
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/zonesUntieFromTemplates
Processingsynchronous
Responseempty
Parameter Type Required Description
zoneConfigIds string req IDs of ZoneConfigs to be detached
zoneConfigNames string req Names of ZoneConfigs to be detached

This will untie a zone from the template it was created from. Afterwards, changes to the template will not affect the zone any longer. Cf. template object for more details.

Either the ID list or the name list has to be provided. If both are set, an error will be returned.

Tying Zones to Templates

POST https://secure.hosting.de/api/dns/v1/jsonxml/zonesTieToTemplates
{
    "authToken": "$$YOUR API KEY$$",
    "zoneConfigIds": [
        "15010100000010"
    ]
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <zoneConfigIds>
    <item>15010100000010</item>
  </zoneConfigIds>
</request>
Response
{
    ...
    "status": "success",
    ...
}
...
    <status>success</status>
    ...
RequestzonesTieToTemplates
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/zonesTieToTemplates
Processingsynchronous
Responseempty
Parameter Type Required Description
zoneConfigIds string req IDs of ZoneConfigs to be detached
zoneConfigNames string req Names of ZoneConfigs to be detached

This will tie a zone to a template. Afterwards all changes to the template will affect the zone. Cf. template object for more details.

New records will be created for all record templates that belong to the template. Should one of these records and an already existing record be identical (i.e. name, type, and content are equal), the old record will be deleted. Either the ID list or the name list has to be provided. If both are set, an error will be returned.

NameserverSet Object

{
    "id": "",
    "accountId": "",
    "name": "Server 1",
    "defaultNameserverSet": false,
    "nameservers": ["ns1.example.com", "ns2.example.com"]
}
<request>
  <accountId />
  <defaultNameserverSet>false</defaultNameserverSet>
  <id />
  <name>Server 1</name>
  <nameservers>
    <item>ns1.example.com</item>
    <item>ns2.example.com</item>
  </nameservers>
</request>

NameserverSet Object

The NameserverSet object is used to manage NameserverSets.

NameserverSets serve a similar purpose to templates: You can create sets for different name server configurations. Then only the ID of the name server set you wish to use for your NS records is needed when creating or recreating a zone. This means you do not need to create the NS records manually.

When you create or recreate a Zone there are two relevant parameters: nameserverSetId and useDefaultNameserverSet.

If useDefaultNameserverSet is set to true, you do not need to provide a nameserverSetId. If you still provide the ID, it will be ignored and the NameserverSet that is marked as default will be used.

If useDefaultNameserverSet is set to false, you may provide a nameserverSetId. If you do so, the NameserverSet with that ID will be used.

If useDefaultNameserverSet is set to false and you do not provide a nameserverSetId or set it to 0, no NameserverSet will be used. In that case, you have to provide at least two NS records for the zone.

Property Type Required Description
id string out-only NameserverSet ID. Ignored in NameserverSet create requests.
accountId string out-only ID of account managing NameserverSet
name string req Name NameserverSet
defaultNameserverSet bool opt If true, this set will be used
nameservers list <string> req List of all name servers in the set. The first entry will be used as primary for the SOA record. Must contain at least two entries.

List Nameserver Sets

POST https://secure.hosting.de/api/dns/v1/jsonxml/nameserverSetsFind
{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "nameserverSetName",
        "value": "my nameserver set"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "nameserverSetName",
        "order": "asc"
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <filter>
    <field>nameserverSetName</field>
    <value>my nameserver set</value>
  </filter>
  <limit>10</limit>
  <page>1</page>
  <sort>
    <field>nameserverSetName</field>
    <order>asc</order>
  </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // nameserver set objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindNameserverSetsResult"
    },
    ...
}
<response>
  <response>
    <data>
        // nameserver set objects
    </data>
    <limit>10</limit>
    <page>1</page>
    <totalEntries>15</totalEntries>
    <totalPages>2</totalPages>
    <type>FindNameserverSetsResult</type>
  </response>
</request>
RequestnameserverSetsFind
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/nameserverSetsFind
Processingsynchronous
ResponseFindNameserverSetsResult

Listing NameserverSets uses the generic filtering and sorting API with the method nameserverSetsFind. The response will contain a list of NameserverSet objects.

The following fields are available for filtering and sorting:

Field Description
AccountId ID of account managing NameserverSet
NameserverSetId ID of NameserverSet object
NameserverSetName Name of NameserverSet
NameserverSetDefaultNameserverSet True, if default NameserverSet is used (boolean)

Creating NameserverSet

POST https://secure.hosting.de/api/dns/v1/jsonxml/nameserverSetCreate
{
    "authToken": "$$YOUR API KEY$$",
    "nameserverSet": {
        "name": "Server 1",
        "defaultNameserverSet": false,
        "nameservers": ["ns1.example.com", "ns2.example.com"]
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <nameserverSet>
    <defaultNameserverSet>false</defaultNameserverSet>
    <name>Server 1</name>
    <nameservers>
      <item>ns1.example.com</item>
      <item>ns2.example.com</item>
    </nameservers>
  </nameserverSet>
</request>
Response
{
    ...
    "response": {
        "accountId": "15010100000001",
        "defaultNameserverSet": false,
        "id": "15010100000010",
        "name": "Server 1",
        "nameservers": ["ns1.example.com", "ns2.example.com"]
    },
    ...
}
<response>
  <response>
    <accountId>15010100000001</accountId>
    <defaultNameserverSet>false</defaultNameserverSet>
    <id>15010100000010</id>
    <name>Server 1</name>
    <nameservers>
      <item>ns1.example.com</item>
      <item>ns2.example.com</item>
    </nameservers>
  </response>
</request>
RequestnameserverSetCreate
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/nameserverSetCreate
Processingsynchronous
ResponseNameserverSet
Parameter Type Required Description
nameserverSet NameserverSet req NameserverSet object to be created

Creates a new NameserverSet.

Updating NameserverSets

POST https://secure.hosting.de/api/dns/v1/jsonxml/nameserverSetUpdate
{
    "authToken": "$$YOUR API KEY$$",
    "nameserverSet": {
        "name": "Server 1",
        "defaultNameserverSet": true,
        "nameservers": ["ns1.example.com", "ns2.example.com"]
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <nameserverSet>
    <defaultNameserverSet>true</defaultNameserverSet>
    <name>Server 1</name>
    <nameservers>
      <item>ns1.example.com</item>
      <item>ns2.example.com</item>
    </nameservers>
  </nameserverSet>
</request>
Response
{
    ...
    "response": {
        "accountId": "15010100000001",
        "defaultNameserverSet": true,
        "id": "15010100000010",
        "name": "Server 1",
        "nameservers": ["ns1.example.com", "ns2.example.com"]
    },
    ...
}
<response>
  <response>
    <accountId>15010100000001</accountId>
    <defaultNameserverSet>false</defaultNameserverSet>
    <id>15010100000010</id>
    <name>Server 1</name>
    <nameservers>
      <item>ns1.example.com</item>
      <item>ns2.example.com</item>
    </nameservers>
  </response>
</request>
RequestnameserverSetUpdate
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/nameserverSetUpdate
Processingsynchronous
ResponseNameserverSet
Parameter Type Required Description
nameserverSet NameserverSet req NameserverSet object to be updated

Updates an existing NameserverSet. If the set does not exist, an error will be returned.

Deleting NameserverSets

POST https://secure.hosting.de/api/dns/v1/jsonxml/nameserverSetDelete
{
    "authToken": "$$YOUR API KEY$$",
    "nameserverSetId": "15010100000010"
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <nameserverSetId>15010100000010</nameserverSetId>
</request>
Response
{
    ...
    "status": "success",
    ...
}
...
    <status>success</status>
    ...
RequestnameserverSetDelete
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/nameserverSetDelete
Processingsynchronous
Responseempty
Parameter Type Required Description
nameserverSetId string req ID of NameserverSet to be deleted

Deletes an existing NameserverSet. If the set does not exist, an error will be returned.

Getting Default NameserverSet

POST https://secure.hosting.de/api/dns/v1/jsonxml/nameserverSetGetDefault
{
    "authToken": "$$YOUR API KEY$$"
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
</request>
Response
{
    ...
    "response": {
        "accountId": "15010100000001",
        "defaultNameserverSet": true,
        "id": "15010100000010",
        "name": "Default",
        "nameservers": ["ns1.example.com", "ns2.example.com"]
    },
    ...
}
<response>
  <response>
    <accountId>15010100000001</accountId>
    <defaultNameserverSet>true</defaultNameserverSet>
    <id>15010100000010</id>
    <name>Default</name>
    <nameservers>
      <item>ns1.example.com</item>
      <item>ns2.example.com</item>
    </nameservers>
  </response>
</request>
RequestnameserverSetGetDefault
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/nameserverSetGetDefault
Processingsynchronous
ResponseNameserverSet

No specific parameters need to be passed.

This returns the NameserverSet that is used whenever you do not provide a specific NameserverSet ID while creating a zone.

The Template Object

Template Object

The template itself is a simple object only consisting of a name. However, templates are a powerful tool for creating and mass updating zones - quickly and easily.

There are two ways to create or recreate a zone. You can either create the zone by providing a zoneConfig and a list of records - without any template values. Or you can use a template.

To use a template, you have to at least set the templateId property of the zoneConfig’s template values property. That will cause all record templates attached to the template to be converted into DNS records. Thus enabling you to create a full zone without providing a single record in the zoneCreate call.

Tying Zones to Templates

A zone may be tied to a template, determined by the tieToTemplate property of the zoneConfig’s template values.


Whenever a template is updated, the respective zones will also receive updates. This means:

A zone that is not tied to a template will not change when its respective template is updated.

If you change your mind, you do not need to recreate the zone. Instead, you can use zoneUntieFromTemplate to detach a zone from its template.

Placeholders

Placeholders are a crucial feature of the template system. There are five different placeholders you can use:


##NAME##, ##IPV4##, ##IPV6##, ##MX_IPV4##, and ##MX_IPV6##.

##NAME## will automatically be replaced with the name property of the zoneConfig. It may be used in the name and content properties of record templates. A record template with the type MX could, for example, have the name mail.##NAME##.

##IPV4##, ##IPV6##, ##MX_IPV4## and ##MX_IPV6## may only be used in the content property of record templates. Most commonly ##IPV4## is used for A records, ##IPV6## for AAAA records, and ##MX_IPV4## and ##MX_IPV6## to create target hostnames for MX records. However, usage is not restricted to a certain type.


Using these four placeholders requires replacement values. Not providing a replacement value for a placeholder when creating or recreating a zone from a template, will result in an error.

The replacement values have to be set in their respective properties in the template values object and they have to be valid according to their usage. For example, when your AAAA record template contains the ##IPV6## placeholder, the IPv6 replacement value has to be a valid IPv6 address.

As not all replacement values have to be set when you create a zone from a template, you may provide a template replacements object when recreating or updating a template.

This is necessary if you add a record template using a placeholder that has not been used before. Not all zones tied to the template might have a replacement value for the new placeholder. In that case, the replacement value from the template replacements object will be used as a default.

Property Type Required Description
id string see description ID of this template. Ignored in template create requests. Either ID or name is required in all other requests.
accountId string out-only ID of template managing account
name string req Freely chosen name. It has to be unique within the account.

The Template Replacements Object

TemplateReplacements Object

The template replacements object is used for recreating and updating templates.

Whenever a template is changed, all zones that are tied to the template are changed as well. If, for example, you add a new record template that contains a placeholder that has not been used in the template before, the zones tied to the template might not have a replacement value for the placeholder.

In that case the replacement value provided with the Template Replacements Object will be used as a default.

Property Type Required Description
ipv4Replacement string opt
ipv6Replacement string opt
mailIpv4Replacement string opt
mailIpv6Replacement string opt

The Record Template Object

RecordTemplate Object

Record templates are part of a template.

When you create a zone with a template, each of its RecordTemplates will be converted into a record. Updating a template and adding RecordTemplates will cause converted records to be added to all zones that are tied to the template.

Cf. template object for more details.

Property Type Required Description
id string cf. description RecordTemplate ID. Ignored in RecordTemplate create requests. Either id or templateId, name, type, and content are required in all other requests.
templateId string cf. description ID of template, the RecordTemplate is connected to. Required in non-create requests, if no id is provided.
name string cf. description Name for records created from RecordTemplate. It may contain the ##NAME## placeholder which will be replaced with zone name of zone created from template.
Example: mail.##NAME## may result in mail.example.com
type string cf. description Type for records created from RecordTemplate. Valid types are A, AAAA, MX, NS, CNAME, PTR, SRV
content string cf. description Content for records created from RecordTemplate. If the type is A, the ##IPV4## or ##MX_IPV4## placeholder may be used instead of a specific IPv4. If the type is AAAA, the ##IPV6## or ##MX_IPV6## placeholder may be used instead of a specific IPv6.
ttl int opt TTL for records created from RecordTemplate. Minimum value: 60. Less will result in a warning and the TTL will be corrected to the minimum. Maximum value: 31556926 (one year). Exceeding the maximum or undercutting the minimum value will cause the request to be aborted and result in an error.
priority int opt Priority for the records created from this RecordTemplate. Only relevant if the type is MX or SRV. Must be positive.

Listing Templates

POST https://secure.hosting.de/api/dns/v1/jsonxml/templatesFind
{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "accountId",
        "value": "150101000000001"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "templateName",
        "order": "asc"
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <filter>
    <field>accountId</field>
    <value>150101000000001</value>
  </filter>
  <limit>10</limit>
  <page>1</page>
  <sort>
    <field>templateName</field>
    <order>asc</order>
  </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // template objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindTemplatesResult"
    },
    ...
}
<response>
  ...
  <response>
    <data>
        // template objects
    </data>
    <limit>10</limit>
    <page>1</page>
    <totalEntries>15</totalEntries>
    <totalPages>2</totalPages>
    <type>FindTemplatesResult</type>
  </response>
  ...
</request>
RequesttemplatesFind
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/templatesFind
Processingsynchronous
ResponseFindTemplatesResult

Listing templates uses the generic filtering and sorting API with the method templatesFind. The response will contain a list of template objects.

The following fields are available for filtering and sorting:

Field Description
AccountId ID of the account managing template
TemplateId Template object ID
TemplateName Name of the template

Listing Record Templates

POST https://secure.hosting.de/api/dns/v1/jsonxml/recordTemplatesFind
{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "templateId",
        "value": "15010100000010"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "recordTemplateName",
        "order": "asc"
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <filter>
    <field>templateId</field>
    <value>15010100000010</value>
  </filter>
  <limit>10</limit>
  <page>1</page>
  <sort>
    <field>recordTemplateName</field>
    <order>asc</order>
  </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // record template objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindRecordTemplatesResult"
    },
    ...
}
<response>
  ...
  <response>
    <data>
        // record template objects
    </data>
    <limit>10</limit>
    <page>1</page>
    <totalEntries>15</totalEntries>
    <totalPages>2</totalPages>
    <type>FindRecordTemplatesResult</type>
  </response>
  ...
</request>
RequestrecordTemplatesFind
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/recordTemplatesFind
Processingsynchronous
ResponseFindRecordTemplatesResult

Listing template records uses the generic filtering and sorting API with the method recordTemplatesFind. The response will contain a list of template record objects.

The following fields are available for filtering and sorting:

Field Description
TemplateId ID of template object to which template record belongs
RecordTemplateId ID of template record object
RecordTemplateName Name of template record
RecordTemplateType Type of template record
RecordTemplateContent Content of template record
RecordTemplateTtl Time until template record is live (in seconds)
RecordTemplatePriority Priority of the template record (integer)

Creating Templates

POST https://secure.hosting.de/api/dns/v1/jsonxml/templateCreate
{
    "authToken": "$$YOUR API KEY$$",
    "dnsTemplate": {
        "name": "example template"
    },
    "recordTemplates": [
        {
            "name": "##DOMAIN##",
            "type": "A",
            "content": "##IPV4##",
            "ttl": 10000
        },
        {
            "name": "mail.##DOMAIN##",
            "type": "AAAA",
            "content": "##MX_IPV6##",
            "ttl": 10000,
            "priority": 10
        }
    ]
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <dnsTemplate>
    <name>example template</name>
  </dnsTemplate>
  <recordTemplates>
    <item>
      <content>##IPV4##</content>
      <name>##DOMAIN##</name>
      <ttl>10000</ttl>
      <type>A</type>
    </item>
    <item>
      <content>##MX_IPV6##</content>
      <name>mail.##DOMAIN##</name>
      <priority>10</priority>
      <ttl>10000</ttl>
      <type>AAAA</type>
    </item>
  </recordTemplates>
</request>
Response
{
    ...
    "response": {
        "id": "150101000000010",
        "accountId": "150101000000001",
        "name": "example template"
    },
    ...
}
<response>
  ...
  <response>
    <accountId>150101000000001</accountId>
    <id>150101000000010</id>
    <name>example template</name>
  </response>
  ...
</request>
RequesttemplateCreate
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/templateCreate
Processingsynchronous
ResponseTemplate
Parameter Type Required Description
dnsTemplate Template req Template to be created
recordTemplates list<RecordTemplate> req Record templates to be created and associated with template

Creates a new template. Please cf. the template object for more details on how to use templates.

Recreating Templates

POST https://secure.hosting.de/api/dns/v1/jsonxml/templateRecreate
{
    "authToken": "$$YOUR API KEY$$",
    "clientTransactionId": "",
    "dnsTemplate": {
        "name": "example template"
    },
    "recordTemplates": [
        {
            "name": "##DOMAIN##",
            "type": "A",
            "content": "##IPV4##",
            "ttl": 10000
        },
        {
            "name": "mail.##DOMAIN##",
            "type": "AAAA",
            "content": "##MX_IPV6##",
            "ttl": 10000,
            "priority": 10
        }
    ],
    "replacements": {
        "ipv4Replacement": "123.1.2.3",
        "ipv6Replacement": "2001:db8::2",
        "mailIpv4Replacement": "123.1.2.4",
        "mailIpv6Replacement": "2001:db8::1"
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <clientTransactionId />
  <dnsTemplate>
    <name>example template</name>
  </dnsTemplate>
  <recordTemplates>
    <item>
      <content>##IPV4##</content>
      <name>##DOMAIN##</name>
      <ttl>10000</ttl>
      <type>A</type>
    </item>
    <item>
      <content>##MX_IPV6##</content>
      <name>mail.##DOMAIN##</name>
      <priority>10</priority>
      <ttl>10000</ttl>
      <type>AAAA</type>
    </item>
  </recordTemplates>
  <replacements>
    <ipv4Replacement>123.1.2.3</ipv4Replacement>
    <ipv6Replacement>2001:db8::2</ipv6Replacement>
    <mailIpv4Replacement>123.1.2.4</mailIpv4Replacement>
    <mailIpv6Replacement>2001:db8::1</mailIpv6Replacement>
  </replacements>
</request>
Response
{
    ...
    "response": {
        "id": "15010100000010",
        "accountId": "150101000000001",
        "name": "example template"
    },
    ...
}
<response>
  ...
  <response>
    <accountId>150101000000001</accountId>
    <id>15010100000010</id>
    <name>example template</name>
  </response>
  ...
</request>
RequesttemplateRecreate
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/templateRecreate
Processingasynchronous
ResponseTemplate
Parameter Type Required Description
dnsTemplate Template req Template to be recreated
recordTemplates list<RecordTemplate> req Record templates to be recreated and connected with template
replacements TemplateReplacements opt Replacement values

Recreates an existing template. An error will be returned if the template does not exist.

Updating Templates

POST https://secure.hosting.de/api/dns/v1/jsonxml/templateUpdate
{
    "authToken": "$$YOUR API KEY$$",
    "clientTransactionId": "",
    "dnsTemplate": {
        "name": "example template"
    },
    "recordTemplatesToAdd": [
        {
            "name": "##DOMAIN##",
            "type": "AAAA",
            "content": "##IPV6##",
            "ttl": 3600
        }
    ],
    "recordTemplatesToDelete": [
        {
            "name": "mail.##DOMAIN##",
            "type": "AAAA",
            "content": "##MX_IPV6##"
        }
    ],
    "replacements": {
        "ipv4Replacement": "123.1.2.3",
        "ipv6Replacement": "2001:db8::2",
        "mailIpv4Replacement": "123.1.2.4",
        "mailIpv6Replacement": "2001:db8::1"
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <clientTransactionId />
  <dnsTemplate>
    <name>example template</name>
  </dnsTemplate>
  <recordTemplatesToAdd>
    <item>
      <content>##IPV6##</content>
      <name>##DOMAIN##</name>
      <ttl>3600</ttl>
      <type>AAAA</type>
    </item>
  </recordTemplatesToAdd>
  <recordTemplatesToDelete>
    <item>
      <content>##MX_IPV6##</content>
      <name>mail.##DOMAIN##</name>
      <type>AAAA</type>
    </item>
  </recordTemplatesToDelete>
  <replacements>
    <ipv4Replacement>123.1.2.3</ipv4Replacement>
    <ipv6Replacement>2001:db8::2</ipv6Replacement>
    <mailIpv4Replacement>123.1.2.4</mailIpv4Replacement>
    <mailIpv6Replacement>2001:db8::1</mailIpv6Replacement>
  </replacements>
</request>
Response
{
    ...
    "response": {
        "id": "15010100000010",
        "accountId": "150101000000001",
        "name": "example template"
    },
    ...
}
<response>
  ...
  <response>
    <accountId>150101000000001</accountId>
    <id>15010100000010</id>
    <name>example template</name>
  </response>
  ...
</request>
RequesttemplateUpdate
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/templateUpdate
Processingasynchronous
ResponseTemplate
Parameter Type Required Description
dnsTemplate Template req Template to be updated
recordTemplatesToAdd list<RecordTemplate> req Record templates to be added to template
recordTemplatesToDelete list<RecordTemplate> req Record templates to be removed from template
replacements TemplateReplacements opt New replacement values

Updates an existing template. If the template does not exist, an error will be returned.

Deleting Templates

POST https://secure.hosting.de/api/dns/v1/jsonxml/templateDelete
{
    "authToken": "$$YOUR API KEY$$",
    "clientTransactionId": "",
    "templateId": "15010100000010"
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <clientTransactionId />
  <templateId>15010100000010</templateId>
</request>
Response
{
    ...
    "status": "success",
    ...
}

RequesttemplateDelete
Urlhttps://secure.hosting.de/api/dns/v1/jsonxml/templateDelete
Processingsynchronous
Responseempty
Parameter Type Required Description
templateId string req ID of template to be deleted
templateName string opt Name of the template to be deleted

Deletes an existing template and all record templates connected to it. If both ID and Name are set, the template does not exist, or zones are tied to the template, an error will be returned.

SSL

The SSL part of the API allows you to order, renew, or revoke SSL certificates.

Certificates fall in three different categories: domain validated, organization validated, and extended validated certificates.

Typical Workflow

Available SSL Products

Supplier Product Validity Periods (months) Order Object Additional Domain Names
GeoTrust QuickSSLPremium 12, 24, 36 DomainValidatedOrder -
GeoTrust QuickSSLPremium SAN 12, 24, 36 DomainValidatedOrder 4 subdomain names
GeoTrust RapidSSL 12, 24, 36 DomainValidatedOrder -
GeoTrust RapidSSL Wildcard 12, 24, 36 DomainValidatedOrder -
GeoTrust TrueBizId 12, 24, 36 OrganizationValidatedOrder 100
GeoTrust TrueBizId Wildcard 12, 24, 36 OrganizationValidatedOrder -
GeoTrust TrueBizIdEv 12, 24 ExtendedValidatedOrder 100

The Order Object

You use the order object for viewing existing orders only. You cannot order SSL certificates by using this object.

Order Object

Property Type Required Description
id string req order ID
accountId string req ID of order managing account. Never used in requests.
productCode string req Product name of SSL certificate. E.g. RapidSSL
supplier string req Supplier brand, usually GeoTrust
commonName string req Common name extracted from CSR or SSL certificate
validitySpanMonth int req Requested validity period of certificate in months
orderStatus string req Current order status
validationType string req Can be validateViaEmail, validateViaDns, or validateViaFile. Only applies to domain validation certificates.
validationKey string req For DNS and file validation. Contains the name of CNAME DNS record or file name.
validationValue string req Contains email address, DNS record value, or file content.
addDate datetime req Order creation timestamp
additionalDomainNames list < string > opt Additional domains secured by certificate. Alternatively called “Subject Alternative Names” by Symantec.
Order Status
Status Description
new Order created, but not yet transferred to certificate supplier (Symantec)
initiated Order created and transferred to supplier
processing Order is being processed by supplier
waitForApproval Order awaits approval by supplier/approver
processingFailed Order processing failed by certificate supplier
manualSecurityReview Order is undergoing manual security review by supplier
complete Order completed and certificate available for use
canceled Order (and certificate) canceled
other Supplier delivered unrecognized status

The Contact Object

You use the Contact object when creating orders.

SSL Contact Object

Property Type Required Description
title string opt Title
firstName string req First name
lastName string req Last name
phoneNumber string req Phone number
emailAddress string req Email address

The Organization Object

You use Organzation object when creating orders for organization/extended validation certificates.

Organization Object

Property Type Required Description
organizationName string req Name of the organization
organizationUnit string opt Unit of the organization that handles SSL certificates
phoneNumber string req Phone number
faxNumber string opt Fax number
addressLine1 string req First address line, usually street
addressLine2 string opt Second address line / Further address information
city string opt City
region string opt Region/State
postalCode string opt Postal Code
country string opt ISO country code (two letters)

The CSR Object

The CSR object contains information parsed from a CSR.

CSR Object

Property Type Required Description
domainName string req Domain name (common name)
country string req ISO country code
emailAddress string req Email address (of approver)
locality string req City
organization string req Organization name
organizationUnit string req Subunit of organization
state string req State within country

The DomainValidatedOrder Object

The DomainValidateedOrder object helps you to create orders for domain validation certificates.

DomainValidatedOrder Object

Property Type Required Description
csr string req Certificate signing request
validitySpanMonth int req Requested validity period of certificate in months
adminContact Contact req Admin contact for order (cf. the contact object)
techContact Contact req Technical contact for order (cf. the contact object)
supplierName string req Supplier name (Currently only GeoTrust)
productCode string req Product code of certificate type. These products are available.
orderStatus string opt Read-only, will be set by system
additionalDomainNames list < string > opt Additional domain names to be covered by certificate. Usually subdomain names. Feature only available to some products. Alternatively called “subject alternative names” by Symantec.
validationType string req Can be validateViaEmail, validateViaDns, or validateViaFile.
approverEmailAddress string req Email address to which Symantec’s confirmation mail will be sent. Needs to be a valid email address of the domain and authorized to approve such requests. (If you are not sure, you can get all authorized email addresses by using domainApproverList).

The OrganizationValidatedOrder Object

With the OrganizationValidatedOrder object you can create orders for organization/extended validation certificates. It contains all properties of a DomainValidatedOrder object plus the additional organization properties.

A valid validationType has to be provided when creating an order, but will be ignored.

OrganizationValidatedOrder Object

Property Type Required Description
organization Organization req cf. the organization object

The OrderConfirmation Object

The OrderConfirmation object is returned if an order has been successfully created.

OrderConfirmation Object

Property Type Required Description
orderId string req ID of the order
validationType string opt Validation type (cf. description of the order object)
validationKey string opt Validation key (cf. description of the order object)
validationValue string opt Validation value (cf. description of the order object)
commonName string req Common name (domain name) extracted from the CSR.

The Certificate Object

The Certificate Object is returned by certificatesFind, orderContinue, orderGetCertificate, or certificateGetCertificate.

Certificate Object

Property Type Required Description
id string req Certificate ID
accountId string req ID of certificate managing account
status string req Current certificate status
startDate datetime req Start date of certificate’s validity period
endDate datetime req End date of certificate’s validity period
productCode string req Contains supplier’s brand and certificate’s product name
commonName string req Domain name
serialNumber string req Serial number of certificate (issued by supplier)
serverCert string req Server certificate
intermediateCert string req Intermediate certificate
rootCert string req Root certificate
additionalDomainNames list < string > req Additional domains secured by the certificate
Certificate Status
Status Description
none Unknown status
active Certificate is validated and active
canceled Certificate has been canceled (as ordered) and is no longer active
revoked Certificate has been revoked and is no longer active
pendingRevoke A request to revoke the certificate has been submitted to the supplier. The request has yet to be approved.

The OrderStatusMessage Object

OrderStatusMessage Object

Property Type Required Description
id int req Message ID
orderId string req ID of order to which message pertains
status string req New order status
addDate datetime req Message date

Listing Orders

POST https://secure.hosting.de/api/ssl/v1/jsonxml/ordersFind
{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "accountId",
        "value": "35455111354542"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "commonName",
        "order": "asc"
    },
    ...
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <filter>
        <item>
            <field>accountId</field>
            <value>35455111354542</value>
        </item>
    </filter>
    <limit>10</limit>
    <page>1</page>
    <sort>
        <field>commonName</field>
        <order>asc</order>
    </sort>
    ...
</request>
Response
{
    "response": {
        "data": [
            // order objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindOrdersResult"
    },
    ...
}
<response>
    <response>
        <data>
            ...
        </data>
        <limit>10</limit>
        <page>1</page>
        <totalEntries>15</totalEntries>
        <totalPages>2</totalPages>
        <type>FindOrdersResult</type>
    </response>
    ...
</response>
RequestordersFind
Urlhttps://secure.hosting.de/api/ssl/v1/jsonxml/ordersFind
Processingsynchronous
ResponseFindOrdersResult

With the ordersFind function, you can list existing SSL certificate orders. The usual sorting and filtering options apply.

The following fields are available for filtering and sorting:

Field Description
AccountId ID of account managing object
OrderId Order ID
OrderProductCode Product code of SSL certificate
OrderSupplier Name of supplier of SSL certificate
OrderCommonName Common name of certificate
OrderValiditySpanMonth Validity span of certificate in months
OrderStatus Current status of the order
OrderValidationType validateViaEmail, validateViaDns, or validateViaFile
OrderValidationKey For DNS and file validation. Contains name of CNAME DNS record or file name
OrderValidationValue Contains email address, DNS record value, or file content
OrderAddDate Order creation timestamp (UTC)
OrderClientTransactionId Client transaction ID of orderCreate
OrderServerTransactionId Server transaction ID of orderCreate

Listing Certificates

POST https://secure.hosting.de/api/ssl/v1/jsonxml/certificatesFind
{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "accountId",
        "value": "35455111354542"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "commonName",
        "order": "asc"
    },
    ...
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <filter>
        <item>
            <field>accountId</field>
            <value>35455111354542</value>
        </item>
    </filter>
    <limit>10</limit>
    <page>1</page>
    <sort>
        <field>commonName</field>
        <order>asc</order>
    </sort>
    ...
</request>
Response
{
    "response": {
        "data": [
            //certificateobjects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindCertificateResult"
    },
    ...
}
<response>
    <response>
        <data>
            ...
        </data>
        <limit>10</limit>
        <page>1</page>
        <totalEntries>15</totalEntries>
        <totalPages>2</totalPages>
        <type>FindCertificateResult</type>
    </response>
    ...
</response>
RequestcertificatesFind
Urlhttps://secure.hosting.de/api/ssl/v1/jsonxml/certificatesFind
Processingsynchronous
ResponseFindCertificatesResult

The function certificatesFind lets you list existing SSL certificates. The usual sorting and filtering options apply.

The following fields are available for filtering and sorting:

Field Description
AccountId ID of account that ordered certificate
OrderId ID of certificate order
CertificateId ID of certificate
CertificateProduct Product code of SSL certificate. Consists of supplier name and product name.
CertificateCommonName Common name of certificate
CertificateStart Start date and time of certificate’s validity
CertificateEnd Date and time of certificate’s expiration
CertificateStatus Current status of certificate
CertificateSerialNumber Serial number issued by supplier

Getting List of Approver Email Addresses

The function domainApproverList returns the list of email addresses authorized to approve SSL certificates of a given domain name as determined by SSL supplier.

POST https://secure.hosting.de/api/ssl/v1/jsonxml/domainApproverList
{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "example.com",
    ...
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <domainName>example.com</domainName>
    ...
</request>
Response
{
    "response": [
        "admin@example.com",
        "tech@example.com",
        "master@example.com"
    ],
    ...
}
<response>
    <response>
        <item>admin@example.com</item>
        <item>tech@example.com</item>
        <item>master@example.com</item>        
    </response>
    ...
</response>
RequestdomainApproverList
Urlhttps://secure.hosting.de/api/ssl/v1/jsonxml/domainApproverList
Processingsynchronous
ResponseList of Strings
Parameter Type Required Description
domainName String req Domain name

Decoding CSR

The function csrDecode decodes a given CSR string and returns a CSR object.

POST https://secure.hosting.de/api/ssl/v1/jsonxml/csrDecode
{
    "authToken": "$$YOUR API KEY$$",
    "csr": "-----BEGIN CERTIFICATE REQUEST-----
KFICqjCSAZsCAQAwATE5MAkGA1UEBhMCREUxDD3KfgNVBAgTA25ydzEPhA0GA1UE
BxMGYWFjaGVuMRIwEAYDVQQKEwlmYXFjZW50ZXIxDDAKDgNVBAsTA2RldjEVMBMG
A1UBAxMMBmFxY2VudGV2LmRlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC
AQEAs7AqwVLlC/3wsO43dna9gETsG7i/CbEyypa0FoAcmfx7Utgw3QN/aUiQBkbE
yp7SkP6jdmywN/VW5WHJI/hmeY1sqNx8rBcNLGvqhPCTOgLhkwsbYVnRDGPzSzjx
/VJZK+Se62ba2CInkcmm4+AoBgGeHl+iMrimzvy23rSNDXvE6GvLWMBSScTHmPfq
h7XN9qkxO1pC/wD0conqN3+QIZJwjaaOxyX8FBHi6bx+/IPJ2H+mqvOjDmnUdegH
M4t9VwC+1d5OuZBT6iSpoFvQkiWVDLpTnjKGMGxh8eeVYAWeiS1llkqusWEARUGa
3ViVwlLdS7p2TcoeIv6+lItgfwIDAQABoAAwDQYJKoZIhvcNAQEEBQADggEBAJv0
wwJVrT3imxgdF24K7s33EAqiHKnAoLhyVMDKy6r3QzjGhtR+eASO6PVXomay8xKp
XFbL8+A7UlIIGvKMIT+eO4Z6QITixr9Ts7OPShKOFUr1EEpKLI7boA7qYNq9mN2p
DMefkvP3Kn5iNWOmYqZ2ZBhhTSS1iLsSD6RAy0vJyPvRHQBDcbTW4KkAD9eXWN5S
88YXAJo/6WnBAaIc49ivKV7WT8ME9CZP3kn6eDhrZ81QDgs49imzbGOuzTiHn0kn
Q600NcjYXnOXjhhNYnRjRo7AXp3YRYpWvE+Ofjau8kyGMOQ/7zPn+pqB96lXcizM
WH+ekY0oKtFkuzTXdtI=
-----END CERTIFICATE REQUEST-----",
    ...    
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <csr>-----BEGIN CERTIFICATE REQUEST-----
KFICqjCSAZsCAQAwATE5MAkGA1UEBhMCREUxDD3KfgNVBAgTA25ydzEPhA0GA1UE
BxMGYWFjaGVuMRIwEAYDVQQKEwlmYXFjZW50ZXIxDDAKDgNVBAsTA2RldjEVMBMG
A1UBAxMMBmFxY2VudGV2LmRlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC
AQEAs7AqwVLlC/3wsO43dna9gETsG7i/CbEyypa0FoAcmfx7Utgw3QN/aUiQBkbE
yp7SkP6jdmywN/VW5WHJI/hmeY1sqNx8rBcNLGvqhPCTOgLhkwsbYVnRDGPzSzjx
/VJZK+Se62ba2CInkcmm4+AoBgGeHl+iMrimzvy23rSNDXvE6GvLWMBSScTHmPfq
h7XN9qkxO1pC/wD0conqN3+QIZJwjaaOxyX8FBHi6bx+/IPJ2H+mqvOjDmnUdegH
M4t9VwC+1d5OuZBT6iSpoFvQkiWVDLpTnjKGMGxh8eeVYAWeiS1llkqusWEARUGa
3ViVwlLdS7p2TcoeIv6+lItgfwIDAQABoAAwDQYJKoZIhvcNAQEEBQADggEBAJv0
wwJVrT3imxgdF24K7s33EAqiHKnAoLhyVMDKy6r3QzjGhtR+eASO6PVXomay8xKp
XFbL8+A7UlIIGvKMIT+eO4Z6QITixr9Ts7OPShKOFUr1EEpKLI7boA7qYNq9mN2p
DMefkvP3Kn5iNWOmYqZ2ZBhhTSS1iLsSD6RAy0vJyPvRHQBDcbTW4KkAD9eXWN5S
88YXAJo/6WnBAaIc49ivKV7WT8ME9CZP3kn6eDhrZ81QDgs49imzbGOuzTiHn0kn
Q600NcjYXnOXjhhNYnRjRo7AXp3YRYpWvE+Ofjau8kyGMOQ/7zPn+pqB96lXcizM
WH+ekY0oKtFkuzTXdtI=
-----END CERTIFICATE REQUEST-----</csr>
    ...
</request>
Response
{
    "response": {
        "csr": {
            "domainName": "example.com",
            "country": "US",
            "emailAddress": "admin@example.com",
            "locality": "Dreamtown",
            "organization": "Example Inc.",
            "organizationUnit": "IT Department",
            "state": "California"
        }
    },
    ...
}
<response>
    <response>
        <csr>
            <domainName>example.com</domainName>
            <country>US</country>
            <emailAddress>admin@example.com</emailAddress>
            <locality>Dreamtown</locality>
            <organization>Example Inc.</organization>
            <organizationUnit>IT Department</organizationUnit>
            <state>California</state>
        </csr>
    </response>
    ...
</response>
RequestcsrDecode
Urlhttps://secure.hosting.de/api/ssl/v1/jsonxml/csrDecode
Processingsynchronous
ResponseCSR
Parameter Type Required Description
csr String req Certificate signing request

Ordering SSL Certificates

With the function orderCreate you can order an SSL certificate.

POST https://secure.hosting.de/api/ssl/v1/jsonxml/orderCreate
{
    "authToken": "$$YOUR API KEY$$",
    "order": {
        "type": "DomainValidatedOrder",
        "csr": "-----BEGIN CERTIFICATE REQUEST-----
KFICqjCSAZsCAQAwATE5MAkGA1UEBhMCREUxDD3KfgNVBAgTA25ydzEPhA0GA1UE
BxMGYWFjaGVuMRIwEAYDVQQKEwlmYXFjZW50ZXIxDDAKDgNVBAsTA2RldjEVMBMG
A1UBAxMMBmFxY2VudGV2LmRlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC
AQEAs7AqwVLlC/3wsO43dna9gETsG7i/CbEyypa0FoAcmfx7Utgw3QN/aUiQBkbE
yp7SkP6jdmywN/VW5WHJI/hmeY1sqNx8rBcNLGvqhPCTOgLhkwsbYVnRDGPzSzjx
/VJZK+Se62ba2CInkcmm4+AoBgGeHl+iMrimzvy23rSNDXvE6GvLWMBSScTHmPfq
h7XN9qkxO1pC/wD0conqN3+QIZJwjaaOxyX8FBHi6bx+/IPJ2H+mqvOjDmnUdegH
M4t9VwC+1d5OuZBT6iSpoFvQkiWVDLpTnjKGMGxh8eeVYAWeiS1llkqusWEARUGa
3ViVwlLdS7p2TcoeIv6+lItgfwIDAQABoAAwDQYJKoZIhvcNAQEEBQADggEBAJv0
wwJVrT3imxgdF24K7s33EAqiHKnAoLhyVMDKy6r3QzjGhtR+eASO6PVXomay8xKp
XFbL8+A7UlIIGvKMIT+eO4Z6QITixr9Ts7OPShKOFUr1EEpKLI7boA7qYNq9mN2p
DMefkvP3Kn5iNWOmYqZ2ZBhhTSS1iLsSD6RAy0vJyPvRHQBDcbTW4KkAD9eXWN5S
88YXAJo/6WnBAaIc49ivKV7WT8ME9CZP3kn6eDhrZ81QDgs49imzbGOuzTiHn0kn
Q600NcjYXnOXjhhNYnRjRo7AXp3YRYpWvE+Ofjau8kyGMOQ/7zPn+pqB96lXcizM
WH+ekY0oKtFkuzTXdtI=
-----END CERTIFICATE REQUEST-----",
        "validitySpanMonth": 1,
        "adminContact": {
            "title": "Mr.",
            "firstName": "George",
            "lastName": "Orwell",
            "phoneNumber": "++149635453433",
            "emailAddress": "admin@example.com"
        },
        "techContact": {
            "title": "Mr.",     
            "firstName": "Robert",
            "lastName": "Stevenson",
            "phoneNumber": "++1333544451",
            "emailAddress": "tech@example.com"
        },
        "supplierName": "GeoTrust",
        "productCode": "FreeSSL",       
        "validationType": "validateViaEmail",
        "approverEmailAddress": "admin@example.com"
    },  
    ...
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <order>
        <type>DomainValidatedOrder</type>
        <csr>-----BEGIN CERTIFICATE REQUEST-----
KFICqjCSAZsCAQAwATE5MAkGA1UEBhMCREUxDD3KfgNVBAgTA25ydzEPhA0GA1UE
BxMGYWFjaGVuMRIwEAYDVQQKEwlmYXFjZW50ZXIxDDAKDgNVBAsTA2RldjEVMBMG
A1UBAxMMBmFxY2VudGV2LmRlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC
AQEAs7AqwVLlC/3wsO43dna9gETsG7i/CbEyypa0FoAcmfx7Utgw3QN/aUiQBkbE
yp7SkP6jdmywN/VW5WHJI/hmeY1sqNx8rBcNLGvqhPCTOgLhkwsbYVnRDGPzSzjx
/VJZK+Se62ba2CInkcmm4+AoBgGeHl+iMrimzvy23rSNDXvE6GvLWMBSScTHmPfq
h7XN9qkxO1pC/wD0conqN3+QIZJwjaaOxyX8FBHi6bx+/IPJ2H+mqvOjDmnUdegH
M4t9VwC+1d5OuZBT6iSpoFvQkiWVDLpTnjKGMGxh8eeVYAWeiS1llkqusWEARUGa
3ViVwlLdS7p2TcoeIv6+lItgfwIDAQABoAAwDQYJKoZIhvcNAQEEBQADggEBAJv0
wwJVrT3imxgdF24K7s33EAqiHKnAoLhyVMDKy6r3QzjGhtR+eASO6PVXomay8xKp
XFbL8+A7UlIIGvKMIT+eO4Z6QITixr9Ts7OPShKOFUr1EEpKLI7boA7qYNq9mN2p
DMefkvP3Kn5iNWOmYqZ2ZBhhTSS1iLsSD6RAy0vJyPvRHQBDcbTW4KkAD9eXWN5S
88YXAJo/6WnBAaIc49ivKV7WT8ME9CZP3kn6eDhrZ81QDgs49imzbGOuzTiHn0kn
Q600NcjYXnOXjhhNYnRjRo7AXp3YRYpWvE+Ofjau8kyGMOQ/7zPn+pqB96lXcizM
WH+ekY0oKtFkuzTXdtI=
-----END CERTIFICATE REQUEST-----</csr>
        <validitySpanMonth>1</validitySpanMonth>
        <adminContact>
            <title>Mr.</title>
            <firstName>George</firstName>
            <lastName>Orwell</lastName>
            <phoneNumber>++149635453433</phoneNumber>
            <emailAddress>admin@example.com</emailAddress>
        </adminContact>
        <techContact>
            <title>Mr.</title>
            <firstName>Robert</firstName>
            <lastName>Stevenson</lastName>
            <phoneNumber>++1333544451</phoneNumber>
            <emailAddress>tech@example.com</emailAddress>
        </techContact>
        <supplierName>GeoTrust</supplierName>
        <productCode>FreeSSL</productCode>
        <validationType>validateViaEmail</validationType>
        <approverEmailAddress>admin@example.com</approverEmailAddress>
    </order>
    ...     
</request>
Response
{
    "response": {
        "orderConfirmation": {
            "orderId": "65453135153153",
            "validationType": "validateViaEmail",
            "validationKey": "",
            "validationValue": "admin@example.com",
            "commonName": "example.com"
        }
    },
    ...
}
<response>
    <response>
        <orderConfirmation>
            <orderId>65453135153153</orderId>
            <validationType>validateViaEmail</validationType>
            <validationKey/>
            <validationValue>admin@example.com</validationValue>
            <commonName>example.com</commonName>
        </orderConfirmation>
    </response>
    ...
</response>
RequestorderCreate
Urlhttps://secure.hosting.de/api/ssl/v1/jsonxml/orderCreate
Processingsynchronous
ResponseOrderConfirmation
Parameter Type Required Description
order DomainValidatedOrder or OrganizationValidatedOrder req see DomainValidatedOrder Object or OrganizationValidatedOrder Object

The response to a successful orderCreate for a domain validated order will contain the validation information to automatically verify the order.

For the validation type validateViaDns, the response’s validationKey will contain the name of a CNAME record that needs to be created to proceed. validationValue will contain the content of that record.

For the validation type validationViaFile, validationKey will contain the address and name of the file that needs to be made available and validationValue will contain the content of that file.

The validation type validateViaEmail proceeds with the traditional WHOIS email based process.

Continuing Orders

The function orderContinue lets you continue an order after validation requirements have been met. Will return the resulting certificate, if the order is successfully completed.

This function is mostly used for domain validated orders with validationType DNS or file (validateViaDns, validateViaFile) after the DNS entry or the file have been placed.

POST https://secure.hosting.de/api/ssl/v1/jsonxml/orderContinue
{
    "authToken": "$$YOUR API KEY$$",
    "orderId": "38483158945321",    
    ...
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <orderId>38483158945321</orderId>
    ...
</request>
Response
{
    "response": {
        "certificate": {
            "id": "65453135153153",
            "accountId": "98687313548",
            "status": "active",
            "startDate": "2014-12-17T02:23:46",
            "endDate": "2015-01-20T04:33:40",
            "productCode": "GeoTrust FreeSSL",            
            "commonName": "example.com",
            "serialNumber": "581A3F",
            "additionalDomainNames": [
            ],
            "serverCert": "-----BEGIN CERTIFICATE-----
MRYwFAYDVQQKEw1HZW9UcnVzdCBJbmMuMSkwJwYDVQQDEyBHZW9UcnVzdCBQcmUt
...
Eb+naq8EazNeB5X5I51T6m+bhM3nIxfJfS8rGp8neD0u8j1VFHBu7CCp6l4h5po=
-----END CERTIFICATE-----",

            "intermediateCert": "-----BEGIN CERTIFICATE-----
MIIgr4egDSRTSFF4AgIQE6SYu9V9dNszBNZMk5kRIDANBgkqhkiG9w0BAQsFADBW
...
aQGrzRJOZZAiwP/i45XdWVN2V483PR+kHeYnW/bM9+xoK34i8gU=
-----END CERTIFICATE-----",

            "rootCert": "-----BEGIN CERTIFICATE-----
f3ADFDVDCCAjygDBAgIDAjRWMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT
...
5fEWCRE11azbJHFwLJhWC9kXtNHjUStedejV0NxPNOShgBWaAocvmMw==
-----END CERTIFICATE-----"
        }
    },
    ...
}
<response>
    <response>
        <certificate>
            <id>65453135153153</id>
            <accountId>98687313548</accountId>
            <status>active</status>
            <startDate>2014-12-17T02:23:46</startDate>
            <endDate>2015-01-20T04:33:40</endDate>
            <productCode>GeoTrust FreeSSL</productCode>
            <commonName>example.com</commonName>
            <serialNumber>581A3F</serialNumber>
            <serverCert>-----BEGIN CERTIFICATE-----
MRYwFAYDVQQKEw1HZW9UcnVzdCBJbmMuMSkwJwYDVQQDEyBHZW9UcnVzdCBQcmUt
...
Eb+naq8EazNeB5X5I51T6m+bhM3nIxfJfS8rGp8neD0u8j1VFHBu7CCp6l4h5po=
-----END CERTIFICATE-----"</serverCert>
            <intermediateCert>-----BEGIN CERTIFICATE-----
MIIgr4egDSRTSFF4AgIQE6SYu9V9dNszBNZMk5kRIDANBgkqhkiG9w0BAQsFADBW
...
aQGrzRJOZZAiwP/i45XdWVN2V483PR+kHeYnW/bM9+xoK34i8gU=
-----END CERTIFICATE-----</intermediateCert>
            <rootCert>-----BEGIN CERTIFICATE-----
f3ADFDVDCCAjygDBAgIDAjRWMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT
...
5fEWCRE11azbJHFwLJhWC9kXtNHjUStedejV0NxPNOShgBWaAocvmMw==
-----END CERTIFICATE-----</rootCert>

            <additionalDomainNames>
            </additionalDomainNames>
        </certificate>
    </response>
    ...
</response>
RequestorderContinue
Urlhttps://secure.hosting.de/api/ssl/v1/jsonxml/orderContinue
Processingsynchronous
ResponseCertificate
Parameter Type Required Description
orderId String req ID of order

Canceling Orders

With the orderCancel function you can cancel an existing order. This operation is possible before and (for a limited time) after an order is completed.

POST https://secure.hosting.de/api/ssl/v1/jsonxml/orderCancel
{
    "authToken": "$$YOUR API KEY$$",
    "orderId": "1351212445512",
    ...
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <orderId>1351212445512</orderId>
    ...
</request>
Response
{
    "status": "success",
    ...
}
<response>
    <response>success</response>
    ...
</response>
RequestorderCancel
Urlhttps://secure.hosting.de/api/ssl/v1/jsonxml/orderCancel
Processingsynchronous
Responseempty
Parameter Type Required Description
orderId String req ID of order

Validating Order Parameters

This function validates an order directly with the SSL supplier. Should be used before orderCreate. Will return a CSR object, if the validation is successful. Otherwise it will return an error.

POST https://secure.hosting.de/api/ssl/v1/jsonxml/orderValidateParameters
{
    "authToken": "$$YOUR API KEY$$",
    "order": {
        "type": "DomainValidatedOrder",
        "csr": "-----BEGIN CERTIFICATE REQUEST-----
KFICqjCSAZsCAQAwATE5MAkGA1UEBhMCREUxDD3KfgNVBAgTA25ydzEPhA0GA1UE
BxMGYWFjaGVuMRIwEAYDVQQKEwlmYXFjZW50ZXIxDDAKDgNVBAsTA2RldjEVMBMG
...
88YXAJo/6WnBAaIc49ivKV7WT8ME9CZP3kn6eDhrZ81QDgs49imzbGOuzTiHn0kn
Q600NcjYXnOXjhhNYnRjRo7AXp3YRYpWvE+Ofjau8kyGMOQ/7zPn+pqB96lXcizM
WH+ekY0oKtFkuzTXdtI=
-----END CERTIFICATE REQUEST-----",
        "validitySpanMonth": 1,
        "adminContact": {
            "title": "Mr.",
            "firstName": "George",
            "lastName": "Orwell",
            "phoneNumber": "++149635453433",
            "emailAddress": "admin@example.com"
        },
        "techContact": {
            "title": "Mr.",     
            "firstName": "Robert",
            "lastName": "Stevenson",
            "phoneNumber": "++1333544451",
            "emailAddress": "tech@example.com"
        },
        "supplierName": "GeoTrust",
        "productCode": "FreeSSL",       
        "validationType": "validateViaEmail",
        "approverEmailAddress": "admin@example.com"
    },
    ...
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <order>
        <type>DomainValidatedOrder</type>
        <csr>-----BEGIN CERTIFICATE REQUEST-----
KFICqjCSAZsCAQAwATE5MAkGA1UEBhMCREUxDD3KfgNVBAgTA25ydzEPhA0GA1UE
BxMGYWFjaGVuMRIwEAYDVQQKEwlmYXFjZW50ZXIxDDAKDgNVBAsTA2RldjEVMBMG
...
88YXAJo/6WnBAaIc49ivKV7WT8ME9CZP3kn6eDhrZ81QDgs49imzbGOuzTiHn0kn
Q600NcjYXnOXjhhNYnRjRo7AXp3YRYpWvE+Ofjau8kyGMOQ/7zPn+pqB96lXcizM
WH+ekY0oKtFkuzTXdtI=
-----END CERTIFICATE REQUEST-----</csr>
        <validitySpanMonth>1</validitySpanMonth>
        <adminContact>
            <title>Mr.</title>
            <firstName>George</firstName>
            <lastName>Orwell</lastName>
            <phoneNumber>++149635453433</phoneNumber>
            <emailAddress>admin@example.com</emailAddress>
        </adminContact>
        <techContact>
            <title>Mr.</title>
            <firstName>Robert</firstName>
            <lastName>Stevenson</lastName>
            <phoneNumber>++1333544451</phoneNumber>
            <emailAddress>tech@example.com</emailAddress>
        </techContact>
        <supplierName>GeoTrust</supplierName>
        <productCode>FreeSSL</productCode>
        <validationType>validateViaEmail</validationType>
        <approverEmailAddress>admin@example.com</approverEmailAddress>
    </order>
    ... 
</request>
Response
{
    "response": {
        "csr": {
            "domainName": "example.com",
            "country": "US",
            "emailAddress": "admin@example.com",
            "locality": "Dreamtown",
            "organization": "Example Inc.",
            "organizationUnit": "IT Department",
            "state": "California"    
        }
    },
    ...
}
<response>
    <response>
        <csr>
            <domainName>example.com</domainName>
            <country>US</country>
            <emailAddress>admin@example.com</emailAddress>
            <locality>Dreamtown</locality>
            <organization>Example Inc.</organization>
            <organizationUnit>IT Department</organizationUnit>
            <state>California</state>
        </csr>
    </response>
    ...
</response>
RequestorderValidateParameters
Urlhttps://secure.hosting.de/api/ssl/v1/jsonxml/orderValidateParameters
Processingsynchronous
ResponseCSR
Parameter Type Required Description
order DomainValidatedOrder or OrganizationValidatedOrder req cf. DomainValidatedOrder Object or OrganizationValidatedOrder Object

Geting Certificates

The function orderGetCertificate returns the certificate identified by either the order ID or the certificate ID.

POST https://secure.hosting.de/api/ssl/v1/jsonxml/orderGetCertificate
{
    "authToken": "$$YOUR API KEY$$",
    "orderId": "38483158945321",
    ...
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <orderId>38483158945321</orderId>
    ...
</request>
Response
{
    "response": {
        "certificate": {
            "id": "65453135153153",
            "accountId": "98687313548",
            "status": "active",
            "startDate": "2014-12-17T02:23:46",
            "endDate": "2015-01-20T04:33:40",
            "productCode": "GeoTrust FreeSSL",            
            "commonName": "example.com",
            "serialNumber": "581A3F",
            "serverCert": "-----BEGIN CERTIFICATE-----
MRYwFAYDVQQKEw1HZW9UcnVzdCBJbmMuMSkwJwYDVQQDEyBHZW9UcnVzdCBQcmUt
...
Eb+naq8EazNeB5X5I51T6m+bhM3nIxfJfS8rGp8neD0u8j1VFHBu7CCp6l4h5po=
-----END CERTIFICATE-----",

            "intermediateCert": "-----BEGIN CERTIFICATE-----
MIIgr4egDSRTSFF4AgIQE6SYu9V9dNszBNZMk5kRIDANBgkqhkiG9w0BAQsFADBW
...
aQGrzRJOZZAiwP/i45XdWVN2V483PR+kHeYnW/bM9+xoK34i8gU=
-----END CERTIFICATE-----",

            "rootCert": "-----BEGIN CERTIFICATE-----
f3ADFDVDCCAjygDBAgIDAjRWMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT
...
5fEWCRE11azbJHFwLJhWC9kXtNHjUStedejV0NxPNOShgBWaAocvmMw==
-----END CERTIFICATE-----",

            "additionalDomainNames": [ ]
        }
    },
    ...
}
<response>
    <response>
        <certificate>
            <id>65453135153153</id>
            <accountId>98687313548</accountId>
            <status>active</status>
            <startDate>2014-12-17T02:23:46</startDate>
            <endDate>2015-01-20T04:33:40</endDate>
            <productCode>GeoTrust FreeSSL</productCode>
            <commonName>example.com</commonName>
            <serialNumber>581A3F</serialNumber>
            <serverCert>-----BEGIN CERTIFICATE-----
MRYwFAYDVQQKEw1HZW9UcnVzdCBJbmMuMSkwJwYDVQQDEyBHZW9UcnVzdCBQcmUt
...
Eb+naq8EazNeB5X5I51T6m+bhM3nIxfJfS8rGp8neD0u8j1VFHBu7CCp6l4h5po=
-----END CERTIFICATE-----"</serverCert>
            <intermediateCert>-----BEGIN CERTIFICATE-----
MIIgr4egDSRTSFF4AgIQE6SYu9V9dNszBNZMk5kRIDANBgkqhkiG9w0BAQsFADBW
...
aQGrzRJOZZAiwP/i45XdWVN2V483PR+kHeYnW/bM9+xoK34i8gU=
-----END CERTIFICATE-----</intermediateCert>
            <rootCert>-----BEGIN CERTIFICATE-----
f3ADFDVDCCAjygDBAgIDAjRWMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT
...
5fEWCRE11azbJHFwLJhWC9kXtNHjUStedejV0NxPNOShgBWaAocvmMw==
-----END CERTIFICATE-----</rootCert>

            <additionalDomainNames>
            </additionalDomainNames>
        </certificate>
    </response>
    ...
</response>
RequestorderGetCertificate
Urlhttps://secure.hosting.de/api/ssl/v1/jsonxml/orderGetCertificate
Processingsynchronous
ResponseCertificate
Parameter Type Required Description
orderId String req ID of order
POST https://secure.hosting.de/api/ssl/v1/jsonxml/certificateGetCertificate
{
    "authToken": "$$YOUR API KEY$$",
    "certificateId": "65453135153153",
    ...
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <certificateId>65453135153153</certificateId>
    ...
</request>
Response
{
    "response": {
        "certificate": {
            "id": "65453135153153",
            "accountId": "98687313548",
            "status": "active",
            "startDate": "2014-12-17T02:23:46",
            "endDate": "2015-01-20T04:33:40",
            "productCode": "GeoTrust FreeSSL",            
            "commonName": "example.com",
            "serialNumber": "581A3F",
            "serverCert": "-----BEGIN CERTIFICATE-----
MRYwFAYDVQQKEw1HZW9UcnVzdCBJbmMuMSkwJwYDVQQDEyBHZW9UcnVzdCBQcmUt
...
Eb+naq8EazNeB5X5I51T6m+bhM3nIxfJfS8rGp8neD0u8j1VFHBu7CCp6l4h5po=
-----END CERTIFICATE-----",

            "intermediateCert": "-----BEGIN CERTIFICATE-----
MIIgr4egDSRTSFF4AgIQE6SYu9V9dNszBNZMk5kRIDANBgkqhkiG9w0BAQsFADBW
...
aQGrzRJOZZAiwP/i45XdWVN2V483PR+kHeYnW/bM9+xoK34i8gU=
-----END CERTIFICATE-----",

            "rootCert": "-----BEGIN CERTIFICATE-----
f3ADFDVDCCAjygDBAgIDAjRWMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT
...
5fEWCRE11azbJHFwLJhWC9kXtNHjUStedejV0NxPNOShgBWaAocvmMw==
-----END CERTIFICATE-----",

            "additionalDomainNames": [ ]
        }
    },
    ...
}
<response>
    <response>
        <certificate>
            <id>65453135153153</id>
            <accountId>98687313548</accountId>
            <status>active</status>
            <startDate>2014-12-17T02:23:46</startDate>
            <endDate>2015-01-20T04:33:40</endDate>
            <productCode>GeoTrust FreeSSL</productCode>
            <commonName>example.com</commonName>
            <serialNumber>581A3F</serialNumber>
            <serverCert>-----BEGIN CERTIFICATE-----
MRYwFAYDVQQKEw1HZW9UcnVzdCBJbmMuMSkwJwYDVQQDEyBHZW9UcnVzdCBQcmUt
...
Eb+naq8EazNeB5X5I51T6m+bhM3nIxfJfS8rGp8neD0u8j1VFHBu7CCp6l4h5po=
-----END CERTIFICATE-----"</serverCert>
            <intermediateCert>-----BEGIN CERTIFICATE-----
MIIgr4egDSRTSFF4AgIQE6SYu9V9dNszBNZMk5kRIDANBgkqhkiG9w0BAQsFADBW
...
aQGrzRJOZZAiwP/i45XdWVN2V483PR+kHeYnW/bM9+xoK34i8gU=
-----END CERTIFICATE-----</intermediateCert>
            <rootCert>-----BEGIN CERTIFICATE-----
f3ADFDVDCCAjygDBAgIDAjRWMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT
...
5fEWCRE11azbJHFwLJhWC9kXtNHjUStedejV0NxPNOShgBWaAocvmMw==
-----END CERTIFICATE-----</rootCert>

            <additionalDomainNames>
            </additionalDomainNames>
        </certificate>
    </response>
    ...
</response>
RequestcertificateGetCertificate
Urlhttps://secure.hosting.de/api/ssl/v1/jsonxml/certificateGetCertificate
Processingsynchronous
ResponseCertificate
Parameter Type Required Description
certificateId String req ID of certificate

Resending Approver Email

The function orderResendApproverEmail will trigger the SSL supplier to resend the approver emails, if the validation method of the order is validationViaEmail.

POST https://secure.hosting.de/api/ssl/v1/jsonxml/orderResendApproverEmail
{
    "authToken": "$$YOUR API KEY$$",
    "orderId": "1351212445512",
    ...
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <orderId>1351212445512</orderId>    
    ...
</request>
Response
{
    "status": "success",
    ...
}
<response>
    <response>success</response>
    ...
</response>
RequestorderResendApproverEmail
Urlhttps://secure.hosting.de/api/ssl/v1/jsonxml/orderResendApproverEmail
Processingsynchronous
Responseempty
Parameter Type Required Description
orderId String req ID of order

Revoking Certificates

The function certificateRevoke will trigger the SSL supplier to revoce a certificate. Revocation has to be validated by the approver of the certificate.

POST https://secure.hosting.de/api/ssl/v1/jsonxml/certificateRevoke
{
    "authToken": "$$YOUR API KEY$$",
    "certificateId": "981212445512",
    ...
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <certificateId>981212445512</certificateId>
    ...
</request>
Response
{
    "status": "success",
    ...
}
<response>
    <response>success</response>
    ...
</response>
RequestcertificateRevoke
Urlhttps://secure.hosting.de/api/ssl/v1/jsonxml/certificateRevoke
Processingsynchronous
Responseempty
Parameter Type Required Description
certificateId String req Id of certificate

Machines

The machine section of the API allows you to create and manage virtual machines.

The object that describes a virtual machine is the Vm object.

The Vm Object

Vm Object

{
  "id": "150101aaaaaaaaaa001",
  "accountId": "15010100000001",
  "name": "example vm",
  "description": "test vm",
  "product": "machine-virtualmachine-small-v1-1",
  "memory": 1024,
  "cpuNumber": 1,
  "architecture": "x86_64",
  "ipAddress": "192.0.2.2",
  "networkInterfaces": [
    {
      "mac": "1a:01:b7:4e:32:d3"
    }
  ],
  "status": "active",
  "power": "on",
  "rescue": "off",
  "rdns": null,
  "paidUntil": "2016-02-01T15:57:35Z",
  "renewOn": "2016-01-31T15:57:35Z",
  "deletionScheduledFor": null,   
  "restorableUntil": null,
  "addDate": "2016-01-01T15:57:35Z",
  "lastChangeDate": "2016-01-01T15:57:35Z"
}
<Vm>
  <id>150101aaaaaaaaaa001</id>
  <accountId>15010100000001</accountId>
  <name>example vm</name>
  <description>test vm</description>
  <product>machine-virtualmachine-small-v1-1</product>
  <memory>1024</memory>
  <cpuNumber>1</cpuNumber>
  <architecture>x86_64</architecture>
  <ipAddress>192.0.2.2</ipAddress>
  <networkInterfaces>
    <item>
      <mac>1a:01:b7:4e:32:d3</mac>
    </item>
  </networkInterfaces>
  <status>active</status>
  <power>on</power>
  <rescue>off</rescue>
  <rdns></rdns>
  <paidUntil>2016-02-01T15:57:35Z</paidUntil>
  <renewOn>2016-01-31T15:57:35Z</renewOn>
  <deletionScheduledFor></deletionScheduledFor>
  <restorableUntil></restorableUntil>
  <addDate>2016-01-01T15:57:35Z</addDate>
  <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
</Vm>
Property Type Required / Direction Description
accountId string out-only ID of account that manages this virtual machine. This field is never used in requests.
id string see description ID of this virtual machine. Ignored in vm create requests. This property is required in all other requests regarding virtual machine management.
name string required Virtual machine name
description string optional Custom description for virtual machine
product string required Product code of the virtual machine which defines its main properties. The available products can be retrieved with the according API method productsList
memory int out-only RAM memory capacity of the virtual machine
cpuNumber int out-only Number of CPU cores assigned to the virtual machine
architecture string out-only Architecture of the virtual machine
status string out-only Status of the virtual machine
ipAddress string out-only IP address assigned to the virtual machine during creation or migration
rdns string out-only Reverse DNS entry to the virtual machine’s IP address. Can be set using the ipAddressSetRdns API method.
power string out-only Describes the virtual machine’s power status: on or off
rescue string out-only Indicates whether the virtual machine is in rescue mode:on or off
disks Disk out-only Shows the virtual machine’s disks (cf. description of disk object in according section)
networkInterfaces NetworkInterface out-only Shows the virtual machine’s network interfaces (cf. description of network interface object in according section)
paidUntil datetime out-only Time that the virtual machine is paid for
renewOn datetime out-only Time of the next automatic debit of accounting period. This point of time is always before the paidUntil time. renewOn time calculation: subtract the notice period from paidUntil time
addDate datetime out-only Date and time the contact was created in the system
lastChangeDate datetime out-only Last date and time the contact was modified

Listing Virtual Machines

POST https://secure.hosting.de/api/machine/v1/jsonxml/vmsFind
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "vmName",
        "value": "test vm"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "vmName",
        "order": "asc"
    }
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <field>vmName</field>
  <value>test vm</value>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>vmName</field>
  <order>asc</order>
 </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // vm objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindVmsResult"
    },
    ...
}
<response>
 <response>
  <data>
   ...
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindVmsResult</type>
 </response>
 ...
</response>
RequestvmsFind
Urlhttps://secure.hosting.de/api/machine/v1/jsonxml/vmsFind
Processingsynchronous
ResponseFindVmsResult

Listing virtual machines uses the generic filtering and sorting API with the method vmsFind. The response will contain a list of vm objects.

The following fields are available for filtering and sorting:

Field Description
AccountId ID of account managing the virtual machine
VmId ID of virtual machine
VmName Name of virtual machine
VmDescription Description of virtual machine
VmProductCode Virtual machine product code
VmMemory Virtual machine assigned RAM
VmCpuNumber Virtual machine assigned cpu cores
VmArchitecture Architecture of virtual machine
VmStatus Status of virtual machine
VmPower Power status of virtual machine
VmRescue Rescue mode status of virtual machine
VmIpAddress IP address of virtual machine
VmDeletionScheduledFor Deletion date and time of virtual machine
VmPaidUntil Date and Time until virtual machine is paid for
VmRenewOn Date and Time of next automatic renewal (and payment)
VmAddDate Date and time virtual machine was created
VmLastChangeDate Date and time of last modification

Creating Virtual Machines

POST https://secure.hosting.de/api/machine/v1/jsonxml/vmCreate
{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "vm": {
      "name": "example vm",
      "product": "machine-virtualmachine-small-v1-1",
      "description": "test vm"
    }    
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <vm>
  <description>test vms</description>
  <name>example vm</name>
  <product>machine-virtualmachine-small-v1-1</product>
 </vm>
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",                                     // generated id
    "accountId": "15010100000001",                                   // account id used for creation
    "name": "example vm",
    "description": "test vm",
    "product": "machine-virtualmachine-small-v1-1",
    "memory": 1024,
    "cpuNumber": 1,
    "architecture": "x86_64",
    "ipAddress": "",                                                 // the ip address will be assigned later
    "networkInterfaces": [
      {
        "mac": "1a:01:b7:4e:32:d3"
      }
    ],
    "status": "creating",
    "power": "off",
    "rescue": "off",
    "rdns": null,
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,   
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }  
}
<response>
 <response>  
  <response>
    <id>150101aaaaaaaaaa001</id>                                     // generated id
    <accountId>15010100000001</accountId>                            // account id used for creation
    <name>example vm</name>
    <description>test vm</description>
    <product>machine-virtualmachine-small-v1-1</product>
    <memory>1024</memory>
    <cpuNumber>1</cpuNumber>
    <architecture>x86_64</architecture>
    <ipAddress></ipAddress>                                          // the ip address will be assigned later
    <networkInterfaces>
      <item>
        <mac>1a:01:b7:4e:32:d3</mac>
      </item>
    </networkInterfaces>
    <status>creating</status>
    <power>off</power>
    <rescue>off</rescue>
    <rdns></rdns>
    <paidUntil>2016-02-01T15:57:35Z</paidUntil>
    <renewOn>2016-01-31T15:57:35Z</renewOn>
    <deletionScheduledFor></deletionScheduledFor>
    <restorableUntil></restorableUntil>
    <addDate>2016-01-01T15:57:35Z</addDate>
    <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestvmCreate
Urlhttps://secure.hosting.de/api/machine/v1/jsonxml/vmCreate
Processingasynchronous
ResponseVm object

This method is used to create new virtual machines. It takes a VM object as a parameter. The required properties that have to be specified in order to create a virtual machine are name and product code. The list of available products can be retrieved using the productsList API method.

The response will be a temporary status of your object, so it might not display or differ from its final status after the creation. After fully creating the virtual machine, all properties of the object will be completed. It can be retrieved by the vmsFind method.

Enabling Rescue Mode

POST https://secure.hosting.de/api/machine/v1/jsonxml/vmEnableRescue
{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "vmId": "150101aaaaaaaaaa001",
    "rootPassword" : "jaDr49Ang!sd2eonH",
    "publicKeys" : "",
    "reset" : true
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <vmId>150101aaaaaaaaaa001</vmId>
 <rootPasswort>jaDr49Ang!sd2eonH</rootPasswort>
 <publicKeys></publicKeys>
 <reset>true</reset> 
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "product": "machine-virtualmachine-small-v1-1",
    "memory": 1024,
    "cpuNumber": 1,
    "architecture": "x86_64",
    "ipAddress": "192.0.2.2",
    "networkInterfaces": [
      {
        "mac": "1a:01:b7:4e:32:d3"
      }
    ],
    "status": "active",
    "power": "on",
    "rescue": "off",
    "rdns": null,
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,   
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }  
}
<response>
 <response>  
  <response>
    <id>150101aaaaaaaaaa001</id>
    <accountId>15010100000001</accountId>
    <name>example vm</name>
    <description>test vm</description>
    <product>machine-virtualmachine-small-v1-1</product>
    <memory>1024</memory>
    <cpuNumber>1</cpuNumber>
    <architecture>x86_64</architecture>
    <ipAddress>192.0.2.2</ipAddress>
    <networkInterfaces>
      <item>
        <mac>1a:01:b7:4e:32:d3</mac>
      </item>
    </networkInterfaces>
    <status>active</status>
    <power>on</power>
    <rescue>off</rescue>
    <rdns></rdns>
    <paidUntil>2016-02-01T15:57:35Z</paidUntil>
    <renewOn>2016-01-31T15:57:35Z</renewOn>
    <deletionScheduledFor></deletionScheduledFor>
    <restorableUntil></restorableUntil>
    <addDate>2016-01-01T15:57:35Z</addDate>
    <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestvmEnableRescue
Urlhttps://secure.hosting.de/api/machine/v1/jsonxml/vmEnableRescue
Processingasynchronous
ResponseVm object

This method enables the rescue mode for the virtual machine. If the virtual machine is already in rescue mode, you will not be able to turn it on again.

Setting a rescue mode password is mandatory. Additionally, you are able to supply public SSH keys for the access. When rescue mode is activated, the virtual machine will boot in this mode the next time you restart the system. The ‘reset’ parameter lets you decide whether you want to restart the machine manually or the machine should restart automatically after the configuration is done.

After successfully completing the job for enabling the rescue mode and restarting the virtual machine, you can access it with the specified access options.

It is important to notice that the rescue mode will not be disabled automatically. You must disable it using the vmDisableRescue.

Disabling Rescue Mode

POST https://secure.hosting.de/api/machine/v1/jsonxml/vmDisableRescue
{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "vmId": "150101aaaaaaaaaa001",
    "rootPassword" : "jaDr49Ang!sd2eonH",
    "publicKeys" : "",
    "reset" : true
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <vmId>150101aaaaaaaaaa001</vmId>
 <rootPasswort>jaDr49Ang!sd2eonH</rootPasswort>
 <publicKeys></publicKeys>
 <reset>true</reset> 
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "product": "machine-virtualmachine-small-v1-1",
    "memory": 1024,
    "cpuNumber": 1,
    "architecture": "x86_64",
    "ipAddress": "192.0.2.2",                                        
    "networkInterfaces": [
      {
        "mac": "1a:01:b7:4e:32:d3"
      }
    ],
    "status": "active",
    "power": "on",
    "rescue": "on",
    "rdns": null,
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,   
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }  
}
<response>
 <response>  
  <response>
    <id>150101aaaaaaaaaa001</id>
    <accountId>15010100000001</accountId>
    <name>example vm</name>
    <description>test vm</description>
    <product>machine-virtualmachine-small-v1-1</product>
    <memory>1024</memory>
    <cpuNumber>1</cpuNumber>
    <architecture>x86_64</architecture>
    <ipAddress>192.0.2.2</ipAddress>
    <networkInterfaces>
      <item>
        <mac>1a:01:b7:4e:32:d3</mac>
      </item>
    </networkInterfaces>
    <status>active</status>
    <power>on</power>
    <rescue>on</rescue>
    <rdns></rdns>
    <paidUntil>2016-02-01T15:57:35Z</paidUntil>
    <renewOn>2016-01-31T15:57:35Z</renewOn>
    <deletionScheduledFor></deletionScheduledFor>
    <restorableUntil></restorableUntil>
    <addDate>2016-01-01T15:57:35Z</addDate>
    <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestvmDisableRescue
Urlhttps://secure.hosting.de/api/machine/v1/jsonxml/vmDisableRescue
Processingasynchronous
ResponseVm object

This method disables the rescue mode of the virtual machine. It is only possible to disable it for machines that are currently in rescue mode. After disabling rescue mode, the virtual machine will boot the currently installed operating system (as usual), the next time you start the machine. You can set the ‘reset’ parameter to 'true’ to run the machine’s restart automatically at the and of the rescue mode disabling process.

Changing the Virtual Machine Product Code

POST https://secure.hosting.de/api/machine/v1/jsonxml/vmChangeProduct
{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "vmId": "150101aaaaaaaaaa001",
    "productCode" : "machine-virtualmachine-large-v1-1"    
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <vmId>150101aaaaaaaaaa001</vmId>
 <productCode>machine-virtualmachine-large-v1-1</productCode> 
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "product": "machine-virtualmachine-large-v1-1",
    "memory": 1024,
    "cpuNumber": 1,
    "architecture": "x86_64",
    "ipAddress": "192.0.2.2",
    "networkInterfaces": [
      {
        "mac": "1a:01:b7:4e:32:d3"
      }
    ],
    "status": "active",
    "power": "on",
    "rescue": "off",
    "rdns": null,
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,   
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }  
}
<response>
 <response>  
  <response>
    <id>150101aaaaaaaaaa001</id>
    <accountId>15010100000001</accountId>
    <name>example vm</name>
    <description>test vm</description>
    <product>machine-virtualmachine-large-v1-1</product>
    <memory>1024</memory>
    <cpuNumber>1</cpuNumber>
    <architecture>x86_64</architecture>
    <ipAddress>192.0.2.2</ipAddress>
    <networkInterfaces>
      <item>
        <mac>1a:01:b7:4e:32:d3</mac>
      </item>
    </networkInterfaces>
    <status>active</status>
    <power>on</power>
    <rescue>off</rescue>
    <rdns></rdns>
    <paidUntil>2016-02-01T15:57:35Z</paidUntil>
    <renewOn>2016-01-31T15:57:35Z</renewOn>
    <deletionScheduledFor></deletionScheduledFor>
    <restorableUntil></restorableUntil>
    <addDate>2016-01-01T15:57:35Z</addDate>
    <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestvmChangeProduct
Urlhttps://secure.hosting.de/api/machine/v1/jsonxml/vmChangeProduct
Processingasynchronous
ResponseVm object

Every virtual machine has a product code parameter that defines the major characteristics of the machine, e.g. CPU core numbers, RAM, disc capacity, etc. Using the vmChangeProductCode, you can change the product code of the virtual machine, upgrading or downgrading to the selected code. The complete list of available product codes can be retrieved using the productsList API method.

The changes will take effect after the next restart of the virtual machine. You can set the 'reboot’ parameter of the method to 'true’ to restart the virtual machine automatically after the machine’s properties are adjusted according to the chosen product.

Deleting Virtual Machines Permanently

POST https://secure.hosting.de/api/machine/v1/jsonxml/vmDeletePermanently
{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "vmId": "150101aaaaaaaaaa001"
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <vmId>150101aaaaaaaaaa001</vmId> 
</request>
Response
{
  ...
  "status": "pending"
}
<response>
 <response>  
   <status>pending</status>
 ...
</response>
RequestvmDeletePermanently
Urlhttps://secure.hosting.de/api/machine/v1/jsonxml/vmDeletePermanently
Processingasynchronous
Responsenone

This method deletes a virtual machine immediately. You will not be able to restore it afterwards.

Power Management

The API provides convenient methods to manage the power status of virtual machines. All power management methods take only one parameter - the ID of the virtual machine.

Power On

POST https://secure.hosting.de/api/machine/v1/jsonxml/vmPwerOn
{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "vmId": "150101aaaaaaaaaa001"
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <vmId>150101aaaaaaaaaa001</vmId> 
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "product": "machine-virtualmachine-small-v1-1",
    "memory": 1024,
    "cpuNumber": 1,
    "architecture": "x86_64",
    "ipAddress": "192.0.2.2",
    "networkInterfaces": [
      {
        "mac": "1a:01:b7:4e:32:d3"
      }
    ],
    "status": "active",
    "power": "off",
    "rescue": "off",
    "rdns": null,
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,   
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }  
}
<response>
 <response>  
  <response>
    <id>150101aaaaaaaaaa001</id>
    <accountId>15010100000001</accountId>
    <name>example vm</name>
    <description>test vm</description>
    <product>machine-virtualmachine-small-v1-1</product>
    <memory>1024</memory>
    <cpuNumber>1</cpuNumber>
    <architecture>x86_64</architecture>
    <ipAddress>192.0.2.2</ipAddress>
    <networkInterfaces>
      <item>
        <mac>1a:01:b7:4e:32:d3</mac>
      </item>
    </networkInterfaces>
    <status>active</status>
    <power>off</power>
    <rescue>off</rescue>
    <rdns></rdns>
    <paidUntil>2016-02-01T15:57:35Z</paidUntil>
    <renewOn>2016-01-31T15:57:35Z</renewOn>
    <deletionScheduledFor></deletionScheduledFor>
    <restorableUntil></restorableUntil>
    <addDate>2016-01-01T15:57:35Z</addDate>
    <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestvmPwerOn
Urlhttps://secure.hosting.de/api/machine/v1/jsonxml/vmPwerOn
Processingasynchronous
ResponseVm object

You can use the vmPowerOn method to turn on a virtual machine.

Power Off

POST https://secure.hosting.de/api/machine/v1/jsonxml/vmPwerOff
{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "vmId": "150101aaaaaaaaaa001"
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <vmId>150101aaaaaaaaaa001</vmId> 
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "product": "machine-virtualmachine-small-v1-1",
    "memory": 1024,
    "cpuNumber": 1,
    "architecture": "x86_64",
    "ipAddress": "192.0.2.2",
    "networkInterfaces": [
      {
        "mac": "1a:01:b7:4e:32:d3"
      }
    ],
    "status": "active",
    "power": "on",
    "rescue": "off",
    "rdns": null,
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,   
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }  
}
<response>
 <response>  
  <response>
    <id>150101aaaaaaaaaa001</id>
    <accountId>15010100000001</accountId>
    <name>example vm</name>
    <description>test vm</description>
    <product>machine-virtualmachine-small-v1-1</product>
    <memory>1024</memory>
    <cpuNumber>1</cpuNumber>
    <architecture>x86_64</architecture>
    <ipAddress>192.0.2.2</ipAddress>
    <networkInterfaces>
      <item>
        <mac>1a:01:b7:4e:32:d3</mac>
      </item>
    </networkInterfaces>
    <status>active</status>
    <power>on</power>
    <rescue>off</rescue>
    <rdns></rdns>
    <paidUntil>2016-02-01T15:57:35Z</paidUntil>
    <renewOn>2016-01-31T15:57:35Z</renewOn>
    <deletionScheduledFor></deletionScheduledFor>
    <restorableUntil></restorableUntil>
    <addDate>2016-01-01T15:57:35Z</addDate>
    <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestvmPwerOff
Urlhttps://secure.hosting.de/api/machine/v1/jsonxml/vmPwerOff
Processingasynchronous
ResponseVm object

The vmPowerOff method lets you turn off a virtual machine. It basically emulates unplugging the machine’s power adapter.

Shutdown

POST https://secure.hosting.de/api/machine/v1/jsonxml/vmShutdown
{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "vmId": "150101aaaaaaaaaa001"
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <vmId>150101aaaaaaaaaa001</vmId> 
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "product": "machine-virtualmachine-small-v1-1",
    "memory": 1024,
    "cpuNumber": 1,
    "architecture": "x86_64",
    "ipAddress": "192.0.2.2",
    "networkInterfaces": [
      {
        "mac": "1a:01:b7:4e:32:d3"
      }
    ],
    "status": "active",
    "power": "on",
    "rescue": "off",
    "rdns": null,
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,   
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }  
}
<response>
 <response>  
  <response>
    <id>150101aaaaaaaaaa001</id>
    <accountId>15010100000001</accountId>
    <name>example vm</name>
    <description>test vm</description>
    <product>machine-virtualmachine-small-v1-1</product>
    <memory>1024</memory>
    <cpuNumber>1</cpuNumber>
    <architecture>x86_64</architecture>
    <ipAddress>192.0.2.2</ipAddress>
    <networkInterfaces>
      <item>
        <mac>1a:01:b7:4e:32:d3</mac>
      </item>
    </networkInterfaces>
    <status>active</status>
    <power>on</power>
    <rescue>off</rescue>
    <rdns></rdns>
    <paidUntil>2016-02-01T15:57:35Z</paidUntil>
    <renewOn>2016-01-31T15:57:35Z</renewOn>
    <deletionScheduledFor></deletionScheduledFor>
    <restorableUntil></restorableUntil>
    <addDate>2016-01-01T15:57:35Z</addDate>
    <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestvmShutdown
Urlhttps://secure.hosting.de/api/machine/v1/jsonxml/vmShutdown
Processingasynchronous
ResponseVm object

By using the vmShutdown method you can gracefully shutdown a virtual machine. It will receive an ACPI shutdown request. If the currently installed operating system of the virtual machine does not handle ACPI request, this method will have no effect.

All operating systems you installed by using our installer system will automatically handle ACPI requests. For any other custom installations, you need to ensure that those request are handled properly.

Reboot

POST https://secure.hosting.de/api/machine/v1/jsonxml/vmReboot
{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "vmId": "150101aaaaaaaaaa001"
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <vmId>150101aaaaaaaaaa001</vmId> 
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "product": "machine-virtualmachine-small-v1-1",
    "memory": 1024,
    "cpuNumber": 1,
    "architecture": "x86_64",
    "ipAddress": "192.0.2.2",
    "networkInterfaces": [
      {
        "mac": "1a:01:b7:4e:32:d3"
      }
    ],
    "status": "active",
    "power": "on",
    "rescue": "off",
    "rdns": null,
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,   
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }  
}
<response>
 <response>  
  <response>
    <id>150101aaaaaaaaaa001</id>
    <accountId>15010100000001</accountId>
    <name>example vm</name>
    <description>test vm</description>
    <product>machine-virtualmachine-small-v1-1</product>
    <memory>1024</memory>
    <cpuNumber>1</cpuNumber>
    <architecture>x86_64</architecture>
    <ipAddress>192.0.2.2</ipAddress>
    <networkInterfaces>
      <item>
        <mac>1a:01:b7:4e:32:d3</mac>
      </item>
    </networkInterfaces>
    <status>active</status>
    <power>on</power>
    <rescue>off</rescue>
    <rdns></rdns>
    <paidUntil>2016-02-01T15:57:35Z</paidUntil>
    <renewOn>2016-01-31T15:57:35Z</renewOn>
    <deletionScheduledFor></deletionScheduledFor>
    <restorableUntil></restorableUntil>
    <addDate>2016-01-01T15:57:35Z</addDate>
    <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestvmReboot
Urlhttps://secure.hosting.de/api/machine/v1/jsonxml/vmReboot
Processingasynchronous
ResponseVm object

By using the vmReboot method you can gracefully reboot a virtual machine. Similarly to the vmShutdown method the virtual machine will also receive an ACPI request - this time for a reboot. If the currently installed operating system does not handle ACPI requests, this method will have no effect.

All operating systems you installed by using our installer system will automatically handle ACPI requests. For any other custom installations, you need to ensure that the ACPI requests are handled properly.

Reset

POST https://secure.hosting.de/api/machine/v1/jsonxml/vmReset
{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "vmId": "150101aaaaaaaaaa001"
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <vmId>150101aaaaaaaaaa001</vmId> 
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "product": "machine-virtualmachine-small-v1-1",
    "memory": 1024,
    "cpuNumber": 1,
    "architecture": "x86_64",
    "ipAddress": "192.0.2.2",
    "networkInterfaces": [
      {
        "mac": "1a:01:b7:4e:32:d3"
      }
    ],
    "status": "active",
    "power": "on",
    "rescue": "off",
    "rdns": null,
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,   
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }  
}
<response>
 <response>  
  <response>
    <id>150101aaaaaaaaaa001</id>
    <accountId>15010100000001</accountId>
    <name>example vm</name>
    <description>test vm</description>
    <product>machine-virtualmachine-small-v1-1</product>
    <memory>1024</memory>
    <cpuNumber>1</cpuNumber>
    <architecture>x86_64</architecture>
    <ipAddress>192.0.2.2</ipAddress>
    <networkInterfaces>
      <item>
        <mac>1a:01:b7:4e:32:d3</mac>
      </item>
    </networkInterfaces>
    <status>active</status>
    <power>on</power>
    <rescue>off</rescue>
    <rdns></rdns>
    <paidUntil>2016-02-01T15:57:35Z</paidUntil>
    <renewOn>2016-01-31T15:57:35Z</renewOn>
    <deletionScheduledFor></deletionScheduledFor>
    <restorableUntil></restorableUntil>
    <addDate>2016-01-01T15:57:35Z</addDate>
    <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestvmReset
Urlhttps://secure.hosting.de/api/machine/v1/jsonxml/vmReset
Processingasynchronous
ResponseVm object

By using the vmReset method the user can reset a virtual machine. This method emulates the behavior of pushing the reset power button.

Web Hosting

The web hosting section of the API allows you to create and manage web spaces and web hosting domains.

Each website is configured in a vhost (virtual host) that is contained in a webspace.

The webspace represents storage on a concrete web server in the platform. This is where cron jobs and access permissions are managed. One webspace can contain multiple vhosts.

The vhost represents a website and contains website specific settings like domain name, php version, SSL settings, redirects, and special handling for locations.

The User Object

The user object describes a user who can be authorized to access a web space. One user can be authorized in any number of web spaces. Central management of passwords and SSH keys is possible.

{
    "accountId": "15010100000001",
    "addDate": "2016-03-14T08:50:53Z",
    "comment": "",
    "id": "15010100000091",
    "lastChangeDate": "2016-03-14T08:50:53Z",
    "name": "John Smith",
    "sshKey": "",
    "status": "active",
    "userName": "ayapzk"
}
<user>
 <accountId>15010100000001</accountId>
 <addDate>2016-03-14T08:50:53Z</addDate>
 <comment></comment>
 <id>15010100000091</id>
 <lastChangeDate>2016-03-14T08:50:53Z</lastChangeDate>
 <name>John Smith</name>
 <sshKey></sshKey>
 <status>active</status>
 <userName>ayapzk</userName>
</user>

User Object

Property Type Required Description
id string cf. description Ignored in user create requests. Required in all other requests
accountId string out-only ID of account managing user
name string req Name of user (for display purposes)
userName string out-only user key: short alphanumeric string used for generating unique webspace access names
sshKey string opt Public SSH key of user in same as in authorized_keys file of openssh
comment string opt Additional information about user. Value can be freely defined by platform account holder.
status string out-only user status
addDate datetime out-only Date and time of user creation
lastChangeDate datetime out-only Date and time of last user modification

The Webspace Object

The object that describes a web space is the webspace object.

{
    "accesses": [
        {
            "addDate": "2016-03-14T09:11:24Z",
            "ftpAccess": true,
            "lastChangeDate": "2016-03-14T09:11:24Z",
            "sshAccess": true,
            "statsAccess": true,
            "userId": "15010100000091",
            "userName": "webv4h25r_ayapzk",
            "webspaceId": "15010100000094"
        }
    ],
    "accountId": "15010100000001",
    "addDate": "2016-03-14T09:11:24Z",
    "cronJobs": [
    ],
    "currentContractPeriodEnd": "2016-04-14T09:11:24Z",
    "deletionDate": null,
    "id": "15010100000094",
    "lastChangeDate": "2016-03-14T09:11:24Z",
    "name": "Example",
    "product": "Default",
    "restorableUntil": null,
    "serverIpv4": "192.0.2.80",
    "status": "creating",
    "storageQuota": 10240,
    "storageQuotaUsedRatio": 0,
    "storageUsed": 0,
    "webspaceName": "webv4h25r"
}
<webspace>
 <accesses>
  <item>
   <addDate>2016-03-14T09:11:24Z</addDate>
   <ftpAccess>true</ftpAccess>
   <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
   <sshAccess>true</sshAccess>
   <statsAccess>true</statsAccess>
   <userId>15010100000091</userId>
   <userName>webv4h25r_ayapzk</userName>
   <webspaceId>15010100000094</webspaceId>
  </item>
 </accesses>
 <accountId>1</accountId>
 <addDate>2016-03-14T09:11:24Z</addDate>
 <cronJobs/>
 <currentContractPeriodEnd>2016-04-14T09:11:24Z</currentContractPeriodEnd>
 <deletionDate></deletionDate>
 <id>15010100000094</id>
 <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
 <name>Example</name>
 <product>Default</product>
 <restorableUntil></restorableUntil>
 <serverIpv4>192.0.2.80</serverIpv4>
 <status>creating</status>
 <storageQuota>10240</storageQuota>
 <storageQuotaUsedRatio>0</storageQuotaUsedRatio>
 <storageUsed>0</storageUsed>
 <webspaceName>webv4h25r</webspaceName>
</webspace>

Webspace Object

Property Type Required Description
id string cf. description ID of webspace. Ignored in webspace create requests. Required in all other requests.
accountId string out-only ID of managing account
name string req Name of webspace
webspaceName string opt webspace key: short alphanumeric string used as unique identifier system generated names.
productCode string req product code for this webspace.
storageQuota int out-only
storageUsed int out-only
storageQuotaUsedRatio double out-only
status string out-only Status of webspace
accesses list<WebspaceAccess> out-only A list of WebspaceAccess objects with all current authorizations for users.
serverIpv4 string out-only The IPv4 address to configure for domains using the webspace in DNS.
cronJobs list<CronJob> opt A list of CronJob objects describing active cron jobs for the webspace.
paidUntil datetime out-only Time that the webspace is paid for
deletionScheduledFor datetime out-only Deletion date and time of webspace
restorableUntil datetime out-only Date and time until webspace is restorable
addDate datetime out-only Date and time of webspace creation
lastChangeDate datetime out-only Date and time of last webspace modification

The WebspaceAccess Object

The WebspaceAccess object is a helper object to describe a user’s access level to a webspace.

{
    "addDate": "2016-03-14T09:11:24Z",
    "ftpAccess": true,
    "lastChangeDate": "2016-03-14T09:11:24Z",
    "sshAccess": true,
    "statsAccess": true,
    "userId": "15010100000091",
    "userName": "webv4h25r_ayapzk",
    "webspaceId": "15010100000094"
}
<webspaceAccess>
 <addDate>2016-03-14T09:11:24Z</addDate>
 <ftpAccess>true</ftpAccess>
 <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
 <sshAccess>true</sshAccess>
 <statsAccess>true</statsAccess>
 <userId>15010100000091</userId>
 <userName>webv4h25r_ayapzk</userName>
 <webspaceId>15010100000094</webspaceId>
</webspaceAccess>

WebspaceAccess Object

Property Type Required Description
webspaceId string out-only ID of webspace the user with userId is authorized to access
userId string req ID of authorized user
userName string out-only Generated name for accessing webspace (cf. Webspace Access Names for details)
ftpAccess bool opt If set to true, user is authorized to access webspace using ftp protocol
sshAccess bool opt If set to true, user is authorized to access webspace using ssh protocol (sftp, scp, interactive ssh login)
statsAccess bool opt If set to true, user is authorized to see access statistics of webspace
addDate datetime out-only Date and time of webspace access creation
lastChangeDate datetime out-only Date and time of last webspace access modification

Webspace Access Names

Each Webspace Access has a unique name that e.g. is used when accessing the webspace using FTP or SSH. If webxxxxxx is the web space key and yyyyyy is the user key, the name of the Webspace Access will look like this: webxxxxxx_yyyyyy

Listing Web Spaces

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/webspacesFind
{
    "authToken": "$$YOUR API KEY$$",
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "webspaceName",
        "order": "ASC"
    }
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>webspaceName</field>
  <order>ASC</order>
 </sort>
</request>

Response
{
    ...
    "response": {
        "data": [
            // webspace objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 33,
        "totalPages": 4,
        "type": "FindWebspacesResult"
    },
    ...
}

<response>
 <response>
  <data/>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>33</totalEntries>
  <totalPages>4</totalPages>
  <type>FindWebspacesResult</type>
 </response>
</response>

RequestwebspacesFind
Urlhttps://secure.hosting.de/api/webhosting/v1/jsonxml/webspacesFind
Processingsynchronous
ResponseFindWebspacesResult

The function webspacesFind lets you list web spaces. The usual filtering and sorting options apply. The response will contain a list of Webspace objects.

The following fields are available for filtering and sorting:

Field Description
AccountId ID of managing account
WebspaceId ID of webspace
WebspaceName Name of webspace
WebspaceWebspaceName webspace key: short alphanumeric string used as unique identifier system generated names.
WebspaceProductCode The product code of the webspace
WebspaceStorageQuota
WebspaceStorageUsed
WebspaceStorageQuotaUsedRatio
WebspaceStatus Status of webspace
WebspaceDeletionScheduledFor Deletion date and time of webspace
WebspaceRestorableUntil Date and time until webspace is restorable
WebspacePaidUntil Time that the webspace is paid for
WebspaceLastChangeDate Date and time of last webspace modification
WebspaceAddDate Date and time of webspace creation
WebspaceAccessesUserId Matches webspaces for which user is authorized

Creating Webspaces

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/webspaceCreate
{
    "authToken": "$$YOUR API KEY$$",
    "webspace": {
        "name": "Example",
        "productCode": "webhosting-webspace",
        "storageQuota": 10240
    },
    "accesses": [
        {
            "userId": "15010100000091",
            "ftpAccess": true,
            "sshAccess": true,
            "statsAccess": true
        }
    ]
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <webspace>
  <name>Example</name>
  <productCode>webhosting-webspace</productCode>
  <storageQuota>10240</storageQuota>
 </webspace>
 <accesses>
  <item>
   <ftpAccess>true</ftpAccess>
   <sshAccess>true</sshAccess>
   <statsAccess>true</statsAccess>
   <userId>15010100000091</userId>
  </item>
 </accesses>
</request>

Response
{
    ...
    "response": {
        "id": "15010100000094",
        "accountId": "15010100000001",
        "webspaceName": "webv4h25r",
        "accesses": [
            {
                "addDate": "2016-03-14T09:11:24Z",
                "ftpAccess": true,
                "lastChangeDate": "2016-03-14T09:11:24Z",
                "sshAccess": true,
                "statsAccess": true,
                "userId": "15010100000091",
                "userName": "webv4h25r_ayapzk",
                "webspaceId": "15010100000094"
            }
        ],
        "addDate": "2016-03-14T09:11:24Z",
        "cronJobs": [
        ],
        "paidUntil": "2016-04-14T09:11:24Z",
        "deletionScheduledFor": null,
        "lastChangeDate": "2016-03-14T09:11:24Z",
        "name": "Example",
        "productCode": "webhosting-webspace",
        "restorableUntil": null,
        "serverIpv4": "192.0.2.80",
        "status": "creating",
        "storageQuota": 10240,
        "storageQuotaUsedRatio": 0,
        "storageUsed": 0
    },
    ...
}

<response>
 <response>
  <id>15010100000094</id>
  <accountId>15010100000001</accountId>
  <webspaceName>webv4h25r</webspaceName>
  <accesses>
   <item>
    <addDate>2016-03-14T09:11:24Z</addDate>
    <ftpAccess>true</ftpAccess>
    <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
    <sshAccess>true</sshAccess>
    <statsAccess>true</statsAccess>
    <userId>15010100000091</userId>
    <userName>webv4h25r_ayapzk</userName>
    <webspaceId>15010100000094</webspaceId>
   </item>
  </accesses>
  <addDate>2016-03-14T09:11:24Z</addDate>
  <cronJobs/>
  <paidUntil>2016-04-14T09:11:24Z</paidUntil>
  <deletionScheduledFor></deletionScheduledFor>
  <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
  <name>Example</name>
  <productCode>webhosting-webspace</productCode>
  <restorableUntil></restorableUntil>
  <serverIpv4>192.0.2.80</serverIpv4>
  <status>creating</status>
  <storageQuota>10240</storageQuota>
  <storageQuotaUsedRatio>0</storageQuotaUsedRatio>
  <storageUsed>0</storageUsed>
 </response>
</response>

RequestwebspaceCreate
Urlhttps://secure.hosting.de/api/webhosting/v1/jsonxml/webspaceCreate
Processingasynchronous
ResponseWebspace
Parameter Type Required Description
webspace Webspace object req Complete webspace object
accesses list<WebspaceAccess object> req List of user authorizations with access to webspace (list may be empty)
poolId string opt Needed if managed server product is purchased: Use managed server pool instead of shared servers.

You can use the function webspaceCreate create a new webspace. After the webspace is created users who are authorized can connect to the it using FTP and SSH.

Updating Webspaces

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/webspaceUpdate
{
    "authToken": "$$YOUR API KEY$$",
    "webspace": {
        "cronJobs": [],
        "id": "15010100000094",
        "name": "Example",
        "productCode": "webhosting-webspace",
        "serverIpv4": "192.0.2.80",
        "storageQuota": 10240
    },
    "accesses": [
        {
            "addDate": "2016-03-14T09:11:24Z",
            "ftpAccess": false,
            "lastChangeDate": "2016-03-14T09:11:24Z",
            "sshAccess": true,
            "statsAccess": false,
            "userId": "15010100000091",
            "userName": "webv4h25r_ayapzk",
            "webspaceId": "15010100000094"
        }
    ]
}

<request>
 <accesses>
  <item>
   <addDate>2016-03-14T09:11:24Z</addDate>
   <ftpAccess>false</ftpAccess>
   <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
   <sshAccess>true</sshAccess>
   <statsAccess>false</statsAccess>
   <userId>15010100000091</userId>
   <userName>webv4h25r_ayapzk</userName>
   <webspaceId>15010100000094</webspaceId>
  </item>
 </accesses>
 <authToken>$$YOUR API KEY$$</authToken>
 <webspace>
  <cronJobs/>
  <id>15010100000094</id>
  <name>Example</name>
  <productCode>webhosting-webspace</productCode>
  <serverIpv4>192.0.2.80</serverIpv4>
  <storageQuota>10240</storageQuota>
 </webspace>
</request>

Response
{
    ...
    "response": {
        "accesses": [
            {
                "addDate": "2016-03-14T09:11:24Z",
                "ftpAccess": false,
                "lastChangeDate": "2016-03-14T09:28:35Z",
                "sshAccess": true,
                "statsAccess": false,
                "userId": "15010100000091",
                "userName": "webv4h25r_ayapzk",
                "webspaceId": "15010100000094"
            }
        ],
        "accountId": "15010100000001",
        "addDate": "2016-03-14T09:11:24Z",
        "cronJobs": [
        ],
        "paidUntil": "2016-04-14T09:11:24Z",
        "deletionScheduledFor": null,
        "id": "15010100000094",
        "lastChangeDate": "2016-03-14T09:28:35Z",
        "name": "Example",
        "productCode": "webhosting-webspace",
        "restorableUntil": null,
        "serverIpv4": "192.0.2.80",
        "status": "active",
        "storageQuota": 10240,
        "storageQuotaUsedRatio": 0,
        "storageUsed": 0,
        "webspaceName": "webv4h25r"
    },
    ...
}

<response>
 <response>
  <accesses>
   <item>
    <addDate>2016-03-14T09:11:24Z</addDate>
    <ftpAccess>false</ftpAccess>
    <lastChangeDate>2016-03-14T09:28:35Z</lastChangeDate>
    <sshAccess>true</sshAccess>
    <statsAccess>false</statsAccess>
    <userId>15010100000091</userId>
    <userName>webv4h25r_ayapzk</userName>
    <webspaceId>15010100000094</webspaceId>
   </item>
  </accesses>
  <accountId>15010100000001</accountId>
  <addDate>2016-03-14T09:11:24Z</addDate>
  <cronJobs/>
  <paidUntil>2016-04-14T09:11:24Z</paidUntil>
  <deletionScheduledFor></deletionScheduledFor>
  <id>15010100000094</id>
  <lastChangeDate>2016-03-14T09:28:35Z</lastChangeDate>
  <name>Example</name>
  <productCode>webhosting-webspace</productCode>
  <restorableUntil></restorableUntil>
  <serverIpv4>192.0.2.80</serverIpv4>
  <status>active</status>
  <storageQuota>10240</storageQuota>
  <storageQuotaUsedRatio>0</storageQuotaUsedRatio>
  <storageUsed>0</storageUsed>
  <webspaceName>webv4h25r</webspaceName>
 </response>
</response>

RequestwebspaceUpdate
Urlhttps://secure.hosting.de/api/webhosting/v1/jsonxml/webspaceUpdate
Processingasynchronous
ResponseWebspace
Parameter Type Required Description
webspace Webspace object req Complete webspace object
accesses list<WebspaceAccess object> req List of user authorizations with access to webspace (list may be empty)

The webspace that you want to update is identified by it’s id. All fields not marked out-only are set to the values in the webspace argument. Optional fields that are not specified in this call are reset to their default values.

The list of authorized users for this webspace is replaced by the list in the parameter accesses.

Deleting Webspaces

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/webspaceDelete
{
    "authToken": "$$YOUR API KEY$$",
    "webspaceId": "15010100000094"
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <webspaceId>15010100000094</webspaceId>
</request>

Response
{
    ...
    "response": {
        "accesses": [
            {
                "addDate": "2016-03-14T09:11:24Z",
                "ftpAccess": false,
                "lastChangeDate": "2016-03-14T09:28:35Z",
                "sshAccess": true,
                "statsAccess": false,
                "userId": "15010100000091",
                "userName": "webv4h25r_ayapzk",
                "webspaceId": "15010100000094"
            }
        ],
        "accountId": "15010100000001",
        "addDate": "2016-03-14T09:11:24Z",
        "cronJobs": [],
        "paidUntil": "2016-04-14T09:11:24Z",
        "deletionScheduledFor": null,
        "id": "15010100000094",
        "lastChangeDate": "2016-03-14T09:28:36Z",
        "name": "Example",
        "productCode": "webhosting-webspace",
        "restorableUntil": null,
        "serverIpv4": "192.0.2.80",
        "status": "active",
        "storageQuota": 10240,
        "storageQuotaUsedRatio": 0,
        "storageUsed": 0,
        "webspaceName": "webv4h25r"
    },
    ...
}

<response>
 <response>
  <accesses>
   <item>
    <addDate>2016-03-14T09:11:24Z</addDate>
    <ftpAccess>false</ftpAccess>
    <lastChangeDate>2016-03-14T09:28:35Z</lastChangeDate>
    <sshAccess>true</sshAccess>
    <statsAccess>false</statsAccess>
    <userId>15010100000091</userId>
    <userName>webv4h25r_ayapzk</userName>
    <webspaceId>15010100000094</webspaceId>
   </item>
  </accesses>
  <accountId>15010100000001</accountId>
  <addDate>2016-03-14T09:11:24Z</addDate>
  <cronJobs/>
  <paidUntil>2016-04-14T09:11:24Z</paidUntil>
  <deletionScheduledFor></deletionScheduledFor>
  <id>15010100000094</id>
  <lastChangeDate>2016-03-14T09:28:36Z</lastChangeDate>
  <name>Example</name>
  <productCode>webhosting-webspace</productCode>
  <restorableUntil></restorableUntil>
  <serverIpv4>192.0.2.80</serverIpv4>
  <status>active</status>
  <storageQuota>10240</storageQuota>
  <storageQuotaUsedRatio>0</storageQuotaUsedRatio>
  <storageUsed>0</storageUsed>
  <webspaceName>webv4h25r</webspaceName>
 </response>
</response>

RequestwebspaceDelete
Urlhttps://secure.hosting.de/api/webhosting/v1/jsonxml/webspaceDelete
Processingasynchronous
ResponseWebspace
Parameter Type Required Description
webspaceId string req ID of webspace to be deleted

The request webspace Delete deletes the specified webspace. All vhosts in the webspace are automatically deleted too.

Listing Users

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/usersFind
{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "userName",
        "value": "*Smith*"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "userName",
        "order": "ASC"
    }
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <field>userName</field>
  <value>*Smith*</value>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>userName</field>
  <order>ASC</order>
 </sort>
</request>

Response
{
    ...
    "response": {
        "data": [
            // user objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 1,
        "totalPages": 1,
        "type": "FindUsersResult"
    },
    ...
}

<response>
 <response>
  <data/>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>1</totalEntries>
  <totalPages>1</totalPages>
  <type>FindUsersResult</type>
 </response>
</response>

RequestusersFind
Urlhttps://secure.hosting.de/api/webhosting/v1/jsonxml/usersFind
Processingsynchronous
ResponseFindUsersResult

The function usersFind lets you list users. The usual filtering and sorting options apply. The response will contain a list of User objects.

The following fields are available for filtering and sorting:

Field Description
AccountId ID of managing account
UserId ID of user
UserName Name of user (for display purposes)
UserUserName Unique user name generated as access account name
UserComment Additional information about user. Value can be freely defined by platform account holder.
UserStatus The status of user
UserLastChangeDate Date and time of last user modification
UserAddDate Date and time of user creation

Creating Users

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/userCreate
{
    "authToken": "$$YOUR API KEY$$",
    "user": {
        "name": "John Smith"
    },
    "password": "57BGnyzxFgIn"
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <password>57BGnyzxFgIn</password>
 <user>
  <name>John Smith</name>
 </user>
</request>

Response
{
    ...
    "response": {
        "accountId": "15010100000001",
        "addDate": "2016-03-14T08:50:53Z",
        "comment": "",
        "id": "15010100000091",
        "lastChangeDate": "2016-03-14T08:50:53Z",
        "name": "John Smith",
        "sshKey": "",
        "status": "active",
        "userName": "ayapzk"
    },
    ...
}

<response>
 <response>
  <accountId>1</accountId>
  <addDate>2016-03-14T08:50:53Z</addDate>
  <comment></comment>
  <id>15010100000091</id>
  <lastChangeDate>2016-03-14T08:50:53Z</lastChangeDate>
  <name>John Smith</name>
  <sshKey></sshKey>
  <status>active</status>
  <userName>ayapzk</userName>
 </response>
</response>

RequestuserCreate
Urlhttps://secure.hosting.de/api/webhosting/v1/jsonxml/userCreate
Processingsynchronous
ResponseUser
Parameter Type Required Description
user User object req Complete user object
password string req user password in plain text

The usersCreate request lets you create new users that can later be authorized to access web spaces.

The user password can only be set using this request or an update. It can not be read back from the system because it is stored as a secure one way hash in the system.

Updating Users

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/userUpdate
{
    "authToken": "$$YOUR API KEY$$",
    "user": {
        "comment": "Had to change password on customer request.",
        "id": "15010100000091",
        "name": "John Smith",
        "sshKey": "",
        "status": "active",
        "userName": "ayapzk"
    },
    "password": "OgL2OtCHnOTd"
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <password>OgL2OtCHnOTd</password>
 <user>
  <comment>Had to change password on customer request.</comment>
  <id>15010100000091</id>
  <name>John Smith</name>
  <sshKey></sshKey>
  <status>active</status>
  <userName>ayapzk</userName>
 </user>
</request>

Response
{
    ...
    "response": {
        "accountId": "15010100000001",
        "addDate": "2016-03-14T08:50:53Z",
        "comment": "Had to change password on customer request.",
        "id": "15010100000091",
        "lastChangeDate": "2016-03-14T09:04:23Z",
        "name": "John Smith",
        "sshKey": "",
        "status": "active",
        "userName": "ayapzk"
    },
    ...
}

<response>
 <response>
  <accountId>1</accountId>
  <addDate>2016-03-14T08:50:53Z</addDate>
  <comment>Had to change password on customer request.</comment>
  <id>15010100000091</id>
  <lastChangeDate>2016-03-14T09:04:23Z</lastChangeDate>
  <name>John Smith</name>
  <sshKey></sshKey>
  <status>active</status>
  <userName>ayapzk</userName>
 </response>
</response>

RequestuserUpdate
Urlhttps://secure.hosting.de/api/webhosting/v1/jsonxml/userUpdate
Processingasynchronous
ResponseUser
Parameter Type Required Description
user User object req Complete user object
password string opt You can change user password to new value (plain text)

By using the usersUpdate request the name, comment, and SSH key of a user are replaced with the values that you supplied in this request.

If an new password is specified, it will replace the currently stored password. If an empty password or no password is supplied, the current password will not be changed.

Deleting Users

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/userDelete
{
    "authToken": "$$YOUR API KEY$$",
    "userId": "15010100000091"
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <userId>15010100000091</userId>
</request>

Response
{
    "status": "success",
    ...
}

<response>
    <response>success</response>
    ...
</response>

RequestuserDelete
Urlhttps://secure.hosting.de/api/webhosting/v1/jsonxml/userDelete
Processingsynchronous
Responsenone
Parameter Type Required Description
userId string req ID of user to be delete

By using the userDelete request you can delete a user that is currently not authorized to access any web space.

When you delete a web space all contained files will also be deleted permanently.

The CronJob Object

The system supports running regular tasks in a webspace. These tasks are controlled by so called cron jobs that specify how often you should run a job and what action you should take.

You can either run a PHP or bash script - or you can request a URL in one of the webspace’s vhosts.

CronJob Object

Property Type Required Description
comment string opt Additional information about cron job. Value can be freely defined by platform account holder.
type string req Available options: url, php, or bash
script string cf. description Required if type is php or bash. Script to run. Should start with ‘data/’ or ‘html/’ and contain path to script running relative to webspace’s home directory.
url string cf. description Required if type is url. This url to access. This must be an url using the http or https schema and will be accesses using the ‘GET’ http method.
schedule string req Available schedule options: 1min, 5min, 10min15min,30min,1hour,2hour,3hour,4hour,6hour,12hour,daily,weekly, ormonthly`.
daypart string cf. description Required for daily or larger intervals. Specifies time window the cron job will be running. Available interval options: 1-5, 5-9, 9-13, 13-17, 17-21, or 21-1.
weekday string cf. description Required for weekly schedule. Available options: mon, tue, wed, thu, fri, sat, or sun.
dayOfMonth int cf. description Required for monthly schedule. Day of month the cron job should be run.

The VHost Object

{
    "accountId": "15010100000001",
    "addDate": "2016-03-14T09:22:19Z",
    "blocked": null,
    "domainName": "example.org",
    "domainNameUnicode": "example.org",
    "enableAlias": false,
    "enableSystemAlias": true,
    "id": "15010100000095",
    "lastChangeDate": "2016-03-14T09:22:19Z",
    "locations": [
        {
            "directoryListingEnabled": false,
            "locationType": "generic",
            "mapScript": "",
            "mapStyle": "",
            "matchString": "",
            "matchType": "default",
            "phpEnabled": true,
            "redirectionStatus": "",
            "redirectionUrl": "",
            "setByProfile": false,
            "superUserConfiguration": ""
        }
    ],
    "phpVersion": "5.6",
    "profile": "",
    "redirectToPrimaryName": false,
    "serverType": "nginx",
    "sslSettings": null,
    "status": "creating",
    "systemAlias": "15010100000095.wh.hosting.zone",
    "webRoot": "example.org",
    "webspaceId": "15010100000094"
}

<vhost>
 <accountId>1</accountId>
 <addDate>2016-03-14T09:22:19Z</addDate>
 <blocked></blocked>
 <domainName>example.org</domainName>
 <domainNameUnicode>example.org</domainNameUnicode>
 <enableAlias>false</enableAlias>
 <enableSystemAlias>true</enableSystemAlias>
 <id>15010100000095</id>
 <lastChangeDate>2016-03-14T09:22:19Z</lastChangeDate>
 <locations>
  <item>
   <directoryListingEnabled>false</directoryListingEnabled>
   <locationType>generic</locationType>
   <mapScript></mapScript>
   <mapStyle></mapStyle>
   <matchString></matchString>
   <matchType>default</matchType>
   <phpEnabled>true</phpEnabled>
   <redirectionStatus></redirectionStatus>
   <redirectionUrl></redirectionUrl>
   <setByProfile>false</setByProfile>
   <superUserConfiguration></superUserConfiguration>
  </item>
 </locations>
 <phpVersion>5.6</phpVersion>
 <profile></profile>
 <redirectToPrimaryName>false</redirectToPrimaryName>
 <serverType>nginx</serverType>
 <sslSettings></sslSettings>
 <status>creating</status>
 <systemAlias>15010100000095.wh.hosting.zone</systemAlias>
 <webRoot>example.org</webRoot>
 <webspaceId>15010100000094</webspaceId>
</vhost>

VHost Object

Property Type Required Description
id string cf. description vhost ID. Ignored in vhost create requests. Required in all other requests.
accountId string out-only ID of account managing vhost
webspaceId string out-only ID of webspace the vhost is part of
domainName string req Name of domain. Can be either in Unicode or ASCII format. Name will always be returned in ASCII/ACE format.
domainNameUnicode string out-only Name of domain in Unicode/international format
enableAlias bool opt If set to true, alternate name is enabled to access vhost (cf. below for more information)
redirectToPrimaryName bool opt If set to true, access of alternate name will be redirected to primary name
enableSystemAlias bool opt If set to true, webspace will temporarily be accessible via auto generated domain name. This is intended for websites prior to live usage.
systemAlias string out-only If enableSystemAlias is set to true, the vhost is also available via this domain name.
status string opt Status of webspace
webRoot string opt Specifies sub directory in “html/” where website files are accessed. If empty, it defaults to the ASCII format of domainName.
profile string opt Profile using vhost (if set)
serverType string req Server type of vhost. Available options: apache, nginx.
locations list<Location> opt List of Location objects
sslSettings SSLSettings opt If set, SSL is enabled
phpVersion string opt php version used to execute php scripts. Available options: 5.6 or 7.0. Default: 5.6.
addDate datetime out-only Date and time of vhost creation
lastChangeDate datetime out-only Date and time of last vhost modification

VHost Alternate Names

You can enable alternate names for vhosts: For example, your vhost is able to cover both www.example.com and example.com. If the primary name (the name that is passed in the domainName attribute) starts with ‘www.’, the alternate name of the vhost will be the primary name without ’www.’. If the primary name doesn’t start with ’www.’, the alternate name will be the primary name with prepended ’www.’. A vhost covers the alternate name if its enableAlias is set to true.

Listing VHosts

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostsFind
{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "webspaceName",
        "value": "*example*"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "webspaceName",
        "order": "ASC"
    }
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <field>webspaceName</field>
  <value>*example*</value>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>webspaceName</field>
  <order>ASC</order>
 </sort>
</request>

Response
{
    ...
    "response": {
        "data": [
            // VHost objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 1,
        "totalPages": 1,
        "type": "FindWebspacesResult"
    },
    ...
}

<response>
 <response>
  <data/>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>1</totalEntries>
  <totalPages>1</totalPages>
  <type>FindWebspacesResult</type>
 </response>
</response>

RequestvhostsFind
Urlhttps://secure.hosting.de/api/webhosting/v1/jsonxml/vhostsFind
Processingsynchronous
ResponseFindVHostsResult

You can list vhosts with the method vhostsFind. The response will contain a list of VHost objects. The usual filtering and sorting options apply.

The following fields are available for filtering and sorting:

Field Description
AccountId ID of managing account
WebspaceId ID of webspace the vhost is part of
VHostId ID of vhost
VHostDomainName Domain name. Pleasae use ASCII/ACE format
VHostDomainNameUnicode Domain name in Unicode/international format
VHostEnableAlias If set to true, alternate name will be enabled for accessing vhost.
VHostEnableSystemAlias If set to true, access for vhost using system alias is enabled
VHostRedirectToPrimaryName If set to true, any access of alternate name is redirected to primary name
VHostStatus Status of vhost
VHostLastChangeDate Date and time of last vhost modification
VHostAddDate Date and time of vhost creation

Creating VHosts

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostCreate
{
    "authToken": "$$YOUR API KEY$$",
    "vhost": {
        "webspaceId": "15010100000094",
        "serverType": "nginx",
        "domainName": "example.org",
        "enableAlias": false,
        "enableSystemAlias": true,
        "redirectToPrimaryName": false,
        "locations": [
            {
                "locationType": "generic",
                "matchType": "default",
                "matchString": "",
                "phpEnabled": true,
                "directoryListingEnabled": false
            }
        ],
        "phpVersion": "5.6",
        "profile": "",
        "sslSettings": null,
        "webRoot": "example.org"
    }
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <vhost>
  <domainName>example.org</domainName>
  <enableAlias>false</enableAlias>
  <enableSystemAlias>true</enableSystemAlias>
  <locations>
   <item>
    <directoryListingEnabled>false</directoryListingEnabled>
    <locationType>generic</locationType>
    <matchString></matchString>
    <matchType>default</matchType>
    <phpEnabled>true</phpEnabled>
   </item>
  </locations>
  <phpVersion>5.6</phpVersion>
  <profile></profile>
  <redirectToPrimaryName>false</redirectToPrimaryName>
  <serverType>nginx</serverType>
  <sslSettings></sslSettings>
  <webRoot>example.org</webRoot>
  <webspaceId>15010100000094</webspaceId>
 </vhost>
</request>

Response
{
    ...
    "response": {
        "accountId": "15010100000001",
        "addDate": "2016-03-14T09:22:19Z",
        "blocked": null,
        "domainName": "example.org",
        "domainNameUnicode": "example.org",
        "enableAlias": false,
        "enableSystemAlias": true,
        "id": "15010100000095",
        "lastChangeDate": "2016-03-14T09:22:19Z",
        "locations": [
            {
                "directoryListingEnabled": false,
                "locationType": "generic",
                "mapScript": "",
                "mapStyle": "",
                "matchString": "",
                "matchType": "default",
                "phpEnabled": true,
                "redirectionStatus": "",
                "redirectionUrl": "",
                "setByProfile": false,
                "superUserConfiguration": ""
            }
        ],
        "phpVersion": "5.6",
        "profile": "",
        "redirectToPrimaryName": false,
        "serverType": "nginx",
        "sslSettings": null,
        "status": "creating",
        "systemAlias": "15010100000095.wh.hosting.zone",
        "webRoot": "example.org",
        "webspaceId": "15010100000094"
    },
    ...
}

<response>
 <response>
  <accountId>15010100000001</accountId>
  <addDate>2016-03-14T09:22:19Z</addDate>
  <blocked></blocked>
  <domainName>example.org</domainName>
  <domainNameUnicode>example.org</domainNameUnicode>
  <enableAlias>false</enableAlias>
  <enableSystemAlias>true</enableSystemAlias>
  <id>15010100000095</id>
  <lastChangeDate>2016-03-14T09:22:19Z</lastChangeDate>
  <locations>
   <item>
    <directoryListingEnabled>false</directoryListingEnabled>
    <locationType>generic</locationType>
    <mapScript></mapScript>
    <mapStyle></mapStyle>
    <matchString></matchString>
    <matchType>default</matchType>
    <phpEnabled>true</phpEnabled>
    <redirectionStatus></redirectionStatus>
    <redirectionUrl></redirectionUrl>
    <setByProfile>false</setByProfile>
    <superUserConfiguration></superUserConfiguration>
   </item>
  </locations>
  <phpVersion>5.6</phpVersion>
  <profile></profile>
  <redirectToPrimaryName>false</redirectToPrimaryName>
  <serverType>nginx</serverType>
  <sslSettings></sslSettings>
  <status>creating</status>
  <systemAlias>15010100000095.wh.hosting.zone</systemAlias>
  <webRoot>example.org</webRoot>
  <webspaceId>15010100000094</webspaceId>
 </response>
</response>

RequestvhostCreate
Urlhttps://secure.hosting.de/api/webhosting/v1/jsonxml/vhostCreate
Processingasynchronous
ResponseVHost
Parameter Type Required Description
vhost VHost object req Complete vhost object
sslPrivateKey string opt Private SSL key in PEM format. Required when SSL is enabled.

The request vhostCreate lets you create a new vhost in a webspace. If you want to use manual SSL with this vhost, you have to pass the private key that corresponds to the certificate in the SSLSettings using the sslPrivateKey parameter.

Updating VHosts

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostUpdate
{
    "authToken": "$$YOUR API KEY$$",
    "vhost": {
        "domainName": "example.org",
        "enableAlias": false,
        "enableSystemAlias": true,
        "id": "15010100000095",
        "locations": [
            {
                "directoryListingEnabled": false,
                "locationType": "generic",
                "matchString": "",
                "matchType": "default",
                "phpEnabled": true,
                "setByProfile": false
            }
        ],
        "phpVersion": "5.6",
        "profile": "",
        "redirectToPrimaryName": false,
        "serverType": "nginx",
        "sslSettings": null,
        "webRoot": "example.org"
    }
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <vhost>
  <domainName>example.org</domainName>
  <enableAlias>false</enableAlias>
  <enableSystemAlias>true</enableSystemAlias>
  <id>15010100000095</id>
  <locations>
   <item>
    <directoryListingEnabled>false</directoryListingEnabled>
    <locationType>generic</locationType>
    <matchString></matchString>
    <matchType>default</matchType>
    <phpEnabled>true</phpEnabled>
    <setByProfile>false</setByProfile>
   </item>
  </locations>
  <phpVersion>5.6</phpVersion>
  <profile></profile>
  <redirectToPrimaryName>false</redirectToPrimaryName>
  <serverType>nginx</serverType>
  <sslSettings></sslSettings>
  <webRoot>example.org</webRoot>
 </vhost>
</request>

Response
{
    ...
    "response": {
        "accountId": "15010100000001",
        "addDate": "2016-03-14T09:22:19Z",
        "blocked": null,
        "domainName": "example.org",
        "domainNameUnicode": "example.org",
        "enableAlias": false,
        "enableSystemAlias": true,
        "id": "15010100000095",
        "lastChangeDate": "2016-03-14T09:34:29Z",
        "locations": [
            {
                "directoryListingEnabled": false,
                "locationType": "generic",
                "mapScript": "",
                "mapStyle": "",
                "matchString": "",
                "matchType": "default",
                "phpEnabled": true,
                "redirectionStatus": "",
                "redirectionUrl": "",
                "setByProfile": false,
                "superUserConfiguration": ""
            }
        ],
        "phpVersion": "5.6",
        "profile": "",
        "redirectToPrimaryName": false,
        "serverType": "nginx",
        "sslSettings": null,
        "status": "active",
        "systemAlias": "15010100000095.dev.webserver.keenlogics.com",
        "webRoot": "example.org",
        "webspaceId": "15010100000094"
    },
    ...
}

<response>
 <response>
  <accountId>15010100000001</accountId>
  <addDate>2016-03-14T09:22:19Z</addDate>
  <blocked></blocked>
  <domainName>example.org</domainName>
  <domainNameUnicode>example.org</domainNameUnicode>
  <enableAlias>false</enableAlias>
  <enableSystemAlias>true</enableSystemAlias>
  <id>15010100000095</id>
  <lastChangeDate>2016-03-14T09:34:29Z</lastChangeDate>
  <locations>
   <item>
    <directoryListingEnabled>false</directoryListingEnabled>
    <locationType>generic</locationType>
    <mapScript></mapScript>
    <mapStyle></mapStyle>
    <matchString></matchString>
    <matchType>default</matchType>
    <phpEnabled>true</phpEnabled>
    <redirectionStatus></redirectionStatus>
    <redirectionUrl></redirectionUrl>
    <setByProfile>false</setByProfile>
    <superUserConfiguration></superUserConfiguration>
   </item>
  </locations>
  <phpVersion>5.6</phpVersion>
  <profile></profile>
  <redirectToPrimaryName>false</redirectToPrimaryName>
  <serverType>nginx</serverType>
  <sslSettings></sslSettings>
  <status>active</status>
  <systemAlias>15010100000095.dev.webserver.keenlogics.com</systemAlias>
  <webRoot>example.org</webRoot>
  <webspaceId>15010100000094</webspaceId>
 </response>
</response>

RequestvhostUpdate
Urlhttps://secure.hosting.de/api/webhosting/v1/jsonxml/vhostUpdate
Processingasynchronous
ResponseVHost
Parameter Type Required Description
vhost VHost object req Complete vhost object
sslPrivateKey string opt Update of private SSL key. Required when new SSL certificate is used and private key associated with vhost does not match certificate.

The vhost to be updated is identified by its ID. All fields not marked with ‘out-only’ are set to the values of the vhost argument. Optional fields that are not specified in this call will be reset to their default values.

If the manual SSL mode is used and the certificate in the vhost is replaced with a certificate that is created from a different private key than the previous certificate, the corresponding private key to the new certificate must be passed by using the sslPrivateKey parameter.

Deleting VHosts

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostDelete
{
    "authToken": "$$YOUR API KEY$$",
    "vhostId": "15010100000095"
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <vhostId>15010100000095</vhostId>
</request>

Response
{
    "status": "success",
    ...
}

<response>
    <response>success</response>
    ...
</response>

RequestvhostDelete
Urlhttps://secure.hosting.de/api/webhosting/v1/jsonxml/vhostDelete
Processingasynchronous
Responsenone
Parameter Type Required Description
vhostId string req ID of vhost to be deleted

The function vhostDelete lets you delete vhosts. The vhost that you want to delete is identified by its ID.

If you delete a vhost, it will be deactivated and set to a state that is restorable for a limit time. After that the vhost will be deleted from the database. The actual files in the webspace belonging to the vhost will not be deleted automatically when a vhost is removed. The user has to delete these files manually.

Restoring VHosts

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostRestore
{
    "authToken": "$$YOUR API KEY$$",
    "vhostId": "15010100000095"
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <vhostId>15010100000095</vhostId>
</request>

Response
{
    "status": "success",
    ...
}

<response>
    <response>success</response>
    ...
</response>

RequestvhostRestore
Urlhttps://secure.hosting.de/api/webhosting/v1/jsonxml/vhostRestore
Processingasynchronous
Responsenone
Parameter Type Required Description
vhostId string req ID of vhost to be restored

You can restore a vhost that was deleted and is still in restorable state with the function vhostRestore. The vhost to be restored is identified by its ID. If the restore is successful and the webspace files for the vhost have not been manually deleted, the vhost will be restored to the state before it was deleted.