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$$",
				"relation": "unequal"
			}
		]
	},
	"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>
	<relation>unequal</relation>
   </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
relation	string	opt	Determins the relation between `field` and `value`. Defaults to ‘equal’

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.

The relation element specifies the comparison performed on field and the specific value. It is an optional element and defaults to ‘equal’ if not set. Please see the table below for further details and explainations.

Available relations

Relation	Description
equal	`field` must match `value` exactly
unequal	`field` must not be the same as `value`
greater	`field` must be greater than `value`. This might apply to e.g. an integer value, a date or a date time
less	`field` must be less than `value`. This might apply to e.g. an integer value, a date or a date time
greaterEqual	`field` must be greater than or equal to `value`. This might apply to e.g. an integer value, a date or a date time
lessEqual	`field` must be less than or equal to `value`. This might apply to e.g. an integer value, a date or a date time

{
	"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:

Person: Natural individual
Organization: Not a natural individual
Role: Abstract group of individuals

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>

Request	contactsFind
Url	https://secure.hosting.de/api/domain/v1/jsonxml/contactsFind
Processing	synchronous
Response	FindContactsResult

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.
ContactAddDate	Date and time the contact was created
ContactLastChangeDate	Date and time the contact was last modified

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>

Request	contactInfo
Url	https://secure.hosting.de/api/domain/v1/jsonxml/contactInfo
Processing	synchronous
Response	Contact 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>

Request	contactCreate
Url	https://secure.hosting.de/api/domain/v1/jsonxml/contactCreate
Processing	synchronous
Response	Contact 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>

Request	contactUpdate
Url	https://secure.hosting.de/api/domain/v1/jsonxml/contactUpdate
Processing	asynchronous
Response	Contact object

Parameter	Type	Required	Description
contact	Contact object	req	Complete contact object
actingAs	string	opt	see below

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.

The email of a contact that is linked to a domain in a generic extension (com, net, etc) may only be changed by an account that acts as an designated agent of both the new and the old contact.

By passing designatedAgent as the actingAs parameter you affirm that the current and the new contact have explicitly opted in to authorize you to approve a Change of Registrant on their behalf.

To check if an update is an owner change under ICANN rules (i.e. is material change and affects domains under icann rules) you can use the contactUpdateIsIcannOwnerChange api function.

Request	contactUpdateIsIcannOwnerChange
Url	https://secure.hosting.de/api/domain/v1/jsonxml/contactUpdateIsIcannOwnerChange
Processing	synchronous
Response	bool

Parameter	Type	Required	Description
contact	Contact object	req	contact object to check

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
active	Domain is in customer’s account
restorable	Domain was deleted and is in restore grace period
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>

Request	domainsFind
Url	https://secure.hosting.de/api/domain/v1/jsonxml/domainsFind
Processing	synchronous
Response	FindDomainsResult

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	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 name object was created in our system.
DomainLastChangeDate	Date and time the domain name was last modified.
ContactId	Match domain names using this contact
DomainContactAllocation	Match domain names that use `ContactId` for this allocation
ContactHandle	Handle of a contact connected to the domain name
ContactName	Name of a contact connected to the domain name
ContactOrganization	Organization of a contact connected to the domain name

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>

Request	domainCreate
Url	https://secure.hosting.de/api/domain/v1/jsonxml/domainCreate
Processing	asynchronous
Response	Domain 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>

Request	domainUpdate
Url	https://secure.hosting.de/api/domain/v1/jsonxml/domainUpdate
Processing	asynchronous
Response	Domain object

Parameter	Type	Required	Description
domain	Domain object	req	Updated domain data
actingAs	string	opt	see below

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.

Changing the owner contact of a domain in a generic extension (com, net, etc) may result in an owner change under the ICANN rules. If this is the case both new and old contact need to confirm the change via emailed confirm code.

By passing designatedAgent as the actingAs parameter you affirm that the current and the new contact have explicitly opted in to authorize you to approve a Change of Registrant on their behalf. Thus the email confirmation will not be needed.

To check if an update is an owner change under ICANN rules (i.e. is material change and affects domains under icann rules) you can use the domainUpdateIsIcannOwnerChange api function.

Request	domainUpdateIsIcannOwnerChange
Url	https://secure.hosting.de/api/domain/v1/jsonxml/domainUpdateIsIcannOwnerChange
Processing	synchronous
Response	bool

Parameter	Type	Required	Description
domain	Domain object	req	domain data to check

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>

Request	domainInfo
Url	https://secure.hosting.de/api/domain/v1/jsonxml/domainInfo
Processing	synchronous
Response	Domain 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>

Request	domainStatus
Url	https://secure.hosting.de/api/domain/v1/jsonxml/domainStatus
Processing	synchronous
Response	DomainStatusResult 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>

Request	domainDelete
Url	https://secure.hosting.de/api/domain/v1/jsonxml/domainDelete
Processing	asynchronous
Response	none

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>

Request	domainWithdraw
Url	https://secure.hosting.de/api/domain/v1/jsonxml/domainWithdraw
Processing	asynchronous
Response	none

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.

Canceling Domain Deletion

POST https://secure.hosting.de/api/domain/v1/jsonxml/domainDeletionCancel

{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "example.de"
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>example.de</domainName>
</request>

Parameter	Type	Required	Description
domainName	string	req	Name of the domain (Unicode or ASCII format)

In order to cancel a scheduled deletion (or withdrawal) of a doman, you can use the request domainDeletionCancel. It’s only parameter specifies the domain for which the pending deletion is to be cancled.

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>

Request	domainTransfer
Url	https://secure.hosting.de/api/domain/v1/jsonxml/domainTransfer
Processing	asynchronous
Response	Domain 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>

Request	domainTransferOutAck
Url	https://secure.hosting.de/api/domain/v1/jsonxml/domainTransferOutAck
Processing	asynchronous
Response	Domain 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>

Request	domainTransferOutNack
Url	https://secure.hosting.de/api/domain/v1/jsonxml/domainTransferOutNack
Processing	asynchronous
Response	Domain 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>

Request	domainRestore
Url	https://secure.hosting.de/api/domain/v1/jsonxml/domainRestore
Processing	asynchronous
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>

Request	domainCreateAuthInfo2
Url	https://secure.hosting.de/api/domain/v1/jsonxml/domainCreateAuthInfo2
Processing	asynchronous
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
warnings	strnig	out-only	JSON encoded list of warnings 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

Request	jobsFind
Url	https://secure.hosting.de/api/domain/v1/jsonxml/jobsFind
Processing	synchronous
Response	FindJobsResult

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
JobStatus	Status of job
JobSubStatus	Substatus 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.
dnsServerGroupId	string	opt	Only used if you use your own servers.
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] (#the-soa-values-object)	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] (#the-template-values-object)	opt	This property can be used if you want to create the zone with a template.
dnsSecMode	string	opt	See DNSSEC

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] (#the-template-replacements-object)	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
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`, `ALIAS`, `CAA`, `CERT`, `CNAME`, `DNSKEY`, `DS`, `MX`, `NS`, `NSEC`, `NSEC3`, `NSEC3PARAM`, `NULLMX`, `OPENPGPKEY`, `PTR`, `RRSIG`, `SRV`, `SSHFP`, `TLSA`, and `TXT`. 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 minimum 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 0 or greater for those types.
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>

Request	zoneConfigsFind
Url	https://secure.hosting.de/api/dns/v1/jsonxml/zoneConfigsFind
Processing	synchronous
Response	FindZoneConfigsResult

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>
   <field>zoneConfigId</field>
   <value>15010100000010</value>
 </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>

Request	recordsFind
Url	https://secure.hosting.de/api/dns/v1/jsonxml/recordsFind
Processing	synchronous
Response	FindRecordsResult

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>

Request	zonesFind
Url	https://secure.hosting.de/api/dns/v1/jsonxml/zonesFind
Processing	synchronous
Response	FindZonesResult

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,
            "priority": 0
        }
    ]
}

<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>
      <priority>0</priority>
      <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>

Request	zoneCreate
Url	https://secure.hosting.de/api/dns/v1/jsonxml/zoneCreate
Processing	asynchronous
Response	Zone

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
dnsSecOptions	DnsSecOptions	opt	`DnsSecOptions` to be used. Default is `null`.

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.

Read the DNSSEC Section for more information abound DNSSEC.

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": {
        "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": "active",
        "templateValues": null,
        "type": "NATIVE",
        "zoneTransferWhitelist": [
        ]
    },
    "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,
            "priority": 0
        }
    ]
}

<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>
      <priority>0</priority>
      <ttl>86000</ttl>
      <type>MX</type>
    </item>
  </records>
  <useDefaultNamserverSet>false</useDefaultNamserverSet>
  <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>active</status>
    <templateValues null="true" />
    <type>NATIVE</type>
    <zoneTransferWhitelist />
  </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>

Request	zoneRecreate
Url	https://secure.hosting.de/api/dns/v1/jsonxml/zoneRecreate
Processing	asynchronous
Response	Zone

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
dnsSecOptions	DnsSecOptions	opt	`DnsSecOptions` to be used. Default is `null`.

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.

Read the DNSSEC Section for more information abound DNSSEC.

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": {
        "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": "active",
        "templateValues": null,
        "type": "NATIVE",
        "zoneTransferWhitelist": [
        ]
    },
    "recordsToAdd": [
        {
            "name": "www.example.com",
            "type": "AAAA",
            "content": "2001:db8::1",
            "ttl": 86000
        },
        {
            "name": "example.com",
            "type": "MX",
            "content": "newmailserver.example.com",
            "ttl": 86000,
            "priority": 0
        }
    ],
    "recordsToModify": [
        {
            "id":"15010100000010",
            "name": "sub.example.com",
            "type": "AAAA",
            "content": "2001:db8::1",
            "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>
  <recordsToModify>
    <item>
      <id>15010100000010</id>
      <content>2001:db8::1</content>
      <name>sub.example.com</name>
      <ttl>86000</ttl>
      <type>AAAA</type>
    </item>
  </recordsToModify>
  <recordsToDelete>
    <item>
      <content>smtp.example.com</content>
      <name>example.com</name>
      <priority>0</priority>
      <type>MX</type>
    </item>
  </recordsToDelete>
  <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>active</status>
    <templateValues null="true" />
    <type>NATIVE</type>
    <zoneTransferWhitelist />
  </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"
            },
            {
                "content": "2001:db8::1",
                "id": "15010100000024",
                "lastChangeDate": "2015-09-02",
                "name": "sub.example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 86000,
                "type": "AAAA",
                "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>
      <item>
        <content>2001:db8::1</content>
        <id>15010100000024</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>sub.example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>86000</ttl>
        <type>AAAA</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>

Request	zoneUpdate
Url	https://secure.hosting.de/api/dns/v1/jsonxml/zoneUpdate
Processing	asynchronous
Response	Zone

Parameter	Type	Required	Description
zoneConfig	zoneConfig object	req	zoneConfig to be updated
recordsToAdd	list<Record>	req	Records to be added
recordsToModify	list<Record>	req	Records to be modified
recordsToDelete	list<Record>	req	Records to be deleted
dnsSecOptions	DnsSecOptions	opt	`DnsSecOptions` to be used. Default is `null`.

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

Existing records that are not contained in either list will not be changed.

Read the DNSSEC Section for more information abound DNSSEC.

Updating Records in a Zone

POST https://secure.hosting.de/api/dns/v1/jsonxml/recordsUpdate

{
    "authToken": "$$YOUR API KEY$$",
    "zoneName": "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,
            "priority": 0
        }
    ],
    "recordsToModify": [
        {
            "id":"15010100000010",
            "name": "sub.example.com",
            "type": "AAAA",
            "content": "2001:db8::1",
            "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>
      <priority>0</priority>
      <ttl>86000</ttl>
      <type>MX</type>
    </item>
  </recordsToAdd>
  <recordsToModify>
    <item>
      <id>15010100000010</id>
      <content>2001:db8::1</content>
      <name>sub.example.com</name>
      <ttl>86000</ttl>
      <type>AAAA</type>
    </item>
  </recordsToModify>
  <recordsToDelete>
    <item>
      <content>smtp.example.com</content>
      <name>example.com</name>
      <type>MX</type>
    </item>
  </recordsToDelete>
  <zoneName>example.com</zoneName>
</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"
            },
            {
                "content": "2001:db8::1",
                "id": "15010100000024",
                "lastChangeDate": "2015-09-02",
                "name": "sub.example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 86000,
                "type": "AAAA",
                "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>
      <item>
        <content>2001:db8::1</content>
        <id>15010100000024</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>sub.example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>86000</ttl>
        <type>AAAA</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>

Request	recordsUpdate
Url	https://secure.hosting.de/api/dns/v1/jsonxml/recordsUpdate
Processing	asynchronous
Response	Zone

Parameter	Type	Required	Description
zoneConfigId	string	opt	zoneConfig to be updated
zoneName	string	opt	zoneConfig to be updated
recordsToAdd	list<Record>	req	Records to be added
recordsToModify	list<Record>	req	Records to be modified
recordsToDelete	list<Record>	req	Records to be deleted

You can use recordsUpdate to remove records, to add new records or to modify existing records. All records in recordsToAdd will be added to the zone, while all records in recordsToDelete will be deleted. All records in recordsToModify will be modified. If you insert a record that does not exist into recordsToDelete or recordsToModify, an error will occur.

Existing records that are not contained in either list will not be changed.

Either the ID or the name has to be provided. If both are set, the ID will be used to identify the zone.

Updating a Record Record Set in a Zone

POST https://secure.hosting.de/api/dns/v1/jsonxml/resourceRecordSetUpdate

{
    "authToken": "$$YOUR API KEY$$",
    "hostname": "www.example.com",
    "recordType": "A",
    "rrSetContents": [
        {
            "content": "127.0.0.1",
            "priority": 0
        }
    ],
    "removeAllRecords": "false"
}

<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <hostname>www.example.com</hostname>
  <recordType>A</recordType>
  <rrSetContents>
    <item>
      <content>127.0.0.1</content>
      <priority>0</priority>
    </item>
  </rrSetContents>
  <removeAllRecords>false</removeAllRecords>
</request>

Request	resourceRecordSetUpdate
Url	https://secure.hosting.de/api/dns/v1/jsonxml/resourceRecordSetUpdate
Processing	asynchronous
Response	empty

Parameter	Type	Required	Description
hostname	string	req	Hostname to change
recordType	string	req	Type of records to changes
rrSetContents	list<RrSetContent>	req	New content of the record set
removeAllRecords	bool	req	Remove records of other types

This request replaces all existing records of a given type with records using the supplied values.

If removeAllRecords is set to true, all other types of records are removed from the given hostname.

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>
    ...

Request	zoneDelete
Url	https://secure.hosting.de/api/dns/v1/jsonxml/zoneDelete
Processing	asynchronous
Response	empty

Parameter	Type	Required	Description
zoneConfigId	string	opt	ID of `ZoneConfig` to be deleted
zoneName	string	opt	Name of `ZoneConfig` to be deleted

The zone will be marked as restorable and removed from the nameservers. After passing the zone’s restorableUntil point the complete zone, ie. the zoneConfig and all records, will be deleted permanently. Either the ID or the name has to be provided. If both are set, an error will be returned.

Restoring Zones

POST https://secure.hosting.de/api/dns/v1/jsonxml/zoneRestore

{
    "authToken": "$$YOUR API KEY$$",
    "zoneConfigId": "15010100000010"
}

<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <zoneConfigId>15010100000010</zoneConfigId>
</request>

Response

{
    ...
    "status": "pending",
    ...
}

...
    <status>pending</status>
    ...

Request	zoneRestore
Url	https://secure.hosting.de/api/dns/v1/jsonxml/zoneRestore
Processing	asynchronous
Response	Zone

Parameter	Type	Required	Description
zoneConfigId	string	opt	ID of `ZoneConfig` to be restored
zoneName	string	opt	Name of `ZoneConfig` to be restored

The zone becomes active again, i.e. is no longer in restorable state, and is send to the nameservers. Either the ID or the name has to be provided. If both are set, an error will be returned.

Purging Zones

POST https://secure.hosting.de/api/dns/v1/jsonxml/zonePurgeRestorable

{
    "authToken": "$$YOUR API KEY$$",
    "zoneConfigId": "15010100000010"
}

<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <zoneConfigId>15010100000010</zoneConfigId>
</request>

Response

{
    ...
    "status": "pending",
    ...
}

...
    <status>pending</status>
    ...

Request	zonePurgeRestorable
Url	https://secure.hosting.de/api/dns/v1/jsonxml/zonePurgeRestorable
Processing	asynchronous
Response	empty

Parameter	Type	Required	Description
zoneConfigId	string	opt	ID of `ZoneConfig` to be purged
zoneName	string	opt	Name of `ZoneConfig` to be purged

Only works on zones that are already in status restorable. The complete zone, ie. the zoneConfig and all records, will be deleted permanently. 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>
    ...

Request	changeContent
Url	https://secure.hosting.de/api/dns/v1/jsonxml/changeContent
Processing	asynchronous
Response	empty

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/zonesUntieFromTemplate

{
    "authToken": "$$YOUR API KEY$$",
    "zoneConfigIds": [
        "15010100000010"
    ]
}

<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <zoneConfigIds>
    <item>15010100000010</item>
  </zoneConfigIds>
</request>

Response

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

...
    <status>success</status>
    ...

Request	zonesUntieFromTemplate
Url	https://secure.hosting.de/api/dns/v1/jsonxml/zonesUntieFromTemplate
Processing	synchronous
Response	empty

Parameter	Type	Required	Description
zoneConfigIds	list of strings	opt	IDs of `ZoneConfigs` to be detached
zoneConfigNames	list of strings	opt	Names of `ZoneConfigs` to be detached

This will untie zones from the template it was created from. Afterwards, changes to the template will not affect the zones 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/zonesTieToTemplate

{
    "authToken": "$$YOUR API KEY$$",
    "zoneConfigIds": [
        "15010100000010"
    ],
    "templateId": "15010100000011",
    "templateReplacements": {
        "ipv4Replacement": "192.0.2.1",
        "ipv6Replacement": "2001:0db8:0000:0042:0000:8a2e:0370:7334",
        "mailIpv4Replacement": "192.0.2.2",
        "mailIpv6Replacement": "2001:0db8:0000:0042:0000:8a2e:0370:7334"
    }
}

<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <zoneConfigIds>
    <item>15010100000010</item>
  </zoneConfigIds>
  <templateId>15010100000011</templateId>
  <templateReplacements>
    <ipv4Replacement>192.0.2.1</ipv4Replacement>
    <ipv6Replacement>2001:0db8:0000:0042:0000:8a2e:0370:7334</ipv6Replacement>
    <mailIpv4Replacement>192.0.2.2</mailIpv4Replacement>
    <mailIpv6Replacement>2001:0db8:0000:0042:0000:8a2e:0370:7334</mailIpv6Replacement>
  </templateReplacements>
</request>

Response

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

...
    <status>success</status>
    ...

Request	zonesTieToTemplate
Url	https://secure.hosting.de/api/dns/v1/jsonxml/zonesTieToTemplate
Processing	asynchronous
Response	empty

Parameter	Type	Required	Description
zoneConfigIds	list of strings	opt	IDs of `ZoneConfigs` to be attached
zoneConfigNames	list of strings	opt	Names of `ZoneConfigs` to be attached
templateId	string	req	ID of the `Template` to attach the `ZoneConfigs` to
templateReplacements	`TemplateReplacements`	opt	`TemplateReplacements` to be used

This will tie zones to a template. Afterwards all changes to the template will affect the zones. 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.

DNSSEC

DNSSEC is used to secure DNS Responses. It is specified in the dnsSecMode parameter within a ZoneConfig. You have three options:

Name	Description
off	DNSSEC will not be used for this zone.
presigned	You sign the zone by yourself. In that case, you have to set `dnsSecOptions` as parameter in your `zoneCreate`, `zoneRecreate` or `zoneUpdate` Requests to `null`. All DS and RRSET Records must be delivered by your request.
automatic	The zone will be signed by our signing servers. No DNSSEC Records have to be specified by you. You can optional define a `dnsSecOptions` Object as parameter in your `zoneCreate`, `zoneRecreate` or `zoneUpdate` Requests to override the defaults. In the easiest case, just submit `null` as `dnsSecOptions`.

There are some objects defined for DNSSEC.

The DnsSecOptions Object

A dnsSecOptions Object can be used to overwrite the defaults on creating or updating zones when using automatic signing mode. It contains the other DNSSEC objects, see below.

DnsSecOptions Object

Property	Type	Required	Description
keys	list<DnsSecKey>	opt	List of `DnsSecKey` Objects. Default is empty.
algorithms	list<string>	opt	Algorithm, see below.
nsecMode	string	opt	NSEC Mode, see below.
publishKsk	bool	opt	Publish KSK to the registry. Only available if the domain name is registered with us. Default is false.

Manual Key list

If you want to submit own keys, just send then within the keys list. If your list is an empty array, our signing server will generate the keys automatically.

Supported algorithms

At the moment, we only support RSASHA256 as algorithm. This is also the default.

Supported NSEC Modes

We support nsec and nsec3 as NSEC Modes. Default is nsec3.

Publishing KSK to the registry

If your domain name is registered with us, the KSK will be published to the registry if you set publishKsk to true.

The DnsSecKey Object

DnsSecKey Object

With the DnsSecKey object one can submit manual keys for the zone signing.

Property	Type	Required	Description
keyData	DnsSecKeyData	req	`DnsSecKeyData` to be used.
dsData	list<DnsSecDsData>	out-only	List of `DnsSecDsData` Objects.
keyTag	int	out-only	Tag of the key
expiresOn	datetime	out-only	Expiry date of the key
comments	string	req	Comments

The DnsSecKeyData Object

DnsSecKeyData Object

With the DnsSecKeyData object one can set the used keys for the zone signing. If nothing is specified, the keys will be automatically generated by our signing server.

Property	Type	Required	Description
flags	int	req	DNS Key Flag
protocol	int	req	DNS KEY Resource Record Protocol
algorithm	int	req	Algorithm
publicKey	string	req	Public Key

Supported flags

Flag	Description
256	for zone signing keys
257	for key signing keys

Supported protocol

At the moment, we only support 3 (DNSSEC) as protocol. See also here.

Supported algorithms

At the moment, we only support 1 (SHA-1) as algorithm. See also here.

The DnsSecDsData Object

DnsSecDsData Object

The DnsSecDsData object will only be used as output within a DnsSecKey Object. It contains the data you have to send to the registry.

Property	Type	Required	Description
algorithm	int	req	Algorithm
digestType	int	req	Digest Type
digest	string	req	Digest

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>

Request	nameserverSetsFind
Url	https://secure.hosting.de/api/dns/v1/jsonxml/nameserverSetsFind
Processing	synchronous
Response	FindNameserverSetsResult

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>

Request	nameserverSetCreate
Url	https://secure.hosting.de/api/dns/v1/jsonxml/nameserverSetCreate
Processing	synchronous
Response	NameserverSet

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>

Request	nameserverSetUpdate
Url	https://secure.hosting.de/api/dns/v1/jsonxml/nameserverSetUpdate
Processing	synchronous
Response	NameserverSet

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>
    ...

Request	nameserverSetDelete
Url	https://secure.hosting.de/api/dns/v1/jsonxml/nameserverSetDelete
Processing	synchronous
Response	empty

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>

Request	nameserverSetGetDefault
Url	https://secure.hosting.de/api/dns/v1/jsonxml/nameserverSetGetDefault
Processing	synchronous
Response	NameserverSet

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:

Adding record templates to a template will cause corresponding records to be added to the zone.
Changing existing record templates will cause the same changes to the records that were created from the record templates.
Deleting a record template will also delete all records that were created by it. This means that recreating a template also deletes ALL records created from the record templates.

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:

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

##DOMAIN## 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.##DOMAIN##.

##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.

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

Property	Type	Required
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 `##DOMAIN##` placeholder which will be replaced with zone name of zone created from template. Example: `mail.##DOMAIN##` 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 0 or greater for those types.

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>

Request	templatesFind
Url	https://secure.hosting.de/api/dns/v1/jsonxml/templatesFind
Processing	synchronous
Response	FindTemplatesResult

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>

Request	recordTemplatesFind
Url	https://secure.hosting.de/api/dns/v1/jsonxml/recordTemplatesFind
Processing	synchronous
Response	FindRecordTemplatesResult

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>

Request	templateCreate
Url	https://secure.hosting.de/api/dns/v1/jsonxml/templateCreate
Processing	synchronous
Response	Template

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>

Request	templateRecreate
Url	https://secure.hosting.de/api/dns/v1/jsonxml/templateRecreate
Processing	asynchronous
Response	Template

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>

Request	templateUpdate
Url	https://secure.hosting.de/api/dns/v1/jsonxml/templateUpdate
Processing	asynchronous
Response	Template

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",
    ...
}

Request	templateDelete
Url	https://secure.hosting.de/api/dns/v1/jsonxml/templateDelete
Processing	synchronous
Response	empty

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.

Please keep in mind, that the SSL API is released as a beta and might have code breaking changes in further releases.

Typical Workflow

Order an SSL certificate by calling orderCreate. Please keep in mind, that this function will be replaced by a new function certificateCreate in a later release.
Domain validated orders allow you to receive certificates in a short period of time. You can choose between four validation methods:

Name	Comment
auto	If your DNS Zone or webspace is hosted with us, our system can validate your domain name automatically.
validateViaDns	Create a DNS Record with the name of `validationKey` and the content of `validationValue`
validateViaEmail	You will receive an email and have to click a link.
validateViaFile	Create a file accessible via HTTP under the domain name with the name `validationKey`, content of the file is `validationValue`

Otherwise (organization validated orders or email validation), proceed with the SSL supplier’s validation process.
If you chose validateViaDns or validateViaFile you should get Certificate Details by calling certificateDetailsGet. If validationKey and validationValue are filled, you can continue to create DNS records or the file on the webspace. You might call certificateDetailsGet more than once until the fields are filled.
Get the certificate by calling certificateGetCertificate. If the orderStatus is completed, the certifcate was succesfully created an you can use it.

Available SSL Products

Supplier	Product	Periods (months)	Additional Domain Names	ProductCode	Validation Type
GeoTrust	RapidSSL	12	-	ssl-geotrust-rapidssl-12m	Domain
GeoTrust	RapidSSL Wildcard	12	-	ssl-geotrust-rapidssl-wildcard-12m	Domain
GeoTrust	TrueBizId	12	100	ssl-geotrust-truebizid-12m	Organization
GeoTrust	TrueBizId Wildcard	12	-	ssl-geotrust-truebizid-wildcard-12m	Organization
GeoTrust	TrueBizIdEv	12	100	ssl-geotrust-truebizidev-12m	Organization

The Certificate Order Object

The CertificateOrder object will be used as a base class when creating orders.

{
    "csr": "-----BEGIN CERTIFICATE REQUEST-----
...
-----END CERTIFICATE REQUEST-----",
    "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"
    },
    "productCode": "ssl-geotrust-rapidssl-12m",		
    "validationType": "validateViaEmail"
}

