Bulk Transfers API Examples

Bulk Transfers allows you to easily transfer a large amount of domains into your reseller account.

 

Bulk Transfers works via an API call. Each API call sent creates a Bulk Transfers "job", where it initiates the transfer of any number of domains from 1 to 10,000 per job.

In the API command, you must specify at least the domain and auth code, but may also specify several other attributes. OpenSRS will do all the other heavy lifting. Our backend will then:

  • Check if the authcode is correct up front
  • Lookup the Whois info and pre-populate contact data from existing whois
  • Send the approval email to the registrant email (not the admin email)
  • Perform Registrant Verification
  • Initiate the transfer(s) using the auth code

The bulk transfer process will only work for domains that are currently registered with registrars operating on the 2013 RRA, as it relies on the standardized whois format required by this RRA.

Although only the domain and auth code are required, there are many other attributes which can be configured and sent as part of the API command. These include:

  • Job name
  • Registrant domain (their existing domain)
  • Registrant username (the username for that domain)
  • Password (for that domain)
  • Nameserver list
  • DNS template

Once the API call is sent, the job will immediately fail out and not allow submission if any of the following problems are present:

  • if the maximum number of items exceeds the maximum (10,000 per job)
  • if the domain list is not in a correct format, or contains no items, or is missing auth_info
  • if the optional reg_domain, reg_username, and reg_password are not for a valid existing profile
  • if both namserver_list and dns_template are given
  • if the provided dns_template is not a valid existing dns template in our system
  • if items in the namserver_list do not pass our hostname validation
  • if the TLD for one of the domains is not valid, is not supported by the bulk transfer process, does not support auth_info, does not support the auth_info_check command, or is missing auth_info

Once the job is in progress, each domain is analyzed. From this point on, the bulk job as a whole will proceed, and only individual domains would fail. Possible reasons reasons for failure at this point include:

  • transferability check fails (within 60 day period, locked, etc.)
  • the TLD does not allow f_bypass_transfer which is essential to making this process work with minimal communication to the registrant
  • the registry will send out their own confirmation emails (as this would cause the registrant to get many confirmation emails from the registry)
  • the supplied auth_info is not correct for the domain
  • Whois data could not be retreived, or is not parseable
  • the contact data found in the whois data does not pass our validation for valid contact data
  • any other abnormal failures when analyzing the domain (like DB is down)

Once the analysis completes without error:

  • a transfer order is processed with F_BYPASS_CONFIRM, and will sit with the status of PROCESSED until the registrant accepts/rejects the transfer.  
  • a single email is sent to each registrant/owner contact (not the admin contact) asking for approval for all of their domains (in this single job)

             -it will timeout after 7 days of non-reponse, the transfer will *not* be initiated at the registry, and the registrant status becomes COMPLETED

             -on cancel, all orders will be cancelled out, and the registrant status is COMPLETED

             -on accept, orders placed are set to pending_registry, and await finalization from the normal transfer process. Once all of the domains are dealt with, the registrant status becomes COMPLETED

 

After successful completion of the transfer, the domain will have the exact same contacts as prior to the transfer. If you have changed the registrants prior to the transfer to direct confirmation emails to a single email address, they will need to update the email once the  transfer is completed – which will, of course, trigger another registrant verification process. However, you are in control as to when this process starts, and by using the bulk transfer feature are able to disconnect the actual transfer from the registrant verification interaction with the end user.

