Search in this section

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Instructions for the complete automation of the registration of a domain, using the example of the domain example.com.
.com is a generic top-level domain, which is well suited for the first implementation due to the lack of restrictions.

Panel
titleColor#FFFFFF
titleBGColor#E44313
titleTable of Contents

Table of Contents
maxLevel4
outlinetrue
stylenone

Basics of the JSON and XML API

All important information for the use of the JSON and XML API can be found under the following links:

Process Overview

Flow Chart

Tasks Names, Codes and Routes

TaskCodeRoute
ContactCreate0301POST /contact
DomainCreate0101POST /domain
PollInfo0905GET /poll
PollConfirm0906PUT /poll/$id
DomainInfo0105GET / domain/$name

Requirements

Domain Contacts

To order a .com domain you need a domain owner (OwnerC), an administrative contact (AdminC) and a technical contact (TechC). You can use existing contacts or create new ones.

Info
iconfalse

Which data a contact must contain for the registration of a domain depends on the TLD. Each registry has its own guidelines. Some TLDs require so-called contact extensions. Detailed information about all TLDs we offer can be found in the TLD Knowledge Base

ContactCreate  - Example

SP Tabs group
dispositionhorizontal
SP Tab pane
nameJSON
Code Block
languagejs
titleRequest
linenumberstrue
collapsetrue
POST /contact
{
  "type": "PERSON",
  "fname": "John",
  "lname": "Doe",
  "organization": "Company",
  "address": [
      "123 Main Street"
  ],
  "pcode": "12345",
  "city": "Anytown",
  "country": "DE",
  "state": "BY",
  "phone": "+49-0-0",
  "email": "john.doe@domain.com"
}
Code Block
languagejs
titleResponse
linenumberstrue
collapsetrue
{
    "stid": "20180926-app3-dev-4889",
    "status": {
        "code": "S0301",
        "text": "Domain contact has been successfully created.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "handle",
        "value": "23102255"
    },
    "data": [
        {
            "created": "2018-09-26T15:18:53.000+0200",
            "updated": "2018-09-26T15:18:53.000+0200",
            "id": 23102255,
            "owner": {
                "user": "USER",
                "context": CONTEXT
            },
            "updater": {
                "user": "USER",
                "context": CONTEXT
            },
            "alias": "John-Doe",
            "type": "PERSON",
            "fname": "John",
            "lname": "Doe",
            "organization": "Company",
            "address": [
                "123 Main Street"
            ],
            "pcode": "12345",
            "city": "Anytown",
            "country": "DE",
            "state": "BY",
            "phone": "+49-0-0",
            "email": "john.doe@domain.com",
            "protection": "SHOW_NONE"
        }
    ]
}
SP Tab pane
nameXML
Code Block
languagexml
titleRequest
linenumberstrue
collapsetrue
<request>
  <auth>
    <user>USER</user>
    <password>PASSWORD</password>
    <context>CONTEXT</context>
  </auth>
  <task>
    <code>0301</code>
    <handle>
      <type>PERSON</type>
      <fname>John</fname>
      <lname>Doe</lname>
      <organization>Anycorp</organization>
      <address>Anystreet</address>
      <pcode>12345</pcode>
      <city>Anytown</city>
      <country>DE</country>
      <state />
      <phone>+49-0-0</phone>
      <fax>+49-0-0</fax>
      <email>john.doe@domain.com</email>
    </handle>
  </task>
</request>
Code Block
languagexml
titleResponse
linenumberstrue
collapsetrue
<response>
  <result>
    <data />
    <status>
      <code>S0301</code>
      <text>Domain contact has been successfully created.</text>
      <type>success</type>
      <object>
        <type>handle</type>
        <value>100</value>
      </object>
    </status>
  </result>
 <stid>20180926-stid</stid>
</response>

Process

Registering domains is an asynchronous process because the registry is involved in the processing of the order. The order notifications are provided in the system upon receipt and can be retrieved by polling.

Info

For more details on asynchronous notifications, see:

Starting DomainCreate  Request