<order>
	<csr>-----BEGIN CERTIFICATE REQUEST-----
...
-----END CERTIFICATE REQUEST-----</csr>
	<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>
	<productCode>ssl-geotrust-rapidssl-12m</productCode>
	<validationType>validateViaEmail</validationType>
</order>

Certificate Order Object

Property	Type	Required	Description
csr	string	req	Certificate signing request
adminContact	Contact	opt	Admin contact for order (cf. the contact object)
techContact	Contact	opt	Technical contact for order (cf. the contact object)
productCode	string	req	Contains supplier’s brand and certificate’s product name
additionalDomainNames	list <string>	opt	Additional domains secured by the certificate
autoRenew	bool	req	If true, certificate will get auto renewed on renewDate
validationType	string	req	Method of the validation (auto, validateViaDns, validateViaEmail, validateViaFile)

The CertificateOrder object has to be extended depending on the chosen product:

{
    "type": "DomainValidatedCertificateOrder",
    ...
    "approverEmailAddress": "admin@example.com"
}

<order>
	<type>DomainValidatedCertificateOrder</type>
	...
	<approverEmailAddress>admin@example.com</approverEmailAddress>
</order>

Domain Validated Certificate Order Object

Property	Type	Required	Description
type	string	req	always `DomainValidatedCertificateOrder` for domain validated orders
approverEmailAddress	string	req	Approver email address

{
    "type": "OrganizationValidatedCertificateOrder",
    ...
    "organization": {
        "organizationName": "Musterfirma",
        "organizationUnit": "IT Service",
        "phoneNumber": "+49635453433",
        "faxNumber": "+49635453433",
        "addressLine1": "Musterstr. 1",
        "city": "Musterstadt",
        "region": "Musterland",
        "postalCode": "12345",
        "country": "DE"
    }
}

<order>
    <type>OrganizationValidatedCertificateOrder</type>
    ...
    <organization>
        <organizationName>Musterfirma</organizationName>
        <organizationUnit>IT Service</organizationUnit>
        <phoneNumber>+49635453433</phoneNumber>
        <faxNumber>+49635453433</faxNumber>
        <addressLine1>Musterstr. 1</addressLine1>
        <addressLine2></addressLine2>
        <city>Musterstadt</city>
        <region>Musterland</region>
        <postalCode>12345</postalCode>
        <country>DE</country>
    </organization>
</order>

Organization Validated Order Object

Property	Type	Required	Description
type	string	req	always `OrganizationValidatedCertificateOrder` for organization validated orders
organization	Organization	req	Organization Object (cf. the Organization Object)

{
    "type": "EmailCertificateOrder",
    ...
    "emailAddresses": [
        "smime@example.com"
    ]
}

<order>
	<type>EmailCertificateOrder</type>
	...
	<emailAddresses>
        <item>smime@example.com</item>
    </emailAddresses>
</order>

Email Certificate Order Object

The EmailCertificateOrder is used for ordering SMIME Certificates.

Property	Type	Required	Description
type	string	req	always `EmailCertificateOrder` for email (SMIME) orders
emailAddresses	list <string>	req	Email Address as list which the SMIME Certificate should contain. At this time this must be exaclty one element.

The OrderConfirmation Object

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

{
    "certificateId": "180102xxxxxxxxx",
    "commonName": "example.com",
    "jobId": "180102xxxxxxxxxx"
}

<orderconfirmation>
	<certiciateId>180102xxxxxxxxxx</certiciateId>
	<commonName>example.com</commonName>
	<jobId>180102xxxxxxxxxx</jobId>
</orderconfirmation>

Order Confirmation Object

Property	Type	Required	Description
certificateId	string	req	Certificate ID
jobId	string	req	Job ID
commonName	string	req	Common Name of the certificate

The Contact Object

You use the Contact object when creating orders.

{
    "title": "Mr.",
    "firstName": "George",
    "lastName": "Orwell",
    "phoneNumber": "+49635453433",
    "emailAddress": "admin@example.com"
}

<contact>
    <emailAddress>admin@example.com</emailAddress>
    <firstName>George</firstName>
    <lastName>Orwell</lastName>
    <phoneNumber>++149635453433</phoneNumber>
    <title>Mr.</title>
</contact>

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 Organization object when creating orders for organization/extended validation certificates.

{
    "organizationName": "Musterfirma",
    "organizationUnit": "IT Service",
    "phoneNumber": "+49635453433",
    "faxNumber": "+49635453433",
    "addressLine1": "Musterstr. 1",
    "addressLine2": "",
    "city": "Musterstadt",
    "region": "Musterland",
    "postalCode": "12345",
    "country": "DE"
}

<organization>
    <organizationName>Musterfirma</organizationName>
    <organizationUnit>IT Service</organizationUnit>
    <phoneNumber>+49635453433</phoneNumber>
    <faxNumber>+49635453433</faxNumber>
    <addressLine1>Musterstr. 1</addressLine1>
    <addressLine2></addressLine2>
    <city>Musterstadt</city>
    <region>Musterland</region>
    <postalCode>12345</postalCode>
    <country>DE</country>
</organization>

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.

{
    "domainName": "example.com",
    "country": "US",
    "emailAddress": "admin@example.com",
    "locality": "Dreamtown",
    "organization": "Example Inc.",
    "organizationUnit": "IT Department",
    "state": "California"
}

<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>

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
additionalDomainNames	list < string >	opt	Additional domains secured by the certificate
keyType	string	req
keyLength	int	req
eccType	string	req

Decode CSR Result Object

The DecodeCsrResult object contains information about products and the decoded CSR.

The Decode CSR Result Object

Property	Type	Required	Description
csr	CSR	req	CSR Object parsed from csr request (cf. the CSR object)
errors	list <ErrorOrWarning>	req	Errors
warnings	list <ErrorOrWarning>	req	Warnings
productCodes	list <string>	req	possible ProductCodes matching the CSR

The Certificate Details Object

The CertificateDetails object is returned by certificatesDetailsGet.

{
    "addDate": "2020-11-24T14:07:05Z",
    "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"
    },
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----",
    "approverEmailAddress": "admin@example.com",
    "id": "65453135153153",
    "lastChangeDate": "2020-11-24T14:09:42Z",
    "type": "DomainValidatedCertificateDetails",
    "validationKey": "",
    "validationType": "validateViaEmail",
    "validationValue": "admin@example.com"
}

<certificatedetails>
    <addDate>2020-11-24T14:07:05Z</addDate>
    <adminContact>
       <emailAddress>admin@example.com</emailAddress>
       <firstName>George</firstName>
       <lastName>Orwell</lastName>
       <phoneNumber>++149635453433</phoneNumber>
       <title>Mr.</title>
    </adminContact>
    <approverEmailAddress>admin@example.com</approverEmailAddress>
    <csr>-----BEGIN CERTIFICATE REQUEST-----
...
-----END CERTIFICATE REQUEST-----</csr>
    <id>65453135153153</id>
    <lastChangeDate>2020-11-24T14:09:42Z</lastChangeDate>
    <techContact>
        <emailAddress>tech@example.com</emailAddress>
        <firstName>Robert</firstName>
        <lastName>Stevenson</lastName>
        <phoneNumber>++1333544451</phoneNumber>
        <title>Mr.</title>
    </techContact>
    <type>DomainValidatedCertificateDetails</type>
    <validationKey />
    <validationType>validateViaEmail</validationType>
    <validationValue>admin@example.com</validationValue>
</certificatedetails>

Certificate Details Object

Every Validation Type contains the following information:

Property	Type	Required	Description
id	string	req	Certificate ID
csr	string	req	Certificate signing request
adminContact	Contact	req	Admin contact for order (cf. the contact object)
techContact	Contact	req	Technical contact for order (cf. the contact object)

Domain Validated Certificate Details

If you ordered a domain validated certificate, the CertificateDetails object contains additionally the following fields:

Property	Type	Required	Description
validationType	string	req	Validation type
validationKey	string	opt	Validation key
validationValue	string	opt	Validation value
approverEmailAddress	string	opt	Emailaddress of the approver

Organization Validated Certificate Details

If you ordered an organization validated certificate, the CertificateDetails object contains additionally the following fields:

