.. _Droplist_API:

Droplist API
============


The IRS Droplist API will return all domains that will be available to be claimed on the date and time specified in the API Droplist request or the domains claimed in last Droplist session depending on the option used.

List of domains in upcoming session
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This API will provide the list of all domains in an upcoming Droplist session. Use the following API parameters to specify the date and time of the upcoming session.

**API address**

https://api.irs.net.nz

**droplist api Input parameters**

Droplist session date and time:

* /api/tbr/session?datetime=YYYY/MM/DD HH:MM:SS

**Example:**

.. code-block:: xml

     /api/tbr/session?datetime=2022/07/19%02:00:00

**Session Time**

The drop list session times will be every day at 2 am UTC and they will remain open for 1 hour.

**Output parameters**


* The next session's date and time

* The number of domain names in that session

* The name of each domain in the session

**Sample output:**

.. code-block:: xml

     {"releaseDate":2022-07-19T02:00:00.000Z",
      "numberOfDomainNames":8154,
      "domainNames":
          ["domain-name1.nz",
          "domain-name2.nz",... 
          ]
     }


**Rate Limits and Restrictions**

The NZ rate limit is 1 second. The registrar portal help section ( Registry Services Concepts > Droplist > Rate Limits and Restrictions ) details how the rate limit works.

Please note the following:

* The example given is based on a rate limit of 5 seconds not 1 second.
* Performing the Hello, Login, Check or Logout commands will NOT affect the rate limit; you can log in at any time or execute a Check command and the rate limit timestamp will not change.
* The EPP timeout between commands is 300 seconds. If you do not send a command within that time period you will be disconnected.


List of domains claimed in last Droplist session
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This API will provide the list of domains that were registered during the last Droplist session.

**Input parameter**

None:

* /api/tbr/lastsessionresults

**Output parameters**

* Droplist session time

* Count of domains claimed in that session

* Array of claimed domains containing:

  * Domain name

  * Registrar who claimed the domain

  * Created date and time in ascending order

**Sample output:**

.. code-block:: xml

    {
   "releaseDate": "2022-07-18T02:00:00.000Z",
  "numberOfDomainNames": 1,
   "domains": [
    {
       "domainName": "hk-redemption-period-to-pending-delete.nz",
       "registrarName": "Gaining Registrar",
       "timestamp": "2022-07-18T02:00:52.015Z"}
     }
   ],
 }

Claim domains from Droplist
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Droplist function allows a Registry to manage the release of domain names that are about to become available again following the expiry of their current registration. Domain names added to the Droplist will become available to Registrars in a controlled fashion using Droplist sessions, periods during which domain names on the Droplist can be re-registered.

**Credentials**

To access the Droplist system you need an EPP user account. If you have an EPP user account, use the EPP credentials to connect. If you do not have an EPP user account, you may use the IRS portal to create the EPP user account. You can also use the IRS portal to create additional EPP user accounts to be used for Droplist sessions.

**Droplist IP Addresses**

Adding IP addresses to an allowlist is required to access the Droplist sessions. You can enter up to 200 IP addresses in the IP Addresses for Droplist Servers section of the Registrar Settings page in the IRS portal but only up to 10 can be used to connect concurrently. If your IP address has not been identified as a Droplist IP address, your connection will be refused.

For details on setting up your IP addresses see `IP allowlist <https://docs.internetnz.nz/registry/IRS_OTE/#ip-whitelisting>`_

**Droplist Commands**

There are two EPP commands available for use in the Droplist system: Domain Check and Domain Create.

**Droplist Server**

To access the droplist server to claim domains or check domains use the following server name for the connection.

.. code-block:: xml

 tbr.irs.net.nz