API: OpenSRS

OpenSRS API Guide: Domains and SSL

Welcome to the OpenSRS API guide. Here you will find comprehensive documentation regarding our domain and SSL services. We hope this guide will help you start working with OpenSRS as quickly as possible. If you have any questions or concerns, please do not hesitate to contact [email protected]

Get Started

Lookup (domain)

Determines the availability of a specified domain name.

Request parameters for lookup (domain)

Standard parameters

  • action = lookup
  • object = domain
  • registrant_ip = valid IP address of the registrant (optional) attributes

Attributes

Parameters within the attributes associative array are described below.

Parameter nameObligationDefinition/Value
domainRequiredThe domain name to be queried.
no_cacheOptionalIn order to obtain results quickly, the default for the lookup command is to check the local OpenSRS cache to determine domain name availability. If you specify no_cache = 1, instead of checking the cache, the lookup command queries the applicable registry to determine domain name availability.
Note: Setting no_cache to 1 increases the amount of time it takes to get results.

Response parameters for lookup (domain)

Standard parameters

  • action = reply
  • object = domain
  • is_success = a Boolean is returned, indicating success or failure of the request
  • response_code = response code indicating outcome of the request
  • response_text = message describing the outcome of the request

📘

Note:

Even if the domain being queried is taken (response_code = 211), is_success is set to 1 because the query was successful. Therefore, be sure to check the response_code and response_text when reading the reply.

Response Attributes

If the request is successful, the attributes associative array may include the following:

Parameter nameObligationDefinition/Value
email_availableOptionalIndicates whether a forwarding email is available or not. Applies to .NAME domains only.
0—No forwarding email available
1—Forwarding email available
has_claimReturned for the new TLDs during the claims period (90 days from the start of GA)Indicates whether the domain name has a matching mark registered at the Trademark Clearinghouse (TMCH)
0—No matching marks exist at the TMCH.
1—A mark is registered at the TMCH that matches the domain name.
reasonReturned if the domain queried is a registry premium domain.Indicates that the domain is registry premium.

Value, if returned:

* Premium Name
noserviceReturned for .NAME if is_success = trueIndicates Registry Agent availability. If RA is available, noservice does not appear in response.• 1—Supplier unavailable
Note: when noservice = 1, is_success = 0.
price_statusReturned if is_success = trueThe pricing status.
Undef—Non .TV domains
Fixed—Price is fixed for .TV domains
statusReturned if is_success = trueWhether the domain is available or taken.

Please note: Querying a registry premium domain will always generate a taken response if the reseller has not enabled the registry premium tier to which the domain belongs.

An available response will only be returned under the following conditions:

1. The domain must be available.
2. The registry premium tier to which the domain belongs must be enabled by the reseller.

Domain = Registry Premium

Parameter nameObligationDefinition/Value
reasonReturned if the domain queried is a registry premium domain.Indicates that the domain is registry premium.

Value, if returned:

* Premium Name
statusReturned if is_success = trueWhether the domain is available or taken.

Please note: Querying a registry premium domain will always generate a taken response if the reseller has not enabled the registry premium tier to which the domain belongs.

An available response will only be returned under the following conditions:

1. The domain must be available.
2. The registry premium tier to which the domain belongs must be enabled by the reseller.

Examples for lookup (domain)

Example 1

Request

<?xml version='1.0' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
    <header>
        <version>0.9</version>
    </header>
    <body>
        <data_block>
            <dt_assoc>
                <item key="protocol">XCP</item>
                <item key="object">DOMAIN</item>
                <item key="action">LOOKUP</item>
                <item key="attributes">
                    <dt_assoc>
                        <item key="domain">example.com</item>
                        <item key="no_cache">1</item>
                    </dt_assoc>
                </item>
                <item key="registrant_ip">111.121.121.121</item>
            </dt_assoc>
        </data_block>
    </body>
</OPS_envelope>

Response

<?xml version='1.0' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
 <header>
  <version>0.9</version>
 </header>
  <body>
    <data_block>
      <dt_assoc>
        <item key="protocol">XCP</item>
        <item key="object">DOMAIN</item>
        <item key="response_text">Domain available</item>
        <item key="action">REPLY</item>
        <item key="attributes">
          <dt_assoc>
            <item key="price_status">undef</item>
            <item key="email_available">undef</item>
            <item key="status">available</item>
          </dt_assoc>
        </item>
        <item key="response_code">210</item>
        <item key="is_success">1</item>
      </dt_assoc>
    </data_block>
  </body>
