API Queries - Manage Domains

The manage_domains API function lists domains in your account and their details (name servers, expiry date, lock status, etc.). Various sorting options are available and up to 1,000 domains can be shown per query. You can also filter the list by providing one or more domains (maximum 1,000) via the domain parameter. Additional parameters are optional for this function.

Additional Parameters

• domain (optional) - Search for one or more domains. Multiple domains (up to 1,000) can be specified by seperating with a comma (,). Note: http://www. should not be included.
• limit (optional) - Number of domains to return. Accepted values are 1-1,000. Default is 100.
• offset (optional) - This paramater is used in with the limit paramater to show each "page" of domains. Note that the first domain is under record 0. For example if you wanted to return domains 21-30, you would use (offset=20&limit=10). See Example 3 for more details and examples. Accepted values are 0 or greater. Default is 0.
• sort_by (optional) - Sort list by various fields. Accepted values are "domain" (sort by domain name alphabetically), "expiry" (expiry date, past and closest dates first), "created" (date domain was registered, oldest first). Default is "domain".
• order (optional) - Choose to show sort_by field in ascending or descending order (alphabetically or chronologically). Accepted values are "asc" (ascending order) and "desc" (descending order). Default is "asc" (ascending order).

Your API key is required and all values should be correctly URL encoded.

Response Values

General and sorting response values:

• total - If the domain parameter is used, this value is the total domains found for your search. Otherwise, this value is the total domains in your account.
• offset - The current offset value (default value if paramater is not specified). See Additional Parameters section above.
• limit - The current limit value (default value if paramater is not specified). See Additional Parameters section above.
• sort_by - The current sort_by value (default value if paramater is not specified). See Additional Parameters section above.
• order - The current order value (default value if paramater is not specified). See Additional Parameters section above.

In the examples, you will see that a lot of information about each domain is returned by our API. A basic explanation of each item and possible values are provided below:

• created - Date and time the domain was registered, shown in UTC time.
• expiry - Expiry date and time of the domain, shown in UTC time. Note that this value can be in the past if the domain has already expired or is in the redemption period.
• dns1 and dns2 - Primary and secondary name servers respectively. This value will be "NO" if no name servers are set.
• technical_contact, admin_contact, registrant_contact and billing_contact - Technical, admin, registrant and billing contact ID respectively. Domain contacts can be added and updated via the Above.com Registrar website.
• privacy - Whois privacy status. Possible values are "on" and "off".
• category - Category set in Above.com Registrar website.
• paid - Paid amount set in Above.com Registrar website.
• value - Value set in Above.com Registrar website.
• keyword - Keywords set in Above.com Registrar website.
• autorenew - Auto renew status. Possible values are "on", "off" and "on_once" (will auto renew once, then be set back to "off").
• status - Domain status. Possible values are "ok", "Pending Create", "Pending Delete", "Pending Renew", "Pending Transfer", "Pending Update", "Registrar Lock", "Registry Lock", "Redemption" and "Expired".
• lock - Lock status. Possible values are "On" and "off".
• lock_type - Type of lock on domain. Possible values are "Registrar", "Registry", "60 Day", "Client" and "Off".

Example

In the below example, we will use the query without specifying any additonal parameters. This will list the first 100 domains with default sorting options. (The equivalent of offset=0&limit=100&sort_by=domain&order=asc).

Note: The response has been truncated in this example.

Query

https://www.above.com/registrar/api/query.html?key=APIKEY&query=manage_domains

Response

<results code="100">
             <domains total="1474" offset="0" limit="100" sort_by="domain" order="ASC">  
              <r domain="apples.com">
               <created>2014-05-06 03:47:40</created>
               <expiry>2018-05-06 03:47:40</expiry>
               <dns1>ns1.abovedomains.com</dns1>
               <dns2>ns2.abovedomains.com</dns2>
               <technical_contact>260152_673371</technical_contact>
               <admin_contact>260152_673371</admin_contact>
               <registrant_contact>260152_673371</registrant_contact>
               <billing_contact>260152_673371</billing_contact>
               <privacy>off</privacy>
               <category></category>
               <paid></paid>
               <value></value>
               <keyword></keyword>
               <autorenew>off</autorenew>
               <status>ok</status>
               <lock>On</lock>
               <lock_type>Client</lock>
              </r>
              <r domain="oranges.net">
               <created>2014-01-21 02:49:35</created>
               <expiry>2017-01-21 02:49:35</expiry>
               <dns1>ns1.abovedomains.com</dns1>
               <dns2>ns2.abovedomains.com</dns2>
               <technical_contact>260152_673371</technical_contact>
               <admin_contact>260152_673371</admin_contact>
               <registrant_contact>260152_673371</registrant_contact>
               <billing_contact>260152_673371</billing_contact>
               <privacy>off</privacy>
               <category></category>
               <paid></paid>
               <value></value>
               <keyword></keyword>
               <autorenew>off</autorenew>
               <status>ok</status>
               <lock>On</lock>
               <lock_type>Client</lock>
              </r>
             </domains>
            </results>
            

Example 2