Examples of a Bulk Transfer sequence of API Requests and Responses:

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">SIMPLE_TRANSFER</item>
    <item key="attributes">
     <dt_assoc>
      <item key="domain_list">
       <dt_array>
        <item key="0">
         <dt_assoc>
          <item key="domain_name">newtransfer461.com</item>
          <item key="auth_info">@xMj%[1b</item>
         </dt_assoc>
        </item>
        <item key="1">
         <dt_assoc>
          <item key="domain_name">newtransfer462.com</item>
          <item key="auth_info">Mj%zA>1r</item>
         </dt_assoc>
        </item>
        <item key="2">
         <dt_assoc>
          <item key="domain_name">newtransfer463.com</item>
          <item key="auth_info">AK4u.+5U</item>
         </dt_assoc>
        </item>
        <item key="3">
         <dt_assoc>
          <item key="domain_name">newtransfer464.com</item>
          <item key="auth_info">L+7Dk`3j</item>
         </dt_assoc>
        </item>
        <item key="4">
         <dt_assoc>
          <item key="domain_name">newtransfer465.com</item>
          <item key="auth_info">$^o&)@7q</item>
         </dt_assoc>
        </item>
        <item key="5">
         <dt_assoc>
          <item key="domain_name">newtransfer466.com</item>
          <item key="auth_info">o&)u-`7H</item>
         </dt_assoc>
        </item>
        <item key="6">
         <dt_assoc>
          <item key="domain_name">newtransfer467.com</item>
          <item key="auth_info">YVnth.5I</item>
         </dt_assoc>
        </item>
        <item key="7">
         <dt_assoc>
          <item key="domain_name">newtransfer468.com</item>
          <item key="auth_info">!(SZ+@6r</item>
         </dt_assoc>
        </item>
        <item key="8">
         <dt_assoc>
          <item key="domain_name">newtransfer469.com</item>
          <item key="auth_info">U$K"y*9a</item>
         </dt_assoc>
        </item>
       </dt_array>
      </item>
     </dt_assoc>
    </item>
   </dt_assoc>
  </data_block>
 </body>
</OPS_envelope>

Response:

{
  'protocol' => 'XCP',
  'object' => 'DOMAIN',
  'response_text' => 'Simple transfer job successfully added',
  'action' => 'REPLY',
  'attributes' => {
    'simple_transfer_job_id' => '134'
  },
  'response_code' => '200',
  'is_success' => '1'
}
<?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">Simple transfer job successfully added</item>
    <item key="action">REPLY</item>
    <item key="response_code">200</item>
    <item key="attributes">
     <dt_assoc>
      <item key="simple_transfer_job_id">134</item>
     </dt_assoc>
    </item>
    <item key="is_success">1</item>
   </dt_assoc>
  </data_block>
 </body>
</OPS_envelope>

 

Request:

{
    protocol => 'XCP',
    object => 'domain',
    action => 'simple_transfer_status',
    attributes => {
        simple_transfer_job_id => 134,
    }
}

Response:

{
  'protocol' => 'XCP',
  'object' => 'DOMAIN',
  'response_text' => 'Simple transfer job information successfully loaded',
  'action' => 'REPLY',
  'response_code' => '200',
  'attributes' => {
    'status' => 'completed',
    'name' => 'unspecified - 2014-07-03 18:34:34',
    'id' => '134',
    'registrant_list' => [
      {
        'email_address' => 'jcrawford@tucows.com',
        'status' => 'completed',
        'name' => 'jeff crawford',
        'id' => '96'
      }
    ],
    'domain_list' => [
      {
        'domain_name' => 'newtransfer477.com',
        'status' => 'completed',
        'reason' => undef,
        'registrant_id' => '96'
      },
      {
        'domain_name' => 'newtransfer478.com',
        'status' => 'failed',
        'reason' => 'Could not parse whois',
        'registrant_id' => undef
      }
    ]
  },
  'is_success' => '1'
}
<?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">Simple transfer job information successfully loaded</item>
    <item key="action">REPLY</item>
    <item key="attributes">
     <dt_assoc>
      <item key="status">completed</item>
      <item key="name">unspecified - 2014-07-03 18:34:34</item>
      <item key="id">134</item>
      <item key="registrant_list">
       <dt_array>
        <item key="0">
         <dt_assoc>
          <item key="email_address">jcrawford@tucows.com</item>
          <item key="status">completed</item>
          <item key="name">jeff crawford</item>
          <item key="id">96</item>
         </dt_assoc>
        </item>
       </dt_array>
      </item>
      <item key="domain_list">
       <dt_array>
        <item key="0">
         <dt_assoc>
          <item key="domain_name">newtransfer477.com</item>
          <item key="status">completed</item>
          <item key="registrant_id">96</item>
          <item key="reason"></item>
         </dt_assoc>
        </item>
        <item key="1">
         <dt_assoc>
          <item key="domain_name">newtransfer478.com</item>
          <item key="status">failed</item>
          <item key="registrant_id"></item>
          <item key="reason">Could not parse whois</item>
         </dt_assoc>
        </item>
       </dt_array>
      </item>
     </dt_assoc>
    </item>
    <item key="response_code">200</item>
    <item key="is_success">1</item>
   </dt_assoc>
  </data_block>
 </body>
</OPS_envelope>
Have more questions? Submit a request

3 Comments

  • Avatar
    Markus

    Will this be integrated in the PHP API Toolkit anytime soon?

  • Avatar
    Aaron Bailey

    Hello Markus,

    Here is a link to the bulk changes section of the latest PHP Toolkit release:

    https://github.com/OpenSRS/osrs-toolkit-php/tree/master/opensrs/domains/bulkchange

    I believe this is what you are looking for, however, if not please let me know.

    Regards,

    Aaron

  • Avatar
    Markus

    I only found the old bulk_transfer command (only works for com/net) there. The SIMPLE_TRANSFER command is much more powerful. Would be great to see it integrated in the php api toolkit. Also it's not quite clear to me if this command needs to be submitted to batch.opensrs.net or the regular api server. (as a SoftLayer reseller I don't have access to the batch system)

Please sign in to leave a comment.
Powered by Zendesk