With the request type DomainCreate you start the registration of the domain. The following values are required:

  • Contacts:  The contact ID of the required contacts. For .com domains, a domain owner, an administrative contact and a technical contact are required.
  • Domain: The name of the domain
  • Name server: The desired name servers. The number of name servers required depends on the TLD.
Info

Which additional data is required for a domain depends on the TLD. Each registry has its own guidelines. Further information can be found in the TLD Knowledge Base.

Domain Create - Example

SP Tabs group
dispositionhorizontal
SP Tab pane
nameJSON
Code Block
languagejs
titleRequest
linenumberstrue
collapsetrue
POST /domain
{
    "name": "example.com",
    "ownerc": {
        "id": 100
    },
    "adminc": {
        "id": 100
    },
    "techc": {
        "id": 100
    },
    "nameServers": [
        {
          "name": "a.ns14.net"
        },
        {
          "name": "b.ns14.net"
        },
        {
          "name": "c.ns14.net"
        },
        {
          "name": "d.ns14.net"
        }
    ]
}
Code Block
languagejs
titleResponse
linenumberstrue
collapsetrue
{
    "stid": "20180926-stid",
    "status": {
        "code": "N0101",
        "text": "Domain registration was started successfully.",
        "type": "NOTIFY"
    },
    "object": {
        "type": "domain",
        "value": "example.com"
    }
}
SP Tab pane
nameXML
Code Block
languagexml
titleRequest
linenumberstrue
collapsetrue
<request>
  <auth>
    <user>USER</user>
    <password>PASSWORD</password>
    <context>CONTEXT</context>
  </auth>
  <task>
    <code>0101</code>
    <domain>
      <name>example.com</name>
      <ownerc>100</ownerc>
      <adminc>100</adminc>
      <techc>100</techc>
      <nserver>
        <name>a.ns14.net</name>
      </nserver>
      <nserver>
        <name>b.ns14.net</name>
      </nserver>
      <nserver>
        <name>c.ns14.net</name>
      </nserver>
      <nserver>
        <name>d.ns14.net</name>
      </nserver>
      <confirm_order>1</confirm_order>
      <period>1</period>
    </domain>
  </task>
</request>
Code Block
languagexml
titleResponse
linenumberstrue
collapsetrue
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <result>
    <data>
      <domain_job>
        <job>
          <id>123456</id>
          <status>RUNNING</status>
        </job>
      </domain_job>
    </data>
    <status>
      <code>N0101</code>
      <text>Domain registration was started successfully.</text>
      <type>notify</type>
      <object>
        <type>domain</type>
        <value>example.com</value>
      </object>
    </status>
  </result>
		<stid>20181015-dev-3282< <stid>20180926-stid</stid>
 <</response>

Checking and confirming Notifications

The order type DomainCancelationCreate creates a cancelation request. This triggers the creation of a second cancelation request, which is processed asynchronously at the time defined in the cancelation.
Once this second requst has been processed, a request notification is sent, indicating whether the deletion was successful or not.
You must call the notification with the PollInfo task.  You must confirm the retrieval with the PollConfirm task.

PollInfo - Examples