You can use the domain paramater to search for one or more domains in your account (up to 1,000 at a time) and to return their details. In this example, we will fetch details for "oranges.com" and "shoes.net" (domain=oranges.com,shoes.net)

Query

https://www.above.com/registrar/api/query.html?key=APIKEY&query=manage_domains&domain=oranges.com,shoes.net

Response

<results code="100">
             <domains total="2" offset="0" limit="100" sort_by="domain" order="ASC">  
              <r domain="oranges.net">
               <created>2014-01-21 02:49:35</created>
               <expiry>2017-01-21 02:49:35</expiry>
               <dns1>ns1.abovedomains.com</dns1>
               <dns2>ns2.abovedomains.com</dns2>
               <technical_contact>260152_673371</technical_contact>
               <admin_contact>260152_673371</admin_contact>
               <registrant_contact>260152_673371</registrant_contact>
               <billing_contact>260152_673371</billing_contact>
               <privacy>off</privacy>
               <category></category>
               <paid></paid>
               <value></value>
               <keyword></keyword>
               <autorenew>off</autorenew>
               <status>ok</status>
               <lock>On</lock>
               <lock_type>Client</lock>
              </r>
              <r domain="shoes.net">
               <created>2014-05-06 03:47:40</created>
               <expiry>2018-05-06 03:47:40</expiry>
               <dns1>ns1.abovedomains.com</dns1>
               <dns2>ns2.abovedomains.com</dns2>
               <technical_contact>260152_673371</technical_contact>
               <admin_contact>260152_673371</admin_contact>
               <registrant_contact>260152_673371</registrant_contact>
               <billing_contact>260152_673371</billing_contact>
               <privacy>off</privacy>
               <category></category>
               <paid></paid>
               <value></value>
               <keyword></keyword>
               <autorenew>off</autorenew>
               <status>ok</status>
               <lock>On</lock>
               <lock_type>Client</lock>
              </r>  
             </domains>
            </results>
            

Example 3

Various sorting options are available for the manage_domains API function. In the below example, we will sort domains by created date in descending order. This will show the most recently registered domains first. (sort_by=created&order=desc).

Note: The response has been truncated in this example.

Query

https://www.above.com/registrar/api/query.html?key=APIKEY&query=manage_domains&sort_by=created&order=desc

Response

<results code="100">
             <domains total="1474" offset="0" limit="100" sort_by="created" order="DESC">  
              <r domain="johnsmith.name">
               <created>2014-07-25 10:55:11</created>
               <expiry>2017-07-25 10:55:11</expiry>
               <dns1>ns1.abovedomains.com</dns1>
               <dns2>ns2.abovedomains.com</dns2>
               <technical_contact>260152</technical_contact>
               <admin_contact>260152</admin_contact>
               <registrant_contact>260152</registrant_contact>
               <billing_contact>260152</billing_contact>
               <privacy>off</privacy>
               <category></category>
               <paid></paid>
               <value></value>
               <keyword></keyword>
               <autorenew>off</autorenew>
               <status>ok</status>
               <lock>On</lock>
               <lock_type>Client</lock>
              </r>
              <r domain="webhosting.net">
               <created>2014-06-30 05:10:45</created>
               <expiry>2017-06-30 05:10:45</expiry>
               <dns1>ns1.abovedomains.com</dns1>
               <dns2>ns2.abovedomains.com</dns2>
               <technical_contact>260152_673371</technical_contact>
               <admin_contact>260152_673371</admin_contact>
               <registrant_contact>260152_673371</registrant_contact>
               <billing_contact>260152_673371</billing_contact>
               <privacy>off</privacy>
               <category></category>
               <paid></paid>
               <value></value>
               <keyword></keyword>
               <autorenew>off</autorenew>
               <status>ok</status>
               <lock>On</lock>
               <lock_type>Client</lock>
              </r>  
             </domains>
            </results>
            

Example 3

The limit and offset parameters work exactly the same way they do in common database SQL. The offset parameter is the record you want to start at (0 is the first record) and the limit parameter is used to control how many records are returned.

To return details for domains 1-10 for example, you would use the following:
offset=0&limit=10

For the second page of domains (11-20), you would use the following:
offset=10&limit=10

For the third page of domains (21-30), you would use the following:
offset=20&limit=10

If you were showing 100 domains per page and wanted the third page of domains (201-300), you would use the following:
offset=200&limit=100

Note: The response has been truncated in this example.

Query

In this example, there are a total of 150 domains in the account, however we are trying to fetch domains 201-300. We will receive an error as no records will be found for this query.

https://www.above.com/registrar/api/query.html?key=APIKEY&query=manage_domains&offset=200&limit=100

Response

<results code="2001">
             <msg>No domains found</msg>
            </results>
            

Error Codes

Possible error responses for this function are:

• 2001 - No domains found
• 2002 - Invalid limit. Accepted values are 1-1000
• 2003 - Invalid offset. Accepted values are 0 or greater
• 2004 - Invalid sort_by value. Accepted values are domain, expiry, created
• 2005 - Invalid order value. Accepted values are asc, desc
• General errors, such as 401 - Invalid API key or 500 - System unavailable.