</OPS_envelope>
<?xml version='1.0' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
 <header>
  <version>0.9</version>
  </header>
 <body>
  <data_block>
   <dt_assoc>
    <item key="protocol">XCP</item>
    <item key="object">DOMAIN</item>
    <item key="response_text">Domain taken</item>
    <item key="action">REPLY</item>
    <item key="attributes">
     <dt_assoc>
      <item key="price_status">undef</item>
      <item key="email_available">undef</item>
      <item key="status">taken</item>
     </dt_assoc>
    </item>
    <item key="response_code">211</item>
    <item key="is_success">1</item>
   </dt_assoc>
  </data_block>
 </body>
</OPS_envelope>

Example 2

Lookup request for a new TLD during the claims period.

Request

<?xml version='1.0' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
 <header>
  <version>0.9</version>
 </header>
  <body>
    <data_block>
      <dt_assoc>
        <item key="protocol">XCP</item>
        <item key="object">DOMAIN</item>
        <item key="action">LOOKUP</item>
        <item key="attributes">
          <dt_assoc>
            <item key="domain">example.guru</item>
          </dt_assoc>
        </item>
      </dt_assoc>
    </data_block>
  </body>
</OPS_envelope>

Response

<?xml version='1.0' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
 <header>
  <version>0.9</version>
 </header>
 <body>
   <data_block>
     <dt_assoc>
       <item key="protocol">XCP</item>
       <item key="object">DOMAIN</item>
       <item key="response_text">Domain available</item>
       <item key="action">REPLY</item>
       <item key="attributes">
         <dt_assoc>
           <item key="status">available</item>
           <item key="has_claim">1</item>
         </dt_assoc>
       </item>
       <item key="response_code">210</item>
       <item key="is_success">1</item>
     </dt_assoc>
   </data_block>
  </body>
</OPS_envelope>

Examples for lookup (domain) for Registry Premium Domains

📘

Please note: The response generated when querying a registry premium domain with lookup (domain) is dependent upon which registry premium domains the reseller has enabled. An available registry premium domain will appear unavailable or "taken" if the reseller has not enabled the tier of registry premium domains into which the domain falls.

Request

<?xml version='1.0' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
 <header>
   <version>0.9</version>
 </header>
  <body>
    <data_block>
      <dt_assoc>
        <item key="protocol">XCP</item>
        <item key="object">DOMAIN</item>
        <item key="action">LOOKUP</item>
        <item key="attributes">
          <dt_assoc>
            <item key="domain">ddd.bike</item>
          </dt_assoc>
        </item>
      </dt_assoc>
    </data_block>
  </body>
</OPS_envelope>

Responses

Example 1
This example shows the response generated if the reseller has enabled the tier of registry premium domains into which the domain falls.

<?xml version=\'1.0\' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
  <header>
    <version>0.9</version>
  </header>
  <body>
    <data_block>
      <dt_assoc>
        <item key="protocol">XCP</item>
        <item key="object">DOMAIN</item>
        <item key="response_text">Domain available</item>
        <item key="action">REPLY</item>
        <item key="attributes">
          <dt_assoc>
            <item key="status">available</item>
            <item key="reason">Premium Name</item>
          </dt_assoc>
        </item>
        <item key="response_code">210</item>
        <item key="is_success">1</item>
      </dt_assoc>
    </data_block>
  </body>
</OPS_envelope>

Example 2
This example shows the response generated if the reseller has not enabled the tier of registry premium domains into which the domain falls.

<?xml version=\'1.0\' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
  <header>
    <version>0.9</version>
  </header>
  <body>
    <data_block>
      <dt_assoc>
        <item key="protocol">XCP</item>
        <item key="object">DOMAIN</item>
        <item key="response_text">Domain taken</item>
        <item key="action">REPLY</item>
        <item key="attributes">
          <dt_assoc>
            <item key="status">taken</item>
            <item key="reason">Premium Name</item>
          </dt_assoc>
        </item>
        <item key="response_code">211</item>
        <item key="is_success">1</item>
      </dt_assoc>
    </data_block>
  </body>
</OPS_envelope>

Updated less than a minute ago

Lookup (domain)


Determines the availability of a specified domain name.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.