Property	Type	Required	Description
organization	Organization	req	Organization object, see the organization object

The Certificate Object

The Certificate Object is returned by certificatesFind or certificateGetCertificate.

{
    "id": "65453135153153",
    "accountId": "98687313548",
    "status": "active",
    "orderStatus": "complete",
    "startDate": "2014-12-17T02:23:46",
    "endDate": "2015-01-20T04:33:40",            
    "commonName": "example.com",
    "serialNumber": "581A3F",
    "serverCert": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",

    "intermediateCert": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",

    "rootCert": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",

    "externalOrderId": "1234567890",
    "validitySpanMonth": 1,
    "validationLevel": "XXXX",
    "brand": "DigiCert",
    "productCode": "GeoTrust FreeSSL",
    "additionalDomainNames": [ ]
}

<certificate>
    <id>65453135153153</id>
    <accountId>98687313548</accountId>
    <status>active</status>
    <startDate>2014-12-17T02:23:46</startDate>
    <endDate>2015-01-20T04:33:40</endDate>
    <commonName>example.com</commonName>
    <serialNumber>581A3F</serialNumber>
    <serverCert>-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"</serverCert>
    <intermediateCert>-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----</intermediateCert>
    <rootCert>-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----</rootCert>
    <externalOrderId>1234567890"</externalOrderId>
    <validitySpanMonth>1</validitySpanMonth>
    <validationLevel>XXXX"</validationLevel>
    <brand>DigiCert</brand>
    <productCode>GeoTrust FreeSSL</productCode>
    <additionalDomainNames></additionalDomainNames>
</certificate>

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
orderStatus	string	req	Current order status
startDate	datetime	req	Start date of certificate’s validity period
endDate	datetime	req	End date of certificate’s validity period
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
externalOrderId	string	opt	Order ID from supplier
validitySpanMonth	int	opt	Validity period
validationLevel	string	opt	Type of the validation (dv/ev/ov)
productCode	string	req	Contains supplier’s brand and certificate’s product name
brand	string	opt	Name of the certificates brand
product	string	opt	Name of the certificates product
additionalDomainNames	list <string	opt	Additional domains secured by the certificate
cancelableUntil	datetime	opt	Date until the certificate can be cancelled for renew
renewDate	datetime	opt	Date for the next renewal of the certificate
autoRenew	bool	opt	If true, certificate will get auto renewed on renewDate

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.

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

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>

Request	certificatesFind
Url	https://secure.hosting.de/api/ssl/v1/jsonxml/certificatesFind
Processing	synchronous
Response	FindCertificatesResult

The function certificatesFind lets you list existing SSL certificates. The usual sorting and filtering options apply. The response will contain a list of Certificate objects.

The following fields are available for filtering and sorting:

Field	Description
AccountId	ID of account that ordered certificate
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>

Request	domainApproverList
Url	https://secure.hosting.de/api/ssl/v1/jsonxml/domainApproverList
Processing	synchronous
Response	List of Strings

Parameter	Type	Required	Description
domainName	String	req	Domain name

Decoding CSR

The function csrDecode decodes a given CSR string and returns a Decode CSR Result 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"
		},
		"errors": [],
		"warnings": [],
		"productCodes": []
	},
    ...
}

<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>
		<errors></errors>
		<warnings></warnings>
		<productCodes></productCodes>
	</response>
	...
</response>

Request	csrDecode
Url	https://secure.hosting.de/api/ssl/v1/jsonxml/csrDecode
Processing	synchronous
Response	Decode CSR Result

Parameter	Type	Required	Description
csr	String	req	Certificate signing request
productCode	String	opt	If set, check if given productCode can be used with the CSR

Checking Auto Validation Capability

The function checkAutoValidationCapable can be used to check if a certificate order can be validated automatically.

POST https://secure.hosting.de/api/ssl/v1/jsonxml/checkAutoValidationCapable

{
    "authToken": "$$YOUR API KEY$$",
    "names": [
        "example1.com",
        "www.example1.com"
    ],
    "productCode": "ssl-geotrust-rapidssl-12m"
}

<request>
   <authToken>$$YOUR API KEY$$</authToken>
   <names>
      <element>example1.com</element>
      <element>www.example1.com</element>
   </names>
   <productCode>ssl-geotrust-rapidssl-12m</productCode>
</request>

Response

The response just contains Errors and Warnings. If no errors or warnings are returned, you can use auto as value for the validationType parameter of an order object.

{
    "errors": [],
    ...
}

<response>
  <errors />
  ...
</response>

Request	checkAutoValidationCapable
Url	https://secure.hosting.de/api/ssl/v1/jsonxml/checkAutoValidationCapable
Processing	synchronous
Response	Warnings and Errors

Parameter	Type	Required	Description
names	list	req	all Domain names for which the certificate should be issued
productCode	String	opt	If set, check if given productCode can be used for auto validation, only DV certificates can be auto validated

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": "DomainValidatedCertificateOrder",
		"csr": "-----BEGIN CERTIFICATE REQUEST-----
...
-----END CERTIFICATE REQUEST-----",
		"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"
		},
		"productCode": "ssl-geotrust-rapidssl-12m",		
		"validationType": "validateViaEmail",
		"approverEmailAddress": "admin@example.com"
	},
	...
}

<request>
	<authToken>$$YOUR API KEY$$</authToken>
	<order>
		<type>DomainValidatedCertificateOrder</type>
		<csr>-----BEGIN CERTIFICATE REQUEST-----
...
-----END CERTIFICATE REQUEST-----</csr>
		<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>
		<productCode>ssl-geotrust-rapidssl-12m</productCode>
		<validationType>validateViaEmail</validationType>
		<approverEmailAddress>admin@example.com</approverEmailAddress>
	</order>
	...
</request>

Response

{
    "response": {
        "certificateId": "180102xxxxxxxxx",
        "commonName": "example.com",
        "jobId": "180102xxxxxxxxxx"
    },
    ...
}

<response>
	<response>
		<certiciateId>180102xxxxxxxxxx</certiciateId>
		<commonName>example.com</commonName>
		<jobId>180102xxxxxxxxxx</jobId>
	</response>
	...
</response>

Request	orderCreate
Url	https://secure.hosting.de/api/ssl/v1/jsonxml/orderCreate
Processing	asynchronous
Response	OrderConfirmation

Parameter	Type	Required	Description
order	Certificate Order object	req	Order object

For the validation types validateViaDns or validationViaFile you have to call the CertifcateGetDetails Method in order to get the validation details after ordering the certificate.

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

Ordering SMIME Certificates

If you want to order SMIME certificates for email addresses, you have to use the orderCreate function with the type EmailCertificateOrder. The commonName of your CSR must contain the domain name, not the email address itself. The email address has to be given in the parameter emailAddresses. More information can be found in the description of the Certificate Order Object.

Canceling Orders

With the orderCancel function you can cancel an existing order. This operation is possible before an order is completed.

POST https://secure.hosting.de/api/ssl/v1/jsonxml/orderCancel

{
    "authToken": "$$YOUR API KEY$$",
    "certificateId": "1351212445512",
    ...
}

<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <certificateId>1351212445512</certificateId>
    ...
</request>

Response

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

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

Request	orderCancel
Url	https://secure.hosting.de/api/ssl/v1/jsonxml/orderCancel
Processing	asynchronous
Response	empty

Parameter	Type	Required	Description
certificateId	String	req	ID of certificate

Getting Certificate Details

The function certificateDetailsGet returns the certificate details which contain all information from the order and for validation.

POST https://secure.hosting.de/api/ssl/v1/jsonxml/certificateDetailsGet

{
    "authToken": "$$YOUR API KEY$$",
	"certificateId": "65453135153153",
    ...
}

<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <certificateId>65453135153153</certificateId>
	...
</request>

Response

{
    "response": {
        "addDate": "2020-11-24T14:07:05Z",
        "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"
        },
        "csr": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----",
		"approverEmailAddress": "admin@example.com",
        "id": "65453135153153",
        "lastChangeDate": "2020-11-24T14:09:42Z",
        "type": "DomainValidatedCertificateDetails",
        "validationKey": "",
        "validationType": "validateViaEmail",
        "validationValue": "admin@example.com"
    }
}

<response>
    <response>
      <addDate>2020-11-24T14:07:05Z</addDate>
      <adminContact>
         <emailAddress>admin@example.com</emailAddress>
         <firstName>George</firstName>
         <lastName>Orwell</lastName>
         <phoneNumber>++149635453433</phoneNumber>
         <title>Mr.</title>
      </adminContact>
      <approverEmailAddress>admin@example.com</approverEmailAddress>
      <csr>-----BEGIN CERTIFICATE REQUEST-----
...
-----END CERTIFICATE REQUEST-----</csr>
      <id>65453135153153</id>
      <lastChangeDate>2020-11-24T14:09:42Z</lastChangeDate>
      <techContact>
         <emailAddress>tech@example.com</emailAddress>
         <firstName>Robert</firstName>
         <lastName>Stevenson</lastName>
         <phoneNumber>++1333544451</phoneNumber>
         <title>Mr.</title>
      </techContact>
      <type>DomainValidatedCertificateDetails</type>
      <validationKey />
      <validationType>validateViaEmail</validationType>
      <validationValue>admin@example.com</validationValue>
   </response>
</response>

Request	certificateDetailsGet
Url	https://secure.hosting.de/api/ssl/v1/jsonxml/certificateDetailsGet
Processing	synchronous
Response	CertificateDetails

Parameter	Type	Required	Description
certificateId	String	req	ID of certificate

For the validation type validateViaDns, the response’s validationKey will contain the name of a TXT 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.

Getting one Certificate

The function certificateGet returns exaclty one certificate object.

POST https://secure.hosting.de/api/ssl/v1/jsonxml/certificateGet

{
    "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",
            "orderStatus": "complete",
            "startDate": "2014-12-17T02:23:46",
            "endDate": "2015-01-20T04:33:40",            
            "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-----",

            "externalOrderId": "1234567890",
            "validitySpanMonth": 1,
            "validationLevel": "XXXX",
            "brand": "DigiCert",
            "productCode": "GeoTrust FreeSSL",
            "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>
			<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>
            <externalOrderId>1234567890"</externalOrderId>
            <validitySpanMonth>1</validitySpanMonth>
            <validationLevel>XXXX"</validationLevel>
            <brand>DigiCert</brand>
            <productCode>GeoTrust FreeSSL</productCode>
			<additionalDomainNames>
			</additionalDomainNames>
		</certificate>
	</response>
	...
</response>

Request	certificateGet
Url	https://secure.hosting.de/api/ssl/v1/jsonxml/certificateGet
Processing	synchronous
Response	Certificate

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$$",
    "certificateId": "1351212445512",
    ...
}

<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <certificateId>1351212445512</certificateId>	
    ...
</request>

Response

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

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

Request	orderResendApproverEmail
Url	https://secure.hosting.de/api/ssl/v1/jsonxml/orderResendApproverEmail
Processing	synchronous
Response	empty

Parameter	Type	Required	Description
certificateId	String	req	ID of certificate

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>

Request	certificateRevoke
Url	https://secure.hosting.de/api/ssl/v1/jsonxml/certificateRevoke
Processing	synchronous
Response	empty

Parameter	Type	Required	Description
certificateId	String	req	Id of certificate

Reissuing a Certificate

You can reissue an existing certificate without costs for at least five times. This can be needed if you lost your key for the certificate.

POST https://secure.hosting.de/api/ssl/v1/jsonxml/certificateReissue

{
    "authToken": "$$YOUR API KEY$$",
    "certificateId": "981212445512",
    "csr": "-----BEGIN CERTIFICATE REQUEST-----
    KFICqjCSAZsCAQAwATE5MAkGA1UEBhMCREUxDD3KfgNVBAgTA25ydzEPhA0GA1UE
    ...
    WH+ekY0oKtFkuzTXdtI=
    -----END CERTIFICATE REQUEST-----"
}

<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <certificateId>981212445512</certificateId>
    <csr>-----BEGIN CERTIFICATE REQUEST-----
KFICqjCSAZsCAQAwATE5MAkGA1UEBhMCREUxDD3KfgNVBAgTA25ydzEPhA0GA1UE
...
WH+ekY0oKtFkuzTXdtI=
-----END CERTIFICATE REQUEST-----</csr>
</request>

Response

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

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

Request	certificateReissue
Url	https://secure.hosting.de/api/ssl/v1/jsonxml/certificateReissue
Processing	asynchronous
Response	empty

Parameter	Type	Required	Description
certificateId	String	req	ID of certificate
csr	String	opt	new CSR for the 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 Virtual Machine object.

The VirtualMachine Object

VirtualMachine Object

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.
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.
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/virtualMachinesFind

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "virtualMachineName",
        "value": "test vm"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "virtualMachineName",
        "order": "asc"
    }
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <field>virtualMachineName</field>
  <value>test vm</value>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>virtualMachineName</field>
  <order>asc</order>
 </sort>
</request>

Response