SP Tabs group
dispositionhorizontal
SP Tab pane
nameJSON
Code Block
languagejs
titleRequest
linenumberstrue
collapsetrue
GET /poll
Code Block
languagejs
titleResponse
linenumberstrue
collapsetrue
{
    "stid": "20180926-stid",
    "status": {
        "code": "S0905",
        "text": "The notification was polled successfully.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "message",
        "value": "1819917"
    },
    "data": [
        {
            "summary": 1,
            "message": {
                "id": 1819917,
                "job": {
                    "id": 4295609745,
                    "domain": {
                        "created": "2018-09-26T15:11:21.000+0200",
                        "owner": {},
                        "updater": {},
                        "name": "example.com",
                        "expire": "2019-09-26T15:11:20.000+0200",
                        "payable": "2019-09-26T15:11:21.000+0200",
                        "ownerc": {
                            "id": 100
                        },
                        "adminc": {
                            "id": 100
                        },
                        "techc": {
                            "id": 100
                        },
                        "registryStatus": "LOCK",
                        "nameServers": [
                            {
                                "name": "a.ns14.net"
                            },
                            {
                                "name": "b.ns14.net"
                            },
                            {
                                "name": "c.ns14.net"
                            },
                            {
                                "name": "d.ns14.net"
                            }
                        ],
                        "lastAction": "CREATE",
                        "authinfo": "gg9o3FFL/hzNbuPw",
                        "autoRenewStatus": "TRUE",
                        "registrarStatus": "ACTIVE",
                        "rddsOptIn": "NOT_SET"
                    }
                },
                "stid": "20180926-stid",
                "object": {
                    "type": "domain",
                    "value": "example.com"
                },
                "status": {
                    "code": "S0101",
                    "type": "SUCCESS"
                }
            }
        }
    ]
}
SP Tab pane
nameXML
Code Block
languagexml
titleRequest
linenumberstrue
collapsetrue
<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>0905</code>
    </task>
</request>
Code Block
languagexml
titleResponse
linenumberstrue
collapsetrue
<response>
    <result>
        <data>
            <summary>1</summary>
            <message>
                <id>1855680</id>
                <owner>
                    <user>alex_normal_plus</user>
                    <context>4</context>
                </owner>
                <job>
                    <domain>
                        <name>example.com</name>
                        <expire>2019-10-15 14:02:40</expire>
                        <payable>2019-10-15 14:02:41</payable>
                        <ownerc>100</ownerc>
                        <adminc>100</adminc>
                        <techc>100</techc>
                        <nic_member_label>VGRS-TEST</nic_member_label>
                        <registry_status>LOCK</registry_status>
                        <nserver>
                            <name>a.ns14.net</name>
                        </nserver>
                        <nserver>
                            <name>b.ns14.net</name>
                        </nserver>
                        <nserver>
                            <name>c.ns14.net</name>
                        </nserver>
                        <nserver>
                            <name>d.ns14.net</name>
                        </nserver>
                        <period>1</period>
                        <authinfo>S0Lygv+ZkNbniICm</authinfo>
                        <autorenew>true</autorenew>
                        <confirm_order>1</confirm_order>
                        <confirm_owner_consent>0</confirm_owner_consent>
                        <registrar_status>ACTIVE</registrar_status>
                        <rdds_opt_in>NOT_SET</rdds_opt_in>
                        <owner/>
                        <updater/>
                        <created>2018-10-15 14:02:41</created>
                    </domain>
                    <job_id>4295625406</job_id>
                    <status>
                        <code>S0101</code>
                        <type>success</type>
                        <object>
                            <type>domain</type>
                            <value>example.com</value>
                        </object>
                    </status>
                    <stid>20181015-app1-3788</stid>
                </job>
                <created>2018-10-15 14:03:02</created>
            </message>
        </data>
        <status>
            <code>S0905</code>
            <text>The notification was polled successfully.</text>
            <type>success</type>
            <object>
                <type>message</type>
                <value>1855680</value>
            </object>
        </status>
    </result>
    <stid>20181015-app1-3805</stid>
</response>

PollConfirm - Examples

SP Tabs group
dispositionhorizontal
SP Tab pane
nameJSON
Code Block
languagejs
titleRequest
linenumberstrue
collapsetrue
PUT /poll/{id}
Code Block
languagejs
titleResponse
linenumberstrue
collapsetrue
{
    "stid": "20180926-stid",
    "status": {
        "code": "S0906",
        "text": "The notification was confirmed successfully.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "message",
        "value": "1819853"
    }
}
SP Tab pane
nameXML
Code Block
languagexml
titleRequest
linenumberstrue
collapsetrue
<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>0906</code>
       <message>
            <id>650664</id>
        </message>
    </task>
</request>
Code Block
languagexml
titleResponse
linenumberstrue
collapsetrue
<response>
    <result>
        <data>
            <summary>0</summary>
            <message>
                <id>650664</id>
            </message>
        </data>
        <status>
            <code>S0906</code>
            <text>The notification was confirmed successfully.</text>
            <type>success</type>
            <object>
                <type>message</type>
                <value>650664</value>
            </object>
        </status>
      </result>
   <stid>20181015-app1-3162</stid>
	 </result>
</response>

Inquire Domain Data

After successful registration, you can query the registration data stored in the system with the DomainInfo task. This enables you to determine whether the domain has been registered with the desired data.

SP Tabs group
dispositionhorizontal
SP Tab pane
nameJSON
Code Block
languagejs
titleRequest
linenumberstrue
collapsetrue
GET /domain/example.com
Code Block
languagejs
titleResponse
linenumberstrue
collapsetrue
{
    "stid": "20180926-stid",
    "status": {
        "code": "S0105",
        "text": "Domain data has been inquired successfully.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "domain",
        "value": "example.com"
    },
    "data": [
        {
            "created": "2018-09-26T14:54:03.000+0200",
            "updated": "2018-09-26T14:54:10.000+0200",
            "owner": {
                "user": "USER",
                "context": CONTEXT
            },
            "updater": {
                "user": "USER",
                "context": CONTEXT
            },
            "name": "example.com",
            "payable": "2021-12-31T00:00:00.000+0200",
            "ownerc": {
                "id": 100
            },
            "adminc": {
                "id": 100
            },
            "techc": {
                "id": 100
            },
            "registryStatus": "LOCK",
            "nameServers": [
                {
                    "name": "a.ns14.net"
                },
                {
                    "name": "b.ns14.net"
                },
                {
                    "name": "c.ns14.net"
                },
                {
                    "name": "d.ns14.net"
                }
            ],
            "trustee": false,
            "privacy": false,
            "authinfo": "J/w0Xpn66I87YVty",
            "domainsafe": false,
            "validCertificate": false,
            "autoRenewStatus": "TRUE",
            "registrarStatus": "ACTIVE",
            "rddsOptIn": "NOT_SET"
        }
    ]
}
SP Tab pane
nameXML
Code Block
languagexml
titleRequest
linenumberstrue
collapsetrue
<request>
  <auth>
    <user>USER</user>
    <password>PASSWORD</password>
    <context>CONTEXT</context>
  </auth>
  <task>
    <code>0105</code>
    <domain>
      <name>example.com</name>
    </domain>
  </task>
</request>
Code Block
languagexml
titleResponse
linenumberstrue
collapsetrue
<response>
  <result>
    <data>
      <domain>
        <name>example.com</name>
        <payable>2021-12-31 00:00:00</payable>
        <ownerc>100</ownerc>
        <adminc>100</adminc>
        <techc>100</techc>
        <registry_status>LOCK</registry_status>
        <nserver>
          <name>a.ns14.net</name>
        </nserver>
        <nserver>
          <name>b.ns14.net</name>
        </nserver>
        <nserver>
          <name>c.ns14.net</name>
        </nserver>
        <nserver>
          <name>d.ns14.net</name>
        </nserver>
        <period>1</period>
        <status>SUCCESS</status>
        <use_trustee>false</use_trustee>
        <use_privacy>false</use_privacy>
        <authinfo>J/w0Xpn66I87YVty</authinfo>
        <domainsafe>false</domainsafe>
        <certificate>false</certificate>
        <autorenew>true</autorenew>
        <registrar_status>ACTIVE</registrar_status>
        <rdds_opt_in>NOT_SET</rdds_opt_in>
        <owner>
          <user>USER</user>
          <context>CONTEXT</context>
        </owner>
        <updater>
          <user>USER</user>
          <context>CONTEXT</context>
        </updater>
        <created>2018-09-26 14:54:03</created>
        <updated>2018-09-26 14:54:10</updated>
      </domain>
    </data>
    <status>
      <code>S0105</code>
      <text>Domain data has been inquired successfully.</text>
      <type>success</type>
      <object>
        <type>domain</type>
        <value>example.com</value>
      </object>
    </status>
  </result>
  <stid>20180926-stid</stid>
</response>