{
    ...
    "response": {
        "data": [
            // vm objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindVirtualMachinesResult"
    },
    ...
}

<response>
 <response>
  <data>
   ...
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindVirtualMachinesResult</type>
 </response>
 ...
</response>

Request	virtualMachinesFind
Url	https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachinesFind
Processing	synchronous
Response	FindVirtualMachinesResult

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

The following fields are available for filtering and sorting:

Field	Description
AccountId	ID of account managing the virtual machine
VirtualMachineId	ID of virtual machine
VirtualMachineName	Name of virtual machine
VirtualMachineDescription	Description of virtual machine
VirtualMachineProductCode	Virtual machine product code
VirtualMachineMemory	Virtual machine assigned RAM
VirtualMachineCpuNumber	Virtual machine assigned cpu cores
VirtualMachineArchitecture	Architecture of virtual machine
VirtualMachineStatus	Status of virtual machine
VirtualMachinePower	Power status of virtual machine
VirtualMachineRescue	Rescue mode status of virtual machine
VirtualMachineIpAddress	IP address of virtual machine
VirtualMachineDeletionScheduledFor	Deletion date and time of virtual machine
VirtualMachinePaidUntil	Date and Time until virtual machine is paid for
VirtualMachineRenewOn	Date and Time of next automatic renewal (and payment)
VirtualMachineAddDate	Date and time virtual machine was created
VirtualMachineLastChangeDate	Date and time of last modification

Creating Virtual Machines

POST https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachineCreate

{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "virtualMachine": {
      "name": "example vm",
      "productCode": "machine-virtualmachine-small-v1-1m",
      "description": "test vm",
      "backupEnabled": false
    }    
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <virtualMachine>
  <description>test vms</description>
  <name>example vm</name>
  <productCode>machine-virtualmachine-small-v1-1m</productCode>
 </virtualMachine>
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",                                     // generated id
    "accountId": "15010100000001",                                   // account id used for creation
    "name": "example vm",
    "description": "test vm",
    "productCode": "machine-virtualmachine-small-v1-1m",
    "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>
    <productCode>machine-virtualmachine-small-v1-1m</productCode>
    <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>

Request	virtualMachineCreate
Url	https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachineCreate
Processing	asynchronous
Response	VirtualMachine object

This method is used to create new virtual machines. It takes a VirtualMachine 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 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 virtualMachinesFind method.

Install OS Image on a Virtual Machine

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "virtualMachineId": "150101aaaaaaaaaa001",
    "json": "{ \"rootUserKeys\": \"\", \"rootUserPass\": \"yourpassword\" }",
    "osId": "debian-bullseye"
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <virtualMachineId>150101aaaaaaaaaa001</virtualMachineId>
 <json>{ "rootUserKeys": "", "rootUserPass": "yourpassword" }</json>
 <osId>debian-bullseye</odId>
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "productCode": "machine-virtualmachine-small-v1-1m",
    "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>
    <productCode>machine-virtualmachine-small-v1-1m</productCode>
    <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>

Request	virtualMachineInstall
Url	https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachineInstall
Processing	asynchronous
Response	VirtualMachine object

In our example we install a Debian OS. Other operating systems may need other variables. One can receive a list of possible operating systems with the osInstallerList method. In the applications variable of this method one can find the possible variables for any OS. The variables must be passed as JSON string in json.

Enabling Rescue Mode

POST https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachineEnableRescue

{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "virtualMachineId": "150101aaaaaaaaaa001",
    "rootPassword" : "jaDr49Ang!sd2eonH",
    "publicKeys" : [],
    "reset" : true
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <virtualMachineId>150101aaaaaaaaaa001</virtualMachineId>
 <rootPasswort>jaDr49Ang!sd2eonH</rootPasswort>
 <publicKeys></publicKeys>
 <reset>true</reset> 
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "productCode": "machine-virtualmachine-small-v1-1m",
    "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>
    <productCode>machine-virtualmachine-small-v1-1m</productCode>
    <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>

Request	virtualMachineEnableRescue
Url	https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachineEnableRescue
Processing	asynchronous
Response	VirtualMachine 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 virtualMachineDisableRescue.

Disabling Rescue Mode

POST https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachineDisableRescue

{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "virtualMachineId": "150101aaaaaaaaaa001",
    "reset" : true
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <virtualMachineId>150101aaaaaaaaaa001</virtualMachineId>
 <reset>true</reset> 
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "productCode": "machine-virtualmachine-small-v1-1m",
    "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>
    <productCode>machine-virtualmachine-small-v1-1m</productCode>
    <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>

Request	virtualMachineDisableRescue
Url	https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachineDisableRescue
Processing	asynchronous
Response	VirtualMachine 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/virtualMachineChangeProduct

{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "virtualMachineId": "150101aaaaaaaaaa001",
    "productCode" : "machine-virtualmachine-large-v1-1m"    
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <virtualMachineId>150101aaaaaaaaaa001</virtualMachineId>
 <productCode>machine-virtualmachine-large-v1-1m</productCode> 
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "productCode": "machine-virtualmachine-large-v1-1m",
    "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>
    <productCode>machine-virtualmachine-large-v1-1m</productCode>
    <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>

Request	virtualMachineChangeProduct
Url	https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachineChangeProduct
Processing	asynchronous
Response	VirtualMachine 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 virtualMachineChangeProductCode, you can change the product code of the virtual machine, upgrading or downgrading to the selected code.

The changes will take effect after the next restart of the virtual machine. You can set the ‘reset’ 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

POST https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachineDelete

{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "virtualMachineId": "150101aaaaaaaaaa001"
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <virtualMachineId>150101aaaaaaaaaa001</virtualMachineId> 
</request>

Response

{
  ...
  "status": "pending"
}

<response>
 <response>  
   <status>pending</status>
 ...
</response>

Request	virtualMachineDelete
Url	https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachineDelete
Processing	asynchronous
Response	none

This method deletes a virtual machine. It will be in status restorable for 7 days, afterwards it will removed automatically.

Purging Virtual Machines

POST https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachinePurgeRestorable

{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "virtualMachineId": "150101aaaaaaaaaa001"
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <virtualMachineId>150101aaaaaaaaaa001</virtualMachineId> 
</request>

Response

{
  ...
  "status": "pending"
}

<response>
 <response>  
   <status>pending</status>
 ...
</response>

Request	virtualMachinePurgeRestorable
Url	https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachinePurgeRestorable
Processing	asynchronous
Response	none

This method removes a restorable object permanently. 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/virtualMachinePowerOn

{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "virtualMachineId": "150101aaaaaaaaaa001"
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <virtualMachineId>150101aaaaaaaaaa001</virtualMachineId> 
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "productCode": "machine-virtualmachine-small-v1-1m",
    "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>
    <productCode>machine-virtualmachine-small-v1-1m</productCode>
    <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>

Request	virtualMachinePowerOn
Url	https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachinePowerOn
Processing	asynchronous
Response	VirtualMachine object

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

Power Off

POST https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachinePowerOff

{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "virtualMachineId": "150101aaaaaaaaaa001"
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <virtualMachineId>150101aaaaaaaaaa001</virtualMachineId> 
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "productCode": "machine-virtualmachine-small-v1-1m",
    "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>
    <productCode>machine-virtualmachine-small-v1-1m</productCode>
    <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>

Request	virtualMachinePowerOff
Url	https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachinePowerOff
Processing	asynchronous
Response	VirtualMachine object

The virtualMachinePowerOff 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/virtualMachineShutdown

{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "virtualMachineId": "150101aaaaaaaaaa001"
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <virtualMachineId>150101aaaaaaaaaa001</virtualMachineId> 
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "productCode": "machine-virtualmachine-small-v1-1m",
    "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>
    <productCode>machine-virtualmachine-small-v1-1m</productCode>
    <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>

Request	virtualMachineShutdown
Url	https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachineShutdown
Processing	asynchronous
Response	VirtualMachine object

By using the virtualMachineShutdown 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/virtualMachineReboot

{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "virtualMachineId": "150101aaaaaaaaaa001"
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <virtualMachineId>150101aaaaaaaaaa001</virtualMachineId> 
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "productCode": "machine-virtualmachine-small-v1-1m",
    "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>
    <productCode>machine-virtualmachine-small-v1-1m</productCode>
    <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>

Request	virtualMachineReboot
Url	https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachineReboot
Processing	asynchronous
Response	VirtualMachine object

By using the virtualMachineReboot method you can gracefully reboot a virtual machine. Similarly to the virtualMachineShutdown 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/virtualMachineReset

{
    ...
    "authToken": "$$YOUR API KEY$$",    
    "virtualMachineId": "150101aaaaaaaaaa001"
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <virtualMachineId>150101aaaaaaaaaa001</virtualMachineId> 
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "name": "example vm",
    "description": "test vm",
    "productCode": "machine-virtualmachine-small-v1-1m",
    "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>
    <productCode>machine-virtualmachine-small-v1-1m</productCode>
    <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>

Request	virtualMachineReset
Url	https://secure.hosting.de/api/machine/v1/jsonxml/virtualMachineReset
Processing	asynchronous
Response	VirtualMachine object

By using the virtualMachineReset 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",
    "comments": "",
    "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>
 <comments></comments>
 <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`
comments	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",
    "comments": "Opt. example comments",
    "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>
 <comments>Opt. example comments</comments>
 <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
bundleId	string	opt	ID of the bundle which contains the websppace of the vHost.
name	string	req	Name of `webspace`
comments	string	opt	Additional information about `webspace`. Value can be freely defined by platform account holder.
webspaceName	string	opt	`webspace` key: short alphanumeric string used as unique identifier system generated names.
productCode	string	req	product code for this webspace.
storageQuotaIncluded	int	out-only	Storage Quota which is included (free without costs) in the webspace
storageQuota	int	out-only	Storage Quota the wespace has defined in reality
storageUsed	int	out-only	Storgae which is used on the webserver
storageQuotaUsedRatio	double	out-only	Ratio of storageQuota and storageQuotaUsed
includedPhpExecutionTime	int	out-only	Maximum PHP Execution Time which is included (free without costs) in the webspace
phpExecutionTime	int	opt	Maximum PHP Execution Time the webspace has configured in reality.
includedPhpMemory	int	out-only	PHP Memory Limit which is included (free without costs) in the webspace
phpMemory	int	opt	PHP Memory Limit the webspace has configured in reality.
status	string	out-only	Status of `webspace`
restrictions	list	out-only	Restrictions, mostly set by our operators.
accesses	list	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.
serverIpv6	string	out-only	The IPv6 address to configure for domains using the webspace in DNS.
hostName	string	out-only	General Hostname for the webspace. Can be used for FTP Connections for example.
emailChecksActivated	bool	out-only	If true, all emails sent from the webspace are counted.
emailRateLimitQuota	int	out-only	The maximum number of emails the webspace can send in 30 minutes.
webserverId	string	out-only	ID of the webserver on which the webspace was created.
poolId	string	opt	ID of the pool in which the webspace was created. Only used when the webspace was created on a Managed Cloud Server.
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
cronJobs	list	opt	A list of `CronJob` objects describing active cron jobs for the `webspace`.

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`
homeDir	string	opt	If set, the used is rooted to this subdirectory. Only affects Users with FTP access.
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>

Request	webspacesFind
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/webspacesFind
Processing	synchronous
Response	FindWebspacesResult

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-v1-1m",
        "storageQuota": 10240
    },
    "accesses": [
        {
            "userId": "15010100000091",
            "ftpAccess": true,
            "sshAccess": true,
            "statsAccess": true
        }
    ]
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <webspace>
  <name>Example</name>
  <productCode>webhosting-webspace-v1-1m</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",
        "comments": "",
        "productCode": "webhosting-webspace-v1-1m",
        "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>
  <comments></comments>
  <productCode>webhosting-webspace-v1-1m</productCode>
  <restorableUntil></restorableUntil>
  <serverIpv4>192.0.2.80</serverIpv4>
  <status>creating</status>
  <storageQuota>10240</storageQuota>
  <storageQuotaUsedRatio>0</storageQuotaUsedRatio>
  <storageUsed>0</storageUsed>
 </response>
</response>

Request	webspaceCreate
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/webspaceCreate
Processing	asynchronous
Response	Webspace

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",
		"comments": "some comment about this webspace",
        "productCode": "webhosting-webspace-v1-1m",
        "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>
  <comments>some comment about this webspace</comments>
  <productCode>webhosting-webspace-v1-1m</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",
		"comments": "some comment about this webspace",
        "productCode": "webhosting-webspace-v1-1m",
        "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>
  <comments>some comment about this webspace</comments>
  <productCode>webhosting-webspace-v1-1m</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>

Request	webspaceUpdate
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/webspaceUpdate
Processing	asynchronous
Response	Webspace

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-v1-1m",
        "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-v1-1m</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>

Request	webspaceDelete
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/webspaceDelete
Processing	asynchronous
Response	Webspace

Parameter	Type	Required	Description
webspaceId	string	req	ID of webspace to be deleted

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>

Request	usersFind
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/usersFind
Processing	synchronous
Response	FindUsersResult

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
UserComments	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",
        "comments": "",
        "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>
  <comments></comments>
  <id>15010100000091</id>
  <lastChangeDate>2016-03-14T08:50:53Z</lastChangeDate>
  <name>John Smith</name>
  <sshKey></sshKey>
  <status>active</status>
  <userName>ayapzk</userName>
 </response>
</response>

Request	userCreate
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/userCreate
Processing	synchronous
Response	User

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": {
        "comments": "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>
  <comments>Had to change password on customer request.</comments>
  <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",
        "comments": "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>
  <comments>Had to change password on customer request.</comments>
  <id>15010100000091</id>
  <lastChangeDate>2016-03-14T09:04:23Z</lastChangeDate>
  <name>John Smith</name>
  <sshKey></sshKey>
  <status>active</status>
  <userName>ayapzk</userName>
 </response>
</response>

Request	userUpdate
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/userUpdate
Processing	asynchronous
Response	User

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, comments, 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>

Request	userDelete
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/userDelete
Processing	synchronous
Response	none

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
comments	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.
parameters	list	opt	If your script uses parameters, please add them to this list.
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.
interpreterVersion	string	opt	For type php, you can choose between different PHP Versions. Valid values are e.g. `5.6` or `7.3`.
schedule	string	req	Available schedule options: `1min`, `5min`, `10min` 15min`,` 30min`,` 1hour`,` 2hour`,` 3hour`,` 4hour`,` 6hour`,` 12hour`,` daily`,` weekly`, or` monthly`.
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
additionalDomainNames	list <string>	opt	Additional domain names for this vHost, like domainNAme can either be Unicode or ASCII format.
additionalDomainNamesUnicode	list <string>	out-only	Additional domain names for this vHost
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`.
serverTypeChangeBlocked	bool	opt	If true, one can not change the serverType.
httpUsers	list <string>	opt	Users for HTTP Authentication
locations	list <Location object>	opt	List of `Location` objects
sslSettings	SSL Settings object	opt	If set, SSL is enabled
phpVersion	string	opt	php version used to execute php scripts. Available options: `5.6` up to `7.3`. Default: `7.3`.
blocked	bool	opt	true if the vHost was blocked in case of hacked website or abuse by our operators.
restorableUntil	datetime	out-only	If the vHost was deleted, it can be restored until that date.
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": "VHostDomainNameAce",
        "value": "example.*"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "VHostDomainNameAce",
        "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>

Request	vhostsFind
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostsFind
Processing	synchronous
Response	FindVHostsResult

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>

Request	vhostCreate
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostCreate
Processing	asynchronous
Response	VHost

Parameter	Type	Required	Description
vhost	VHost object	req	Complete `vhost` object
phpIni	PHP.ini object	opt	PHP Configuration for this `vhost`
sslPrivateKey	string	opt	Private SSL key in PEM format. Required when SSL is enabled.
setHttpUserPasswords	list <HttpUser>	opt	List of HttpUsers with access to Locations of the `vhost`. See HTTP User objects

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>

Request	vhostUpdate
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostUpdate
Processing	asynchronous
Response	VHost

Parameter	Type	Required	Description
vhost	VHost object	req	Complete `vhost` object
phpIni	PHP.ini object	opt	PHP Configuration for this `vhost`
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.
setHttpUserPasswords	list <HttpUser>	opt	List of HttpUsers with access to Locations of the `vhost`. See HTTP User objects
expectedCosts	int	opt	If your update would produce costs, e.g. if your PHP memory limit will be upgraded, you have to send the expected costs as an acknowledgement.

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>

Request	vhostDelete
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostDelete
Processing	asynchronous
Response	none

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>

Request	vhostRestore
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostRestore
Processing	asynchronous
Response	none

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.

The SSL Settings Object

SSL Settings Object

Property	Type	Required	Description
profile	string	opt	Profile of the SSL Implementation, we support `modern` and `intermediate`
certificates	string	opt	Contains all Certificates needed by the webserver (Server, Intermediate)
managedSslProductCode	string	opt	ProductCode of the SSL Certificate
managedSslStatus	string	opt	Status of the SSL Certificate
hstsMaxAge	int	opt	Maximum Validity of HSTS
hstsIncludeSubdomains	bool	opt	Include Subdomains in HSTS Settings
hstsAllowPreload	bool	opt	Allow preloading in HSTS

Using your own certificate

If you want to use your own certificate, Use the SSL Settings object and add all needed certificates to the parameter certificates. The object can then be added to the vhost. You have to specify the sslPrivateKey parameter when calling vhostCreate or vhostUpdate.

Our system checks the values and if e.g. Key and Certificate to not match, you will receive an error.

Activating automatic SSL for a VHost

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostActivateSsl

{
    "authToken": "$$YOUR API KEY$$",
    "vhost": {
        ...
        "sslSettings": {
            "profile": "modern",
            "managedSslProductCode": "ssl-letsencrypt-dv-3m"
        }
    }
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <vhost>
  ...
  <sslSettings>
    <profile>modern</profile>
    <managedSslProductCode>ssl-letsencrypt-dv-3m</managedSslProductCode>
  </sslSettings>
 </vhost>
</request>

Response

{
    ...
    "response": {
        ...
        "sslSettings": {
            "certificates": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
            "hstsAllowPreload": null,
            "hstsIncludeSubdomains": null,
            "hstsMaxAge": null,
            "managedSslProductCode": "ssl-letsencrypt-dv-3m",
            "managedSslStatus": "active",
            "profile": "modern"
        }
    },
    ...
}

<response>
 <response>
  <sslSettings>
    <certificates>-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----"</certificates>
    <hstsAllowPreload>null</hstsAllowPreload>
    <hstsIncludeSubdomains>null</hstsIncludeSubdomains>
    <hstsMaxAge>null</hstsMaxAge>
    <managedSslProductCode>ssl-letsencrypt-dv-3m</managedSslProductCode>
    <managedSslStatus>active</managedSslStatus>
    <profile>modern</profile>
  </sslSettings>
 </response>
</response>

Request	vhostActivateSsl
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostActivateSsl
Processing	asynchronous
Response	VHost

Our system can automatically add Let’s Encrypt or RapidSSL certificates. In this case, you only have to specify the managedSslProductCode parameter in the the SSL Settings object. Everything in background will be done by our system. This option is only available if either your DNS zone is hosted with us or the domain name of the vhost points to our webserver. You could check if we are capable to create automatic certificates with the checkAutoValidationCapable of the SSL API.

All certificates created automatically by us will also be renewed automatically.

This features is available for the following productCodes:

ssl-geotrust-rapidssl-12m
ssl-letsencrypt-dv-3m

The PHP Configuration Meta Data Object

The PHP Configuration Meta Data object contains available Values for a specific PHP Settings. Only these PHP Settings can be specified in a PHP.ini object to override the default settings for a vhost.

PHP Configuration Meta Data Object

Property	Type	Required	Description
phpVersions	list	req	Lists the PHP Versions for which this Meta Data Object can be used
key	string	req	Key of the Meta Data Object
type	string	req	Type of the Meta Data Object
min	int	opt	minimum available Value
max	int	opt	maximum available Value
availableValues	list	opt	Available Values
defaultValue	string	opt	default Value
accessLevels	list	opt	Shows who has access to set this Meta Data Object
resetOnPhpVersionChange	bool	opt	If true and you change the PHP Version for a vHost, this setting will be resetted to its default
upgrades	list	opt	List of available chargeable Upgrades including productCodes

The PHP.ini Object

To specify PHP Settings you can use a PHP.ini object. Our system allows to define some PHP Values, but not all.

PHP.ini Object

Property	Type	Required	Description
vhostId	string	opt	ID of the vHost
values	list	req	List of different PHP.ini Values

The PHP.ini Value Object

PHP.ini Value Object

Property	Type	Required	Description
key	string	req	Key Name of the PHP.ini Value, e.g. display_output
value	string	req	Value of the PHP.ini Value, e.g. 0
immutable	bool	out-only	If true, the Value of this Key cannot be changed
deletable	bool	out-only	If true, the Key cannot be deleted
metadata	PhpConfigurationMetadata	out-only	Displays information about this PHP.ini Value, e.g. for which PHP Versions it is available.

Getting a list of PHP Settings

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/phpConfigurationMetadata

{
    "authToken": "$$YOUR API KEY$$",
    "all": true
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <all>true</all>
</request>

Response

{
    ...
    "responses": [
        // PhpConfigurationMetaData Objects
    ]
}

<responses>
    <item>
        // PhpConfigurationMetaData Object
    </item>
    ...
</responses>

Request	phpConfigurationMetadata
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/phpConfigurationMetadata
Processing	synchronous
Response	list <PhpConfigurationMetadata>

Parameter	Type	Required	Description
all	bool	opt	If true, all available PHP Settings are returned.

Getting a default PHP.ini Object

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostPhpIniDefault

{
    "authToken": "$$YOUR API KEY$$",
    "webspaceId": 15010100000094
}

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

Response

{
    ...
    "response": [
        // PhpIni Object
    ]
}

<response>
  // PhpIni Object
</response>

Request	vhostPhpIniDefault
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostPhpIniDefault
Processing	synchronous
Response	PhpIni

{
    "vhostId": null,
    "values": [
        {
            "deletable": false,
            "immutable": false,
            "key": "error_reporting",
            "metadata": {
                "accessLevels": [
                    "user"
                ],
                "defaultValue": "0",
                "key": "error_reporting",
                "max": null,
                "min": null,
                "phpVersions": [
                    "5.6",
                    "7.0",
                    "7.1",
                    "7.2",
                    "7.3",
                    "7.4"
                ],
                "resetOnPhpVersionChange": false,
                "type": "string"
            },
            "value": "0"
        }
        ...
    ]
}

<phpIni>
   <vhostId>null</vhostId>
   <values>
      <item>
      <key>error_reporting</key>
      <value>0</value>
      <immutable>false</immutable>
      <deletable>false</deletable>
      <metadata>
      <phpVersions>
         <item>5.6</item>
         <item>7.0</item>
         <item>7.1</item>
         <item>7.2</item>
         <item>7.3</item>
         <item>7.4</item>
      </phpVersions>
      <key>error_reporting</key>
      <type>string</type>
      <min xsi:nil="true"/>
      <max xsi:nil="true"/>
      <defaultValue>0</defaultValue>
      <accessLevels>
         <item>user</item>
      </accessLevels>
      <resetOnPhpVersionChange>false</resetOnPhpVersionChange>
      </metadata>
      </item>
   </values>
</phpIni>

This method returns a default PHP.ini Object for the specified webspace.

Parameter	Type	Required	Description
webspaceId	string	req	ID of the webspace
phpVersion	string	opt	If not specified, the method will return the default PHP.ini Object for the default PHP Version.

Getting the PHP.ini Object for a specific vhost

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostPhpIniList

{
    "authToken": "$$YOUR API KEY$$",
    "vhostId": 15010100000094
}

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

Response

{
    ...
    "response": [
        // PhpIni Object
    ]
}

<response>
  // PhpIni Object
</response>

Request	vhostPhpIniList
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/vhostPhpIniList
Processing	synchronous
Response	PhpIni

{
    "vhostId": null,
    "values": [
        {
            "deletable": false,
            "immutable": false,
            "key": "error_reporting",
            "metadata": {
                "accessLevels": [
                    "user"
                ],
                "defaultValue": "0",
                "key": "error_reporting",
                "max": null,
                "min": null,
                "phpVersions": [
                    "5.6",
                    "7.0",
                    "7.1",
                    "7.2",
                    "7.3",
                    "7.4"
                ],
                "resetOnPhpVersionChange": false,
                "type": "string"
            },
            "value": "0"
        }
        ...
    ]
}

<phpIni>
   <vhostId>null</vhostId>
   <values>
      <item>
      <key>error_reporting</key>
      <value>0</value>
      <immutable>false</immutable>
      <deletable>false</deletable>
      <metadata>
      <phpVersions>
         <item>5.6</item>
         <item>7.0</item>
         <item>7.1</item>
         <item>7.2</item>
         <item>7.3</item>
         <item>7.4</item>
      </phpVersions>
      <key>error_reporting</key>
      <type>string</type>
      <min xsi:nil="true"/>
      <max xsi:nil="true"/>
      <defaultValue>0</defaultValue>
      <accessLevels>
         <item>user</item>
      </accessLevels>
      <resetOnPhpVersionChange>false</resetOnPhpVersionChange>
      </metadata>
      </item>
   </values>
</phpIni>

This method returns the PHP.ini Object for the specified vhost.

Parameter	Type	Required	Description
vhostId	string	req	ID of the vhost

The PHP Version object

PHP Version objects are only returned with the phpversion method. They are never used in requests.

PHP Version Object

Property	Type	Required	Description
accessLevels	list	req	Accesslevels which are allowed to use this version
isDefault	bool	req	If true this version is the default. The default may change from time to time.
version	string	req	PHP Version string, used for specifying the `vhosts` phpVersion

Getting available PHP Versions

This method is used to get a list of all available PHP Versions. It returns a list of PHP Version objects. To specify the PHP Version for a vhost, you have to set the phpVersion parameter of a vhost to a string. The string must match the parameter version of the PhpVersion object.

POST https://secure.hosting.de/api/webhosting/v1/jsonxml/phpversions

{
    "authToken": "$$YOUR API KEY$$"
}

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

Response

{
    ...
    "responses": [
        // PhpVersion Objects
    ]
}

<responses>
    <item>
        // PhpVersion Object
    </item>
    ...
</responses>

Request	phpversions
Url	https://secure.hosting.de/api/webhosting/v1/jsonxml/phpversions
Processing	synchronous
Response	list <PhpVersion>

{
    "accessLevels": [
        "user"
    ],
    "isDefault": false,
    "version": "5.6"
}

<phpVersion>
 <accessLevels>
    <accessLevel>user</accessLevel>
 </accessLevels>
 <isDefault>false</isDefault>
 <version>5.6</version>
</phpVersion>

This method has no parameters.

Updating PHP Settings

You have to use vhostUpdate if you want to change PHP Settings of a vhost.

The HTTP User Object

If you want a location being restricted, you can create HTTP Users. HTTP Users can be created or modified by creating or updating the specified vhost.

HTTP User Object

Property	Type	Required	Description
name	string	req	Username of the HTTP User
password	string	req	Password of the HTTP Header in cleartext

The Location Object

With a location object one can customize the nginx configuration. Locations can be created or modified by creating or updating the specified vhost.

Location Object

Property	Type	Required	Description
setByProfile	bool	opt	If true, this Location was added by a profile
locationType	string	req	Type of the Location. We support `location`, `redirect` and `denyLocation`.
matchType	string	req	Available options are `directory`, `exact` or `regex`
matchString	string	opt	String to match
redirectionStatus	string	opt	Status of the redirection
redirectionUrl	string	opt	URL of the redirection target.
phpEnabled	bool	opt	If true, this Location parses PHP Files
directoryListingEnabled	bool	opt	If true, this Location does a Directory Listing
blockDotfiles	bool	opt	If true, Files beginning with a dot (.htaccess) are blocked for HTTP Requests, defaults to true
mapScript	string	opt	If filled, all requests will go to this script.
mapStyle	string	opt	Style of the map script
httpHeader	list	opt	List of additional HTTP Headers send to the client
restrictToHttpUsers	list	opt	Usernames of the HTTP Users this location is restricted to

The HTTP Header Object

Our system allows to activate some additional HTTP Headers. These can be specified within a location object.

HTTP Header Object

Property	Type	Required	Description
name	string	req	Name of the HTTP Header
content	string	req	Content of the HTTP Header

Database

The database section of the API allows you to create and manage databases. At the moment we support MariaDB/MySQL databases.

Available Database Products

Product	Validity Periods (months)	ProductCode
MariaDB Single Database	1	database-mariadb-single-v1-1m
MariaDB Single Database	12	database-mariadb-single-v1-12m

The Database User Object

A MySQL User is represented by a user object.

{
    "accountId": "15010100000001",
    "addDate": "2016-03-14T08:50:53Z",
    "comments": "",
    "id": "15010100000091",
    "lastChangeDate": "2016-03-14T08:50:53Z",
    "name": "John Smith",
    "dbUserName": "ayapzk",
    "status": "active"
}

<user>
 <accountId>15010100000001</accountId>
 <addDate>2016-03-14T08:50:53Z</addDate>
 <comments></comments>
 <id>15010100000091</id>
 <lastChangeDate>2016-03-14T08:50:53Z</lastChangeDate>
 <name>John Smith</name>
 <dbUserName>ayapzk</dbUserName>
 <status>active</status>
</user>

User Object

Property	Type	Required	Description
id	string	req	User ID
accountId	string	opt	ID of user managing account
name	string	req	free Name which can be specified to identify the `user`
dbUserName	string	out-only	Generated Username of the `user`
status	string	opt	Status of the u`user`ser
comments	string	opt	free comments which can be specified to identify the `user`
addDate	datetime	out-only	Date and time of `user` creation
lastChangeDate	datetime	out-only	Date and time of last `user` modification

The DatabaseAccess Object

The databaseAccess object is the representation of a user which is linked to a database.

{
    "addDate": "2016-03-14T09:11:24Z",
    "lastChangeDate": "2016-03-14T09:11:24Z",
    "accessLevel": [ "read", "write", "schema" ],
    "userId": "15010100000091",
    "dbLogin": "webv4h25r_ayapzk",
    "databaseId": "15010100000094"
}

<databaseAccess>
 <addDate>2016-03-14T09:11:24Z</addDate>
 <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
 <accessLevel>
    <item>read</item>
    <item>write</item>
    <item>schema</item>
 </accessLevel>
 <userId>15010100000091</userId>
 <dbLogin>dbv4h25r_ayapzk</dbLogin>
 <databaseId>15010100000094</databaseId>
</databaseAccess>

DatabaseAccess Object

Property	Type	Required	Description
databaseId	string	opt	Database ID
userId	string	req	User ID
dbLogin	string	opt	Username for MySQL
accessLevel	list	req	Rights for this user, possible values: `read`, `write`, `schema`
addDate	datetime	out-only	Date and time of `databaseAccess` creation
lastChangeDate	datetime	out-only	Date and time of last `databaseAccess` modification

The Database Object

A database object represents the MySQL database.

{
    "accesses": [
        {
            "addDate": "2016-03-14T09:11:24Z",
            "lastChangeDate": "2016-03-14T09:11:24Z",
            "accessLevel": [ "read", "write", "schema" ],
            "userId": "15010100000091",
            "userName": "dbv4h25r_ayapzk",
            "databaseId": "15010100000094"
        }
    ],
    "bundleId": null,
    "poolId": null,
    "accountId": "15010100000001",
    "addDate": "2016-03-14T09:11:24Z",
    "paidUntil": "2016-04-14T09:11:24Z",
    "renewOn": "2016-04-14T09:11:24Z",
    "deletionScheduledFor": null,
    "id": "15010100000094",
    "lastChangeDate": "2016-03-14T09:11:24Z",
    "name": "Example",
    "productCode": "database-mariadb-single-v1-12m",
    "restorableUntil": null,
    "status": "creating",
    "storageQuota": 512,
    "storageQuotaIncluded": 512,
    "storageQuotaUsedRatio": 0,
    "storageUsed": 0,
    "dbName": "dbv4h25r",
    "hostName": "dbv4h25r.mariadb.routing.zone",
    "dbEngine": "MariaDB",
    "dbType": "single",
    "forceSsl": false,
    "restrictions": [],
    "limitations": []
}

<database>
 <accesses>
  <item>
    <addDate>2016-03-14T09:11:24Z</addDate>
    <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
    <accessLevel>
        <item>read</item>
        <item>write</item>
        <item>schema</item>
    </accessLevel>
    <userId>15010100000091</userId>
    <dbLogin>dbv4h25r_ayapzk</dbLogin>
    <databaseId>15010100000094</databaseId>
  </item>
 </accesses>
 <bundleId></bundleId>
 <poolId></poolId>
 <accountId>1</accountId>
 <addDate>2016-03-14T09:11:24Z</addDate>
 <paidUntil>2016-04-14T09:11:24Z</paidUntil>
 <renewOn>2016-04-14T09:11:24Z</renewOn>
 <deletionScheduledFor></deletionScheduledFor>
 <id>15010100000094</id>
 <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
 <name>Example</name>
 <productCode>database-mariadb-single-v1-12m</productCode>
 <restorableUntil></restorableUntil>
 <status>creating</status>
 <storageQuota>512</storageQuota>
 <storageQuotaIncluded>512</storageQuotaIncluded>
 <storageQuotaUsedRatio>0</storageQuotaUsedRatio>
 <storageUsed>0</storageUsed>
 <dbName>dbv4h25r</dbName>
 <hostName>dbv4h25r.mariadb.routing.zone</hostName>
 <dbEngine>MariaDB</dbEngine>
 <dbType>single</dbType>
 <forceSsl>false</forceSsl>
 <limitations/>
 <restrictions/>
</database>

Database Object

Property	Type	Required	Description
id	string	cf. description	ID of `database`. Ignored in `database` create requests. Required in all other requests.
accountId	string	opt	ID of the account to which the `database` belongs to
bundleId	string	opt	ID of the bundle in which the `database` is created
name	string	req	free Name which can be specified to identify the `database`
dbName	string	out-only	Generated Name of the `database` to use for Connections
hostName	string	out-only	General Hostname for the database. Can be used for MySQL Connections for example.
dbEngine	string	out-only	Engine of the database, at the moment we just support `MariaDB`.
dbType	string	out-only	Type of the database, at the moment we just support `single`.
productCode	string	opt	The productCode of the `database`
forceSsl	bool	opt	At the moment, we just support `false`
storageQuota	int	opt	Real Storage Quota for the `database`
storageQuotaIncluded	int	out-only	Storage Quota which is included in the `database` for no costs.
storageUsed	int	out-only	Storage Quota used for all data in the `database`
storageQuotaUsedRatio	double	out-only	Ratio of storageUsed and storageQuota
limitations		out-only	Limitations, at the moment we just support one default
status	string	opt	Status of the database
comments	string	opt	free comments which can be specified to identify the `database`
restrictions	list	out-only	Restrictions, mostly set by our operators.
accesses	list	out-only	A list of `DatabaseAccess` objects with all current authorizations for users.
poolId	string	out-only	PoolId in which the `database` was created
paidUntil	datetime	out-only	Time that the `database` is paid for
renewOn	datetime	out-only	Date on which the `database` will be invoice again
deletionScheduledFor	datetime	out-only	Deletion date and time of `database`
restorableUntil	datetime	out-only	Date and time until `database` is restorable
addDate	datetime	out-only	Date and time of `database` creation
lastChangeDate	datetime	out-only	Date and time of last `database` modification

Listing Users

POST https://secure.hosting.de/api/database/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>

Request	usersFind
Url	https://secure.hosting.de/api/database/v1/jsonxml/usersFind
Processing	synchronous
Response	FindUsersResult

The function usersFind lets you list existing Users. The usual sorting and filtering options apply.

The following fields are available for filtering and sorting:

Field	Description
AccountId	ID of account the user belongs to
UserId	ID of user
UserName	Name of the user
UserDbName
UserStatus	Status of the user
UserLastChangeDate	Date and time of the last change
UserAddDate	Date and time the user was created
UserAccessesDatabaseId	Databases as ID to which the user has access

Creating Users

POST https://secure.hosting.de/api/database/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",
        "comments": "",
        "id": "15010100000091",
        "lastChangeDate": "2016-03-14T08:50:53Z",
        "name": "John Smith",
        "dbUserName": "ayapzk",
        "status": "active"
    },
    ...
}

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

Request	userCreate
Url	https://secure.hosting.de/api/database/v1/jsonxml/userCreate
Processing	synchronous
Response	User

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 databases.

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/database/v1/jsonxml/userUpdate

{
    "authToken": "$$YOUR API KEY$$",
    "user": {
        "comments": "Had to change password on customer request.",
        "id": "15010100000091",
        "name": "John Smith",
        "dbUserName": "ayapzk",
        "status": "active"
    },
    "password": "OgL2OtCHnOTd"
}

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

Response

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

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

Request	userUpdate
Url	https://secure.hosting.de/api/database/v1/jsonxml/userUpdate
Processing	asynchronous
Response	User

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 and comments 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/database/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>

Request	userDelete
Url	https://secure.hosting.de/api/database/v1/jsonxml/userDelete
Processing	synchronous
Response	none

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 database.

Listing Databases

POST https://secure.hosting.de/api/database/v1/jsonxml/databasesFind

{
    "authToken": "$$YOUR API KEY$$",
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "DatabaseName",
        "order": "ASC"
    }
}

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

Response

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

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

Request	databasesFind
Url	https://secure.hosting.de/api/database/v1/jsonxml/databasesFind
Processing	synchronous
Response	FindDatabasesResult

The function databasesFind lets you list existing Databases. The usual sorting and filtering options apply.

The following fields are available for filtering and sorting:

Field	Description
AccountId	ID of account the user belongs to
DatabaseId	ID of the database
DatabaseServerId	ID of the database server
BundleId	ID of the bundle
DatabaseName	Name of the database in UI
DatabaseDbName	real Name of the database in the system
DatabaseDbEngine	Engine of the database
DatabaseDbType	Type of the database
DatabaseProductCode	ProductCode, see table below
DatabaseStorageQuota	Storage Quota of the database in MB
DatabaseStorageUsed	Used Storage Quota in MB
DatabaseStorageQuotaUsedRatio	Ratio of used vs. free Storage Quota
DatabaseStatus	Status of the database
DatabasePaidUntil	Date, until the database is paid
DatabaseRenewOn	Date, on which the database will be invoiced again
DatabaseLastChangeDate	Date and time of the last change
DatabaseAddDate	Date and time the database was created
DatabaseAccessesUserId	ID of a user, to find all databases a user has access to

Creating Databases

POST https://secure.hosting.de/api/database/v1/jsonxml/databaseCreate

{
    "authToken": "$$YOUR API KEY$$",
    "database": {
        "name": "Example",
        "productCode": "database-mariadb-single-v1-12m",
        "storageQuota": 512
    },
    "accesses": [
        {
            "userId": "15010100000091",
            "accessLevel": [ "read", "write", "schema" ]
        }
    ]
}

<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <webspace>
  <name>Example</name>
  <productCode>database-mariadb-single-v1-12m</productCode>
  <storageQuota>512</storageQuota>
 </webspace>
 <accesses>
  <item>
    <accessLevel>
        <item>read</item>
        <item>write</item>
        <item>schema</item>
    </accessLevel>
    <userId>15010100000091</userId>
  </item>
 </accesses>
</request>

Response

{
    ...
    "response": {
        "accesses": [
            {
                "addDate": "2016-03-14T09:11:24Z",
                "lastChangeDate": "2016-03-14T09:11:24Z",
                "accessLevel": [ "read", "write", "schema" ],
                "userId": "15010100000091",
                "userName": "dbv4h25r_ayapzk",
                "databaseId": "15010100000094"
            }
        ],
        "bundleId": null,
        "poolId": null,
        "accountId": "15010100000001",
        "addDate": "2016-03-14T09:11:24Z",
        "paidUntil": "2016-04-14T09:11:24Z",
        "renewOn": "2016-04-14T09:11:24Z",
        "deletionScheduledFor": null,
        "id": "15010100000094",
        "lastChangeDate": "2016-03-14T09:11:24Z",
        "name": "Example",
        "productCode": "database-mariadb-single-v1-12m",
        "restorableUntil": null,
        "status": "creating",
        "storageQuota": 512,
        "storageQuotaIncluded": 512,
        "storageQuotaUsedRatio": 0,
        "storageUsed": 0,
        "dbName": "dbv4h25r",
        "hostName": "dbv4h25r.mariadb.routing.zone",
        "dbEngine": "MariaDB",
        "dbType": "single",
        "forceSsl": false,
        "restrictions": [],
        "limitations": []
    },
    ...
}

<response>
 <response>
    <accesses>
        <item>
            <addDate>2016-03-14T09:11:24Z</addDate>
            <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
            <accessLevel>
                <item>read</item>
                <item>write</item>
                <item>schema</item>
            </accessLevel>
            <userId>15010100000091</userId>
            <dbLogin>dbv4h25r_ayapzk</dbLogin>
            <databaseId>15010100000094</databaseId>
        </item>
    </accesses>
    <bundleId></bundleId>
    <poolId></poolId>
    <accountId>1</accountId>
    <addDate>2016-03-14T09:11:24Z</addDate>
    <paidUntil>2016-04-14T09:11:24Z</paidUntil>
    <renewOn>2016-04-14T09:11:24Z</renewOn>
    <deletionScheduledFor></deletionScheduledFor>
    <id>15010100000094</id>
    <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
    <name>Example</name>
    <productCode>database-mariadb-single-v1-12m</productCode>
    <restorableUntil></restorableUntil>
    <status>creating</status>
    <storageQuota>512</storageQuota>
    <storageQuotaIncluded>512</storageQuotaIncluded>
    <storageQuotaUsedRatio>0</storageQuotaUsedRatio>
    <storageUsed>0</storageUsed>
    <dbName>dbv4h25r</dbName>
    <hostName>dbv4h25r.mariadb.routing.zone</hostName>
    <dbEngine>MariaDB</dbEngine>
    <dbType>single</dbType>
    <forceSsl>false</forceSsl>
    <limitations/>
    <restrictions/>
 </response>
</response>

Request	databaseCreate
Url	https://secure.hosting.de/api/database/v1/jsonxml/databaseCreate
Processing	asynchronous
Response	Database

Parameter	Type	Required	Description
database	Database object	req	Complete `database` object
accesses	list <databaseAccess object>	req	List of user authorizations with access to `database` (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 databaseCreate create a new database. After the database is created users who are authorized can connect to it using a MySQL client.

Updating Databases

POST https://secure.hosting.de/api/database/v1/jsonxml/databaseUpdate

{
    "authToken": "$$YOUR API KEY$$",
    "database": {
        "id": "15010100000094",
        "name": "Example",
        "productCode": "database-mariadb-single-v1-12m",
        "storageQuota": 1024
    },
    "accesses": [
        {
            "addDate": "2016-03-14T09:11:24Z",
            "lastChangeDate": "2016-03-14T09:11:24Z",
            "accessLevel": [ "read", "write", "schema" ],
            "userId": "15010100000091",
            "userName": "dbv4h25r_ayapzk",
            "databaseId": "15010100000094"
        }
    ]
}

<request>
 <accesses>
  <item>
    <addDate>2016-03-14T09:11:24Z</addDate>
    <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
    <accessLevel>
        <item>read</item>
        <item>write</item>
        <item>schema</item>
    </accessLevel>
    <userId>15010100000091</userId>
    <userName>dbv4h25r_ayapzk</userName>
    <databaseId>15010100000094</databaseId>
  </item>
 </accesses>
 <authToken>$$YOUR API KEY$$</authToken>
 <database>
  <id>15010100000094</id>
  <name>Example</name>
  <productCode>database-mariadb-single-v1-12m</productCode>
  <storageQuota>1024</storageQuota>
 </database>
</request>

Response

{
    ...
    "response": {
        "accesses": [
            {
                "addDate": "2016-03-14T09:11:24Z",
                "lastChangeDate": "2016-03-14T09:11:24Z",
                "accessLevel": [ "read", "write", "schema" ],
                "userId": "15010100000091",
                "userName": "dbv4h25r_ayapzk",
                "databaseId": "15010100000094"
            }
        ],
        "bundleId": null,
        "poolId": null,
        "accountId": "15010100000001",
        "addDate": "2016-03-14T09:11:24Z",
        "paidUntil": "2016-04-14T09:11:24Z",
        "renewOn": "2016-04-14T09:11:24Z",
        "deletionScheduledFor": null,
        "id": "15010100000094",
        "lastChangeDate": "2016-03-14T09:11:24Z",
        "name": "Example",
        "productCode": "database-mariadb-single-v1-12m",
        "restorableUntil": null,
        "status": "active",
        "storageQuota": 1024,
        "storageQuotaIncluded": 512,
        "storageQuotaUsedRatio": 0,
        "storageUsed": 0,
        "dbName": "dbv4h25r",
        "hostName": "dbv4h25r.mariadb.routing.zone",
        "dbEngine": "MariaDB",
        "dbType": "single",
        "forceSsl": false,
        "restrictions": [],
        "limitations": []
    },
    ...
}

<response>
 <response>
    <accesses>
        <item>
            <addDate>2016-03-14T09:11:24Z</addDate>
            <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
            <accessLevel>
                <item>read</item>
                <item>write</item>
                <item>schema</item>
            </accessLevel>
            <userId>15010100000091</userId>
            <dbLogin>dbv4h25r_ayapzk</dbLogin>
            <databaseId>15010100000094</databaseId>
        </item>
    </accesses>
    <bundleId></bundleId>
    <poolId></poolId>
    <accountId>1</accountId>
    <addDate>2016-03-14T09:11:24Z</addDate>
    <paidUntil>2016-04-14T09:11:24Z</paidUntil>
    <renewOn>2016-04-14T09:11:24Z</renewOn>
    <deletionScheduledFor></deletionScheduledFor>
    <id>15010100000094</id>
    <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
    <name>Example</name>
    <productCode>database-mariadb-single-v1-12m</productCode>
    <restorableUntil></restorableUntil>
    <status>active</status>
    <storageQuota>1024</storageQuota>
    <storageQuotaIncluded>512</storageQuotaIncluded>
    <storageQuotaUsedRatio>0</storageQuotaUsedRatio>
    <storageUsed>0</storageUsed>
    <dbName>dbv4h25r</dbName>
    <hostName>dbv4h25r.mariadb.routing.zone</hostName>
    <dbEngine>MariaDB</dbEngine>
    <dbType>single</dbType>
    <forceSsl>false</forceSsl>
    <limitations/>
    <restrictions/>
 </response>
</response>

Request	databaseUpdate
Url	https://secure.hosting.de/api/database/v1/jsonxml/databaseUpdate
Processing	asynchronous
Response	Database

Parameter	Type	Required	Description
database	Database object	req	Complete `database` object
accesses	list <databaseAccess object>	req	List of user authorizations with access to `database` (list may be empty)

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

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

Deleting Databases

POST https://secure.hosting.de/api/database/v1/jsonxml/databaseDelete

{
    "authToken": "$$YOUR API KEY$$",
    "databaseId": "15010100000094"
}

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

Response

{
    ...
    "response": {
        "accesses": [
            {
                "addDate": "2016-03-14T09:11:24Z",
                "lastChangeDate": "2016-03-14T09:11:24Z",
                "accessLevel": [ "read", "write", "schema" ],
                "userId": "15010100000091",
                "userName": "dbv4h25r_ayapzk",
                "databaseId": "15010100000094"
            }
        ],
        "bundleId": null,
        "poolId": null,
        "accountId": "15010100000001",
        "addDate": "2016-03-14T09:11:24Z",
        "paidUntil": "2016-04-14T09:11:24Z",
        "renewOn": "2016-04-14T09:11:24Z",
        "deletionScheduledFor": null,
        "id": "15010100000094",
        "lastChangeDate": "2016-03-14T09:11:24Z",
        "name": "Example",
        "productCode": "database-mariadb-single-v1-12m",
        "restorableUntil": null,
        "status": "creating",
        "storageQuota": 512,
        "storageQuotaIncluded": 512,
        "storageQuotaUsedRatio": 0,
        "storageUsed": 0,
        "dbName": "dbv4h25r",
        "hostName": "dbv4h25r.mariadb.routing.zone",
        "dbEngine": "MariaDB",
        "dbType": "single",
        "forceSsl": false,
        "restrictions": [],
        "limitations": []
    },
    ...
}

<response>
 <response>
    <accesses>
        <item>
            <addDate>2016-03-14T09:11:24Z</addDate>
            <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
            <accessLevel>
                <item>read</item>
                <item>write</item>
                <item>schema</item>
            </accessLevel>
            <userId>15010100000091</userId>
            <dbLogin>dbv4h25r_ayapzk</dbLogin>
            <databaseId>15010100000094</databaseId>
        </item>
    </accesses>
    <bundleId></bundleId>
    <poolId></poolId>
    <accountId>1</accountId>
    <addDate>2016-03-14T09:11:24Z</addDate>
    <paidUntil>2016-04-14T09:11:24Z</paidUntil>
    <renewOn>2016-04-14T09:11:24Z</renewOn>
    <deletionScheduledFor></deletionScheduledFor>
    <id>15010100000094</id>
    <lastChangeDate>2016-03-14T09:11:24Z</lastChangeDate>
    <name>Example</name>
    <productCode>database-mariadb-single-v1-12m</productCode>
    <restorableUntil></restorableUntil>
    <status>creating</status>
    <storageQuota>512</storageQuota>
    <storageQuotaIncluded>512</storageQuotaIncluded>
    <storageQuotaUsedRatio>0</storageQuotaUsedRatio>
    <storageUsed>0</storageUsed>
    <dbName>dbv4h25r</dbName>
    <hostName>dbv4h25r.mariadb.routing.zone</hostName>
    <dbEngine>MariaDB</dbEngine>
    <dbType>single</dbType>
    <forceSsl>false</forceSsl>
    <limitations/>
    <restrictions/>
 </response>
</response>

Request	databaseDelete
Url	https://secure.hosting.de/api/database/v1/jsonxml/databaseDelete
Processing	asynchronous
Response	Database

Parameter	Type	Required	Description
databaseId	string	req	ID of database to be deleted

Mailboxes

The email section of the API allows you to create and manage mailboxes.

Currently six types of mailboxes are available in the system: ImapMailbox, Forwarder, SmtpForwarder, MailingList and Catchall. First section of the documentation describes the objects that represent each of these types of mailboxes in detail. How to create and manage existing mailboxes is explained in the following sections.

ImapMailbox

The ImapMailbox Object

{
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "bundleId": "",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "status": "active",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "type": "ImapMailbox",
	"productCode": "email-imap-mailbox-12m",
    "forwarderTargets": [],
    "smtpForwarderTarget": "",
    "isAdmin": false,
    "storageQuota": 1024,
    "storageQuotaUsed": 0,
    "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"
}

<Mailbox>
 <id>150101aaaaaaaaaa001</id>
 <accountId>15010100000001</accountId>
 <bundleId></bundleId>
 <emailAddress>testmailbox@example.com</emailAddress>
 <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
 <domainName>example.com</domainName>
 <domainNameUnicode>example.com</domainNameUnicode>
 <status>active</status>
 <spamFilter>
  <bannedFilesChecks>false</bannedFilesChecks>
  <deleteSpam>false</deleteSpam>
  <headerChecks>false</headerChecks>
  <malwareChecks>false</malwareChecks>
  <modifySubjectOnSpam>true</modifySubjectOnSpam>
  <spamChecks>false</spamChecks>
  <spamLevel>low</spamLevel>
  <useGreylisting>true</useGreylisting>
 </spamFilter>
 <type>ImapMailbox</type>
 <productCode>email-imap-mailbox-12m</productCode>
 <forwarderTargets/>
 <smtpForwarderTarget></smtpForwarderTarget>
 <isAdmin>false</isAdmin>
 <storageQuota>1024</storageQuota>
 <storageQuotaUsed>0</storageQuotaUsed>
 <paidUntil>2016-02-01T15:57:35Z</paidUntil>
 <renewOn>2016-01-31T15:57:35Z</renewOn>
 <deletionScheduledFor xsi:nil="true"/>
 <restorableUntil xsi:nil="true"/>
 <addDate>2016-01-01T15:57:35Z</addDate>
 <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
</Mailbox>

Property	Type	Required / Direction	Description
type	string	fixed	Type of the mailbox. For imap mailbox it must always be “ImapMailbox”.
productCode	string	fixed	Contains the productCode of the mailbox and must be set at creation.
accountId	string	out-only	ID of managing account
bundleId	string	optional	ID of the bundle which handles contractual obligations.
id	string	see description	ID of this mailbox. Ignored in mailboxCreate requests. This property is required in all other requests regarding mailbox management.
emailAddress	string	required	Email address of the mailbox in ASCII/ACE format.
emailAddressUnicode	string	out-only	Email address of the mailbox in Unicode/international format.
domainName	string	out-only	Domain name of the mailbox in ASCII/ACE format.
domainNameUnicode	string	out-only	Domain name of the mailbox in Unicode/international format.
status	string	out-only	Status of the mailbox.
spamFilter	SpamFilter	optional	Spam settings of the mailbox.
autoResponder	AutoResponder	optional	AutoResponder settings of this mailbox.
forwarderTargets	list	required	List of email addresses mails are forwarded to in addition to delivery to this imap mailbox.
isAdmin	bool	optional	Indicates whether the mailbox has admin rights. Mailboxes with admin rights can create and manage other mailboxes in the same domain.
storageQuota	int	required	Mailbox storage capacity in MB.
storageQuotaUsed	int	out-only	Currently used storage of the mailbox in MB.
deletionScheduledFor	datetime	out-only	Date and time the mailbox is scheduled for deletion. Is empty if mailbox is not scheduled for removal.
restorableUntil	datetime	out-only	Date and Time before which the mailbox can be restored.
paidUntil	datetime	out-only	Date that the mailbox 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 mailbox was created in the system.
lastChangeDate	datetime	out-only	Date and time of last mailbox modification

Creating ImapMailboxes

POST https://secure.hosting.de/api/email/v1/jsonxml/mailboxCreate

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailbox": {
        "type": "ImapMailbox",
		"productCode": "email-imap-mailbox-12m",
        "emailAddress": "testmailbox@example.com",
        "storageQuota": 1024,
        "isAdmin": false
    },
    "password": "!Secret23"
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailbox>
  <type>ImapMailbox</type>
  <productCode>email-imap-mailbox-12m</productCode>
  <emailAddress>testmailbox@example.com</emailAddress>
  <storageQuota>1024</storageQuota>
  <isAdmin>false</isAdmin>
 </mailbox>
 <password>!Secret23</password>
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "bundleId": "",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "status": "creating",
    "type": "ImapMailbox",
	"productCode": "email-imap-mailbox-12m",
    "forwarderTargets": [],
    "smtpForwarderTarget": "",
    "isAdmin": false,
    "storageQuota": 1024,
    "storageQuotaUsed": 0,
    "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>
   <bundleId></bundleId>
   <emailAddress>testmailbox@example.com</emailAddress>
   <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   <status>creating</status>
   <type>ImapMailbox</type>
   <productCode>email-imap-mailbox-12m</productCode>
   <forwarderTargets/>
   <smtpForwarderTarget></smtpForwarderTarget>
   <isAdmin>false</isAdmin>
   <storageQuota>1024</storageQuota>
   <storageQuotaUsed>0</storageQuotaUsed>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil xsi:nil="true"/>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>

Request	mailboxCreate
Url	https://secure.hosting.de/api/email/v1/jsonxml/mailboxCreate
Processing	asynchronous
Response	ImapMailbox object

Parameter	Type	Required	Description
mailbox	ImapMailbox object	req	Data for to be created imap mailbox
password	string	req	Password for this mailbox

In order to create an imap mailbox, you need to send a mailboxCreate request. This request takes as first parameter mailbox which contains all required information of the mailbox and as second parameter a password. Please note that in order to create an imap mailbox the type parameter of the mailbox must be ImapMailbox and all required properties of the ImapMailbox object must be set. object

Forwarder

The Forwarder Object

{
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "bundleId": "",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "status": "active",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "type": "Forwarder",
    "forwarderType": "externalForwarder",
	"productCode": "email-forwarder-external-12m",
    "forwarderTargets": [
        "internal_target@example.com",
        "external_target@testdomain.com"
    ],
    "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"
}

<Mailbox>
 <id>150101aaaaaaaaaa001</id>
 <accountId>15010100000001</accountId>
 <bundleId></bundleId>
 <emailAddress>testmailbox@example.com</emailAddress>
 <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
 <domainName>example.com</domainName>
 <domainNameUnicode>example.com</domainNameUnicode>
 <status>active</status>
 <spamFilter>
  <bannedFilesChecks>false</bannedFilesChecks>
  <deleteSpam>false</deleteSpam>
  <headerChecks>false</headerChecks>
  <malwareChecks>false</malwareChecks>
  <modifySubjectOnSpam>true</modifySubjectOnSpam>
  <spamChecks>false</spamChecks>
  <spamLevel>low</spamLevel>
  <useGreylisting>true</useGreylisting>
 </spamFilter>
 <type>Forwarder</type>
 <productCode>email-forwarder-external-12m</productCode>
 <forwarderType>externalForwarder</forwarderType>
 <forwarderTargets>
  <item>internal_target@example.com</item>
  <item>external_target@testdomain.com</item>
 </forwarderTargets>
 <paidUntil>2016-02-01T15:57:35Z</paidUntil>
 <renewOn>2016-01-31T15:57:35Z</renewOn>
 <deletionScheduledFor xsi:nil="true"/>
 <restorableUntil xsi:nil="true"/>
 <addDate>2016-01-01T15:57:35Z</addDate>
 <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
</Mailbox>

Property	Type	Required / Direction	Description
type	string	fixed	Type of the mailbox. For forwarder mailbox it must always be “Forwarder”.
productCode	string	fixed	Contains the productCode of the mailbox and must be set at creation.
accountId	string	out-only	ID of managing account
bundleId	string	optional	ID of the bundle which handles contractual obligations.
id	string	see description	ID of this mailbox. Ignored in mailboxCreate requests. This property is required in all other requests regarding mailbox management.
emailAddress	string	required	Email address of the mailbox in ASCII/ACE format.
emailAddressUnicode	string	out-only	Email address of the mailbox in Unicode/international format.
domainName	string	out-only	Domain name of the mailbox in ASCII/ACE format.
domainNameUnicode	string	out-only	Domain name of the mailbox in Unicode/international format.
status	string	out-only	Status of the mailbox.
spamFilter	SpamFilter	optional	Spam settings of the mailbox.
autoResponder	AutoResponder	optional	AutoResponder settings of this mailbox.
forwarderType	string	out-only	Type of the forwarder. The type of the forwarder can be either `internalForwarder` or `externalForwarder`. If all email addresses in the forwarderTargets list are in the same domain as the forwarder then the forwarderType will be `internalForwarder`. Otherwise it will be `externalForwarder`.
forwarderTargets	list	required	List of email addresses mails are forwarded to.
deletionScheduledFor	datetime	out-only	Date and time the mailbox is scheduled for deletion. Is empty if mailbox is not scheduled for removal.
restorableUntil	datetime	out-only	Date and Time before which the mailbox can be restored.
paidUntil	datetime	out-only	Date that the mailbox 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 mailbox was created in the system.
lastChangeDate	datetime	out-only	Date and time of last mailbox modification

Creating Forwarders

POST https://secure.hosting.de/api/email/v1/jsonxml/mailboxCreate

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailbox": {
        "type": "Forwarder",
		"productCode": "email-forwarder-external-12m",
        "emailAddress": "testmailbox@example.com",
        "forwarderTargets": [
            "internal_target@example.com",
            "external_target@testdomain.com"
        ]
    }
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailbox>
  <type>Forwarder</type>
  <productCode>email-forwarder-external-12m</productCode>
  <emailAddress>testmailbox@example.com</emailAddress>
  <forwarderTargets>
   <item>internal_target@example.com</item>
   <item>external_target@testdomain.com</item>
  </forwarderTargets>
 </mailbox>
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "bundleId": "",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "status": "creating",
    "type": "Forwarder",
    "productCode": "email-forwarder-external-12m",
    "forwarderType": "externalForwarder",
    "forwarderTargets": [
        "internal_target@example.com",
        "external_target@testdomain.com"
    ],
    "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>
   <bundleId></bundleId>
   <emailAddress>testmailbox@example.com</emailAddress>
   <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   <status>creating</status>
   <type>Forwarder</type>
   <productCode>email-forwarder-external-12m</productCode>
   <forwarderType>externalForwarder</forwarderType>
   <forwarderTargets>
    <item>internal_target@example.com</item>
    <item>external_target@testdomain.com</item>
   </forwarderTargets>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil xsi:nil="true"/>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>

Request	mailboxCreate
Url	https://secure.hosting.de/api/email/v1/jsonxml/mailboxCreate
Processing	asynchronous
Response	Forwarder object

Parameter	Type	Required	Description
mailbox	Forwarder object	req	Data for to be created forwarder

In order to create a forwarder, you need to send a mailboxCreate request. This request takes one parameter mailbox which contains all required information of the mailbox to be created. Please note that in order to create an forwarder mailbox the type parameter of the mailbox must be Forwarder and all required properties of the Forwarder object must be set.

SmtpForwarder

An SMTP Forwarder can be used to forward emails by SMTP to a target mailserver. It will be delivered on Port 25 with the SMTP protocol. The target mailserver must accept emails for the created email address. An SMTP Forwarder is useful if you want to forward emails to your local exchange server or if you want to use just our spamfiltering.

The SmtpForwarder Object

{
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "bundleId": "",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "status": "active",
    "type": "SmtpForwarder",
    "productCode": "email-smtp-forwarder-v1-12m",
    "server": "your.mailserver.hostname",
    "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"
}

<Mailbox>
   <id>150101aaaaaaaaaa001</id>
   <accountId>15010100000001</accountId>
   <bundleId></bundleId>
   <emailAddress>testmailbox@example.com</emailAddress>
   <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   <status>active</status>
   <type>SmtpForwarder</type>
   <productCode>email-smtp-forwarder-v1-12m</productCode>
   <server>your.mailserver.hostname</server>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil xsi:nil="true"/>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
</Mailbox>

Property	Type	Required / Direction	Description
type	string	fixed	Type of the mailbox. For SMTP Forwarder mailbox it must always be “SmtpForwarder”.
productCode	string	fixed	Contains the productCode of the mailbox and must be set at creation.
accountId	string	out-only	ID of managing account
bundleId	string	optional	ID of the bundle which handles contractual obligations.
id	string	see description	ID of this mailbox. Ignored in mailboxCreate requests. This property is required in all other requests regarding mailbox management.
emailAddress	string	required	Email address of the mailbox in ASCII/ACE format.
emailAddressUnicode	string	out-only	Email address of the mailbox in Unicode/international format.
domainName	string	out-only	Domain name of the mailbox in ASCII/ACE format.
domainNameUnicode	string	out-only	Domain name of the mailbox in Unicode/international format.
status	string	out-only	Status of the mailbox.
spamFilter	SpamFilter	optional	Spam settings of the mailbox.
autoResponder	AutoResponder	optional	AutoResponder settings of this mailbox.
server	string	required	FQDN or IP address of the server to which emails are forwarded.
port	int	optional	The server port, default is 25.
deletionScheduledFor	datetime	out-only	Date and time the mailbox is scheduled for deletion. Is empty if mailbox is not scheduled for removal.
restorableUntil	datetime	out-only	Date and Time before which the mailbox can be restored.
paidUntil	datetime	out-only	Date that the mailbox 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 mailbox was created in the system.
lastChangeDate	datetime	out-only	Date and time of last mailbox modification

Creating SMTP Forwarder

POST https://secure.hosting.de/api/email/v1/jsonxml/mailboxCreate

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailbox": {
        "type": "SmtpForwarder",
		"productCode": "email-smtp-forwarder-v1-12m",
        "emailAddress": "testmailbox@example.com",
        "server": "your.mailserver.hostname"
    }
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailbox>
  <type>SmtpForwarder</type>
  <productCode>email-smtp-forwarder-v1-12m</productCode>
  <emailAddress>testmailbox@example.com</emailAddress>
  <server>your.mailserver.hostname</server>
 </mailbox>
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "bundleId": "",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "status": "creating",
    "type": "SmtpForwarder",
    "productCode": "email-smtp-forwarder-v1-12m",
    "server": "your.mailserver.hostname",
    "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>
   <bundleId></bundleId>
   <emailAddress>testmailbox@example.com</emailAddress>
   <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   <status>creating</status>
   <type>SmtpForwarder</type>
   <productCode>email-smtp-forwarder-v1-12m</productCode>
   <server>your.mailserver.hostname</server>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil xsi:nil="true"/>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>

Request	mailboxCreate
Url	https://secure.hosting.de/api/email/v1/jsonxml/mailboxCreate
Processing	asynchronous
Response	SmtpForwarder object

Parameter	Type	Required	Description
mailbox	SMTP Forwarder object	req	Data for to be created smtpForwarder

In order to create an SMTP Forwarder, you need to send a mailboxCreate request. This request takes one parameter mailbox which contains all required information of the mailbox to be created. Please note that in order to create an SMTP Forwarder mailbox the type parameter of the mailbox must be SmtpForwarder and all required properties of the SmtpForwarder object must be set.

MailingList

The MailingList Object

{
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "bundleId": "",
    "emailAddress": "testlist@example.com",
    "emailAddressUnicode": "testlist@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "status": "active",
    "type": "MailingList",
    "productCode": "email-mailinglist-team-v1-12m",
    "name": "Test Mailinglist",
    "accessMode": "everyone",
    "replyToMode": "list",
    "owners": [
      "ownerlist@example.com"
    ],
    "members": [
      "internal_member@example.com",
      "external_member@testdomain.com"
    ],
    "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"
}

<Mailbox>
   <id>150101aaaaaaaaaa001</id>
   <accountId>15010100000001</accountId>
   <bundleId></bundleId>
   <emailAddress>testlist@example.com</emailAddress>
   <emailAddressUnicode>testlist@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   <status>active</status>
   <type>MailingList</type>
   <productCode>email-mailinglist-team-v1-12m</productCode>
   <name>Test Mailinglist</name>
   <accessMode>everyone</accessMode>
   <replyToMode>list</replyToMode>
   <owners>
    <item>ownerlist@example.com</item>
   </owners>
   <members>
    <item>internal_member@example.com</item>
    <item>external_member@testdomain.com</item>
   </members>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil xsi:nil="true"/>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
</Mailbox>

Property	Type	Required / Direction	Description
type	string	fixed	Type of the mailbox. For a mailinglist it must always be “MailingList”.
productCode	string	fixed	Contains the productCode of the mailbox and must be set at creation.
accountId	string	out-only	ID of managing account
bundleId	string	optional	ID of the bundle which handles contractual obligations.
id	string	see description	ID of this mailbox. Ignored in mailboxCreate requests. This property is required in all other requests regarding mailbox management.
emailAddress	string	required	Email address of the mailbox in ASCII/ACE format.
emailAddressUnicode	string	out-only	Email address of the mailbox in Unicode/international format.
domainName	string	out-only	Domain name of the mailbox in ASCII/ACE format.
domainNameUnicode	string	out-only	Domain name of the mailbox in Unicode/international format.
status	string	out-only	Status of the mailbox.
spamFilter	SpamFilter	optional	Spam settings of the mailbox.
autoResponder	AutoResponder	optional	AutoResponder settings of this mailbox.
name	string	required	Name of the mailinglist.
subjectPrefix	string	optional	This prefix, if set, will be added to the subject of any email sent to this mailinglist.
accessMode	string	required	Controls who is allowed to send emails to this mailinglist.
replyToMode	string	required	Controls the reply-to header of emails coming from this mailinglist.
replyToEmailAddress	string	optional	If set, this email address will override the reply-to header of emails coming from this mailinglist.
allowHtmlMails	bool	optional	If set to false, HTML emails will be rejected. Default is true.
digestSize	int	optional	Controls the maximum digest size of this mailinglist. Default is 0 which deactivates digest function.
owners	list	required	Email addresses of the owners of this mailinglist.
members	list	optional	Email addresses of the members of this mailinglist.
deletionScheduledFor	datetime	out-only	Date and time the mailbox is scheduled for deletion. Is empty if mailbox is not scheduled for removal.
restorableUntil	datetime	out-only	Date and Time before which the mailbox can be restored.
paidUntil	datetime	out-only	Date that the mailbox 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 mailbox was created in the system.
lastChangeDate	datetime	out-only	Date and time of last mailbox modification

Creating MailingList

POST https://secure.hosting.de/api/email/v1/jsonxml/mailboxCreate

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailbox": {
        "type": "MailingList",
		"productCode": "email-mailinglist-team-v1-12m",
        "emailAddress": "testlist@example.com",
        "name": "Test Mailinglist",
        "accessMode": "everyone",
        "replyToMode": "list",
        "owners": [
            "ownerlist@example.com"
        ],
        "members": [
            "internal_member@example.com",
            "external_member@testdomain.com"
        ]
    }
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailbox>
  <type>MailingList</type>
  <productCode>email-mailinglist-team-v1-12m</productCode>
  <emailAddress>testlist@example.com</emailAddress>
  <name>Test Mailinglist</name>
  <accessMode>everyone</accessMode>
  <replyToMode>list</replyToMode>
  <owners>
   <item>ownerlist@example.com</item>
  </owners>
  <members>
   <item>internal_member@example.com</item>
   <item>external_member@testdomain.com</item>
  </members>
 </mailbox>
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "bundleId": "",
    "emailAddress": "testlist@example.com",
    "emailAddressUnicode": "testlist@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "status": "creating",
    "type": "MailingList",
    "productCode": "email-mailinglist-team-v1-12m",
    "name": "Test Mailinglist",
    "accessMode": "everyone",
    "replyToMode": "list",
    "owners": [
      "ownerlist@example.com"
    ],
    "members": [
      "internal_member@example.com",
      "external_member@testdomain.com"
    ],
    "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>
   <bundleId></bundleId>
   <emailAddress>testlist@example.com</emailAddress>
   <emailAddressUnicode>testlist@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   <status>creating</status>
   <type>MailingList</type>
   <productCode>email-mailinglist-team-v1-12m</productCode>
   <name>Test Mailinglist</name>
   <accessMode>everyone</accessMode>
   <replyToMode>list</replyToMode>
   <owners>
    <item>ownerlist@example.com</item>
   </owners>
   <members>
    <item>internal_member@example.com</item>
    <item>external_member@testdomain.com</item>
   </members>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil xsi:nil="true"/>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>

Request	mailboxCreate
Url	https://secure.hosting.de/api/email/v1/jsonxml/mailboxCreate
Processing	asynchronous
Response	MailingList object

Parameter	Type	Required	Description
mailbox	MailingList object	req	Data for to be created mailinglist

In order to create a mailinglist, you need to send a mailboxCreate request. This request takes one parameter mailbox which contains all required information of the mailbox to be created. Please note that in order to create a mailinglist mailbox the type parameter of the mailbox must be MailingList and all required properties of the MailingList object must be set.

Valid Modes for accessMode are:

owners: Only the email addresses defined in owners are allowed to send emails to this mailinglist. Other emails will be silently discarded.
members: Only the email addresses defined in owners and members are allowed to send emails to this mailinglist. Other emails will be silently discarded.
everyone: Everyone may send emails to this mailinglist.

Valid Modes for replyToMode are:

list: The reply-to header will be set to the email address of the mailinglist.
self: The reply-to header will be set to the original sender of the email address.

Catchall

With a catchall mailbox one can create a wildcard email address for a domain name. All emails sent to non existing mailboxes of that domain will be forwarded to a specified IMAP mailbox.

The Catchall Object

{
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "bundleId": "",
    "emailAddress": "catchall@example.com",
    "emailAddressUnicode": "catchall@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "status": "active",
    "type": "Catchall",
    "productCode": "email-catchall-12m",
    "forwarderTarget": "internal_mailbox@example.com",
    "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"
}

<Mailbox>
   <id>150101aaaaaaaaaa001</id>
   <accountId>15010100000001</accountId>
   <bundleId></bundleId>
   <emailAddress>catchall@example.com</emailAddress>
   <emailAddressUnicode>catchall@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   <status>active</status>
   <type>Catchall</type>
   <productCode>email-catchall-12m</productCode>
   <forwarderTarget>internal_mailbox@example.com</forwarderTarget>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil xsi:nil="true"/>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
</Mailbox>

Property	Type	Required / Direction	Description
type	string	fixed	Type of the mailbox. For catchall mailbox it must always be “Catchall”.
productCode	string	fixed	Contains the productCode of the mailbox and must be set at creation.
accountId	string	out-only	ID of managing account
bundleId	string	optional	ID of the bundle in which the mailbox should be created.
id	string	see description	ID of this mailbox. Ignored in mailboxCreate requests. This property is required in all other requests regarding mailbox management.
emailAddress	string	required	Email address of the mailbox in ASCII/ACE format. This property must contain “” as prefix before the @, e.g. @example.com.net.
emailAddressUnicode	string	out-only	Email address of the mailbox in Unicode/international format.
domainName	string	out-only	Domain name of the mailbox in ASCII/ACE format.
domainNameUnicode	string	out-only	Domain name of the mailbox in Unicode/international format.
status	string	out-only	Status of the mailbox.
spamFilter	SpamFilter	optional	Spam settings of the mailbox.
autoResponder	AutoResponder	optional	AutoResponder settings of this mailbox.
forwarderTarget	string	required	Receiving mailbox of this catchall mailbox. Must be an IMAP mailbox without any further forwarders.
deletionScheduledFor	datetime	out-only	Date and time the mailbox is scheduled for deletion. Is empty if mailbox is not scheduled for removal.
restorableUntil	datetime	out-only	Date and Time before which the mailbox can be restored.
paidUntil	datetime	out-only	Date that the mailbox 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 mailbox was created in the system.
lastChangeDate	datetime	out-only	Date and time of last mailbox modification

Creating Catchall

POST https://secure.hosting.de/api/email/v1/jsonxml/mailboxCreate

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailbox": {
        "type": "Catchall",
		"productCode": "email-catchall-12m",
        "emailAddress": "*@example.com",
        "forwarderTargets": "internal_mailbox@example.com"
    }
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailbox>
  <type>Catchall</type>
  <productCode>email-catchall-12m</productCode>
  <emailAddress>*@example.com</emailAddress>
  <forwarderTarget>internal_mailbox@example.com</forwarderTarget>
 </mailbox>
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "bundleId": "",
    "emailAddress": "*@example.com",
    "emailAddressUnicode": "*@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "status": "creating",
    "type": "Catchall",
    "productCode": "email-catchall-12m",
    "forwarderTarget": "internal_mailbox@example.com",
    "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>
   <bundleId></bundleId>
   <emailAddress>*@example.com</emailAddress>
   <emailAddressUnicode>*@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   <status>creating</status>
   <type>Catchall</type>
   <productCode>email-catchall-12m</productCode>
   <forwarderTarget>internal_mailbox@example.com</forwarderTarget>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil xsi:nil="true"/>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>

Request	mailboxCreate
Url	https://secure.hosting.de/api/email/v1/jsonxml/mailboxCreate
Processing	asynchronous
Response	Catchall object

Parameter	Type	Required	Description
mailbox	Catchall object	req	Data for to be created catchall

In order to create a catchall, you need to send a mailboxCreate request. This request takes one parameter mailbox which contains all required information of the mailbox to be created. Please note that in order to create a catchall mailbox the type parameter of the mailbox must be Catchall and all required properties of the Catchall object must be set.

Spam filtering settings

The SpamFilter Object

{
    "bannedFilesChecks": false,
    "deleteSpam": false,
    "headerChecks": false,
    "malwareChecks": false,
    "modifySubjectOnSpam": true,
    "spamChecks": false,
    "spamLevel": "low",
    "useGreylisting": true
}

<spamFilter>
 <bannedFilesChecks>false</bannedFilesChecks>
 <deleteSpam>false</deleteSpam>
 <headerChecks>false</headerChecks>
 <malwareChecks>false</malwareChecks>
 <modifySubjectOnSpam>true</modifySubjectOnSpam>
 <spamChecks>false</spamChecks>
 <spamLevel>low</spamLevel>
 <useGreylisting>true</useGreylisting>
</spamFilter>

Property	Type	Required / Direction	Description
bannedFilesChecks	bool	optional	Will reject mails with potentially dangerous attachments (like .exe files).
deleteSpam	bool	optional	Reject spam mails
headerChecks	bool	optional	The email headers will be checked for unusual patterns.
malwareChecks	bool	optional	This option enables the scanning of content and attachments of emails for malware and viruses.
modifySubjectOnSpam	bool	optional	Will modify the subject to mark a recognized spam email as such.
spamChecks	bool	optional	The content of emails will be compared against a spam database and will mark the Subject if required (see modifySubjectOnSpam).
spamLevel	string	optional	The levels indicate how many spam factors are taken into account when an email arrives. Valid values: `low`, `medium`. `high`
useGreylisting	bool	optional	Greylisting will delay the acceptance of emails, allowing significantly better recognition of spam.

AutoResponder settings

The AutoResponder Object

{
    "subject": "Out of office",
    "body": "Dear sender, I am out of office.",
    "start": "2016-01-01T15:57:35Z",
    "end": "2016-12-31T15:57:35Z",
    "active": true,
    "enabled": true
}

<autoResponder>
 <subject>Out of office</subject>
 <body>Dear sender, I am out of office.</body>
 <start>2016-12-31T15:57:35Z</start>
 <end>2016-12-31T15:57:35Z</end>
 <active>true</active>
 <enabled>true</enabled>
</autoResponder>

Property	Type	Required / Direction	Description
subject	string	optional	The subject of the autoresponded email.
body	string	optional	The email body of the autoresponded email.
start	datetime	optional	A time on which the autoresponder will become active.
end	datetime	optional	A time on which the autoresponder will deactivated automatically.
active	bool	optional	True when the autoresponder is currently active and sending replies.
enabled	bool	optional	Enable this autoresponder. This option is independent from start and end dates.

Updating Mailboxes

POST https://secure.hosting.de/api/email/v1/jsonxml/mailboxUpdate

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailbox": {
        "id": "150101aaaaaaaaaa001",
        "type": "ImapMailbox",
        "emailAddress": "testmailbox@example.com",
        "storageQuota": 1024,
        "isAdmin": false
    },
    "password": "!Secret23"
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailbox>
  <id>150101aaaaaaaaaa001</id>
  <emailAddress>testmailbox@example.com</emailAddress>
  <storageQuota>1024</storageQuota>
  <type>ImapMailbox</type>
  <isAdmin>false</isAdmin>
 </mailbox>
 <password>!Secret23</password>
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "bundleId": "",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "status": "active",
    "type": "ImapMailbox",
    "forwarderTargets": [],
    "smtpForwarderTarget": "",
    "isAdmin": false,
    "storageQuota": 1024,
    "storageQuotaUsed": 0,
    "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>
   <emailAddress>testmailbox@example.com</emailAddress>
   <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   <status>active</status>
   <type>ImapMailbox</type>
   <forwarderTargets/>
   <smtpForwarderTarget></smtpForwarderTarget>
   <isAdmin>false</isAdmin>
   <storageQuota>1024</storageQuota>
   <storageQuotaUsed>0</storageQuotaUsed>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil xsi:nil="true"/>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>

Request	mailboxUpdate
Url	https://secure.hosting.de/api/email/v1/jsonxml/mailboxUpdate
Processing	asynchronous
Response	ImapMailbox, Forwarder, SmtpForwarder, MailingList or Catchall object

Parameter	Type	Required	Description
mailbox	ImapMailbox, Forwarder, SmtpForwarder, MailingList or Catchall	req	Complete mailbox object of the same type as the mailbox to update.
password	string	opt	Password for this mailbox

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

The parameter password will only be accepted for ImapMailbox objects.

Listing Mailboxes

POST https://secure.hosting.de/api/email/v1/jsonxml/Find

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "MailboxEmailAddress",
        "value": "testmailbox@example.com"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "MailboxEmailAddress",
        "order": "asc"
    }
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <field>MailboxEmailAddress</field>
  <value>testmailbox@example.com</value>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>MailboxEmailAddress</field>
  <order>asc</order>
 </sort>
</request>

Response

{
    ...
    "response": {
        "data": [
            // Mailbox objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindMailboxesResult"
    },
    ...
}

<response>
 <response>
  <data>
   ...
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindMailboxesResult</type>
 </response>
 ...
</response>

Request	mailboxesFind
Url	https://secure.hosting.de/api/email/v1/jsonxml/mailboxesFind
Processing	synchronous
Response	FindMailboxesResult

Listing mailboxes uses the generic filtering and sorting API with the method mailboxesFind. The response will contain a list of mailbox objects.

The following fields are available for filtering and sorting:

Field	Description
AccountId	ID of account managing the mailbox
MailboxId	ID of mailbox
MailboxEmailAddress	Email address of the mailbox
MailboxEmailAddressUnicode	Email address of the mailbox in Unicode-Form
MailboxDomainName	Domain name of the mailbox
MailboxDomainNameUnicode	Domain name of the mailbox in Unicode-Form
MailboxType	Type of the mailbox
MailboxStatus	Status of the mailbox
MailboxStorageQuota	Mailbox storage capacity
MailboxStorageQuotaUsed	Currently used storage of the mailbox
MailboxDeletionScheduledFor	Deletion date and time of the mailbox
MailboxRestorableUntil	Date and Time until mailbox can be restored
MailboxPaidUntil	Time that the mailbox is paid for
MailboxRenewOn	Date and Time of next automatic renewal (and payment)
MailboxAddDate	Date and time mailbox was created
MailboxLastChangeDate	Date and time of last modification

Deleting Mailboxes

POST https://secure.hosting.de/api/email/v1/jsonxml/mailboxDelete

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailboxId": "150101aaaaaaaaaa001",
    "execDate": "2016-01-15T12:00:00Z"
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailboxId>150101aaaaaaaaaa001</mailboxId>
 <execDate>2016-01-15T12:00:00Z</execDate>
</request>

Response

{
  ...
  "status": "pending"
}

<response>
 <response>  
   <status>pending</status>
 ...
</response>

Request	mailboxDelete
Url	https://secure.hosting.de/api/email/v1/jsonxml/mailboxDelete
Processing	asynchronous
Response	none

Parameter	Type	Required	Description
mailboxId	string	see description	Id of the mailbox
emailAddress	string	see description	Email address of the meilbox
execDate	datetime	optional	Scheduled deletion date

This method deletes a mailbox. To delete a mailbox you must specify either the id of the mailbox or its email address, but not both.

A deleted mailbox can be restored within the restore period with the mailboxRestore API method. If the mailbox will not be restored within the restore period it will be removed from the system.

If you also specify an execDate, it will be scheduled for deletion on execDate. This will set the mailbox object’s and deletionDate. A scheduled deletion can be canceled with the mailboxDeletionCancel API method.

Canceling Deletion of Mailboxes

POST https://secure.hosting.de/api/email/v1/jsonxml/mailboxDeletionCancel

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailboxId": "150101aaaaaaaaaa001"
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailboxId>150101aaaaaaaaaa001</mailboxId>
</request>

Request	mailboxDeletionCancel
Url	https://secure.hosting.de/api/email/v1/jsonxml/mailboxDeletionCancel
Processing	synchronous
Response	Mailbox object

Parameter	Type	Required	Description
mailboxId	string	see description	Id of the mailbox
emailAddress	string	see description	Email address of the mailbox

This method cancels a scheduled deletion for a mailbox. To cancel a deletion of a mailbox you must specify either the id of the mailbox or its email address, but not both.

Restoring Mailboxes

POST https://secure.hosting.de/api/email/v1/jsonxml/mailboxRestore

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailboxId": "150101aaaaaaaaaa001"
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailboxId>150101aaaaaaaaaa001</mailboxId>
</request>

Response

{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    //mailbox type specific properties
    "status": "restorable",
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,
    "restorableUntil": "2016-01-22T12:00:00Z",
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-15T12:00:00Z"
  }
}

<response>
 <response>
  <response>
   <id>150101aaaaaaaaaa001</id>
   <accountId>15010100000001</accountId>
   <emailAddress>testmailbox@example.com</emailAddress>
   <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   ...mailbox type specific properties
   <status>restorable</status>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil>2016-01-22T12:00:00Z</restorableUntil>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-15T12:00:00Z</lastChangeDate>
  </response>
 </response>
 ...
</response>

Request	mailboxRestore
Url	https://secure.hosting.de/api/email/v1/jsonxml/mailboxRestore
Processing	asynchronous
Response	Mailbox object

Parameter	Type	Required	Description
mailboxId	string	see description	Id of the mailbox
emailAddress	string	see description	Email address of the mailbox

This method restores a previously deleted mailbox. After the mailbox is restored it can be used normally. To restore a mailbox you must specify either the id of the mailbox or its email address, but not both.

Purging Restorable Mailboxes

POST https://secure.hosting.de/api/email/v1/jsonxml/mailboxPurgeRestorable

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailboxId": "150101aaaaaaaaaa001"
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailboxId>150101aaaaaaaaaa001</mailboxId>
</request>

Response

{
  ...
  "status": "pending"
}

<response>
 <response>  
   <status>pending</status>
 ...
</response>

Request	mailboxPurgeRestorable
Url	https://secure.hosting.de/api/email/v1/jsonxml/mailboxPurgeRestorable
Processing	asynchronous
Response	none

Parameter	Type	Required	Description
mailboxId	string	see description	id of the mailbox
emailAddress	string	see description	email address of the mailbox

This method deletes a restorable mailbox immediately from the system. You will not be able to restore it afterwards. To use this method you must specify either the id of the mailbox or its email address, but not both.

Checking Mailbox Authorization

POST https://secure.hosting.de/api/email/v1/jsonxml/checkEmailAddress

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "emailAddress": "testmailbox@example.com"
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <emailAddress>testmailbox@example.com</emailAddress>
</request>

Response

{
  ...
  "response": {
    "status": "emailAddressAvailable",
    "verificationCode": "",
    "errors": [],
    "bundleCompatibility": true,
    "dnsConfigurationRequired": false,
    "dnsAutoconfigurationPossible": true,
    "currentDnsRecords": [],
    "requiredDnsRecords": []
  }
}

<response>
 <response>
  <response>
 <status>emailAddressAvailable</status>
 <verificationCode></verificationCode>
 <errors></errors>
 <bundleCompatibility>true</bundleCompatibility>
 <dnsConfigurationRequired>false</dnsConfigurationRequired>
 <dnsAutoconfigurationPossible>true</dnsAutoconfigurationPossible>
 <currentDnsRecords></currentDnsRecords>
 <requiredDnsRecords></requiredDnsRecords>
  </response>
 </response>
 ...
</response>

Request	checkEmailAddress
Url	https://secure.hosting.de/api/email/v1/jsonxml/checkEmailAddress
Processing	synchronous
Response	CheckEmailAddressResult

Parameter	Type	Required	Description
emailAddress	string	required	Email address of the mailbox
productCode	string	optional	ProductCode of the mailbox
accountId	string	optional	ID of the account under which the mailbox should be created
bundleId	string	optional	ID of the bundle in which the mailbox should be created
skipDnsCheck	bool	optional	Skip the DNS validation checks

This method checks if an mailbox can be created and if dns authorizationes required (This happens when the domain is not in your account).

If status in the result object is emailAddressAvailable you can proceed to create the mailbox.

If status in the result object is verificationRequired you need to create a TXT DNS record in the domain with the value from the verificationCode field in the result object.

Domain Settings

Domain settings serve to display and limit the usage of mailboxes in a certain domain.

The DomainSettings Object

{
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "storageQuota": -1,
    "storageQuotaAllocated": 1024,
    "mailboxQuota": -1,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
}

<DomainSettings>
 <domainName>example.com</domainName>
 <domainNameUnicode>example.com</domainNameUnicode>
 <storageQuota>-1</storageQuota>
 <storageQuotaAllocated>1024</storageQuotaAllocated>
 <mailboxQuota>-1</mailboxQuota>
 <addDate>2016-01-01T15:57:35Z</addDate>
 <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
</DomainSettings>

Property	Type	Required / Direction	Description
domainName	string	required	Domain name in ASCII/ACE format.
domainNameUnicode	string	out-only	Domain name in Unicode/international format.
storageQuota	int	optional	Storage quota allowed to be used in this domain for imap mailboxes.
storageQuotaAllocated	int	out-only	Currently used storage in this domain for imap mailboxes.
mailboxQuota	int	optional	Number of imap mailboxes allowed to be created in this domain.
exchangeStorageQuota	int	removal pending	Always 0
exchangeStorageQuotaAllocated	int	removal pending	Always 0
exchangeMailboxQuota	int	removal pending	Always 0
addDate	datetime	out-only	Date and time the mailbox was created in the system.
lastChangeDate	datetime	out-only	Last date and time the mailbox was modified.

Listing Domain Settings

POST https://secure.hosting.de/api/email/v1/jsonxml/Find

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "DomainName",
        "value": "example.com"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "DomainName",
        "order": "asc"
    }
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <field>DomainName</field>
  <value>example.com</value>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>DomainName</field>
  <order>asc</order>
 </sort>
</request>

Response

{
    ...
    "response": {
        "data": [
            // DomainSettings objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindDomainSettingsResult"
    },
    ...
}

<response>
 <response>
  <data>
   ...DomainSettings objects
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindDomainSettingsResult</type>
 </response>
 ...
</response>

Request	domainSettingsFind
Url	https://secure.hosting.de/api/email/v1/jsonxml/domainSettingsFind
Processing	synchronous
Response	FindDomainSettingsResult

Listing domain settings uses the generic filtering and sorting API with the method domainSettingsFind. The response will contain a list of DomainSettings objects.

The following fields are available for filtering and sorting:

Field	Description
DomainName	Domain name
MailboxId	ID of mailbox
MailboxEmailAddress	Email address of the mailbox
MailboxEmailAddressUnicode	Email address of the mailbox in Unicode-Form
MailboxDomainName	Domain name of the mailbox
MailboxDomainNameUnicode	Domain name of the mailbox in Unicode-Form

Updating DomainSettings

It is possible to limit mailboxes number or storage usage for certain domains using the DomainSettings object and domainSettingsUpdate API method.

POST https://secure.hosting.de/api/email/v1/jsonxml/domainSettingsUpdate

{
    ...
    "authToken": "$$YOUR API KEY$$",
    "domainSettings": {
        "domainName": "example.com",
        "storageQuota": 10240,
        "mailboxQuota": 10
    }
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
<domainSettings>
 <domainName>example.com</domainName>
 <storageQuota>10240</storageQuota>
 <mailboxQuota>10</mailboxQuota>
</domainSettings>
</request>

Response

{
  ...
  "response": {
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "storageQuota": 10240,
    "storageQuotaAllocated": 1024,
    "mailboxQuota": 10,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-15T12:00:00Z"
  }
}

<response>
 <response>
  <response>
 <domainName>example.com</domainName>
 <domainNameUnicode>example.com</domainNameUnicode>
 <storageQuota>10240</storageQuota>
 <storageQuotaAllocated>1024</storageQuotaAllocated>
 <mailboxQuota>10</mailboxQuota>
 <addDate>2016-01-01T15:57:35Z</addDate>
 <lastChangeDate>2016-01-15T12:00:00Z</lastChangeDate>
  </response>
 </response>
 ...
</response>

Request	domainSettingsUpdate
Url	https://secure.hosting.de/api/email/v1/jsonxml/domainSettingsUpdate
Processing	synchronous
Response	DomainSettings object

Parameter	Type	Required	Description
domainSettings	DomainSettings object	req	Data for the domain settings to be updated