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 help@opensrs.com

Get Started

check_transfer

Checks to see if the specified domain can be transferred in to OpenSRS, or from one OpenSRS reseller to another. This call can also be used to check the status of the last transfer request on a given domain name.

When you use the check_transfer action prior to initiating a transfer, the transferable response parameter is most relevant, and if transferable = 0, the reason field is also important.

When you use the check_transfer action to determine the progress of a transfer, the status parameter is most important. If the response indicates that the transfer is in progress and the status is pending_registry, the transfer will be scheduled to complete within 5 minutes of the query; running the query expedites the process and causes the transfer to complete within 5 minutes.

Request parameters for check_transfer

Standard parameters

  • action = check_transfer
  • object = domain attributes

Attributes

Parameters within the attributes associative array are described below.

Parameter name
Obligation
Definition/Value

check_status

Optional

Flag to request the status of a transfer request. If the transfer state is returned as pending_registry and the Registry shows OpenSRS as the Registrar of record, OpenSRS schedules the completion of gTLD transfers.

Allowed values are 0 or 1.

domain

Required

The fully qualified domain name in the transfer order.

get_request_address

Optional

Flag to request the registrant's contact email address. This is useful if you want to make
sure that your client can receive mail at that address to acknowledge the transfer.

Allowed values are 0 or 1.

Response parameters for check_transfer

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

Attributes

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

Parameter name
Obligation
Definition/Value

noservice

Returned if
is_success=true

Indication of supplier availability:

  • 0—Supplier is available

  • 1—Supplier is unavailable.

Note: When noservice is 1 then transferable is set to 0 and is_success is set to 1.

reason

Returned if is_success = true and transferrable = 0

Reason for transfer status.

request_address

Optional

Valid email address of registrant, which can be used to make sure that they can receive mail at that address to acknowledge the transfer.

status

Returned if is_success = true. If no transfer is underway, this value is retrieved from the previous transfer order.

Status of the latest transfer on the domain initiated by the reseller.

Note: Resellers can only request status for transfers that they initiated (any checks for transfers initiated by other resellers returns 'undef').

  • pending_owner—Awaiting approval by domain's admin contact (every transfer begins with this status). If approval is not given within five days, the transfer is cancelled by OpenSRS.

  • pending_admin—Waiting for approval by OpenSRS support staff.

  • pending_registry—Awaiting registry approval (the transfer completes after 7 days unless it is declined by the current registrar). If the Registry shows OpenSRS as the Registrar of record, OpenSRS schedules the completion of gTLD transfers. The transfer will be scheduled to complete within 5 minutes of the query.

  • completed—The transfer completed successfully.

  • cancelled—The reseller or OpenSRS stopped the transfer.

  • undef—No transfer exists for this domain.

timestamp

Returned if is_success = true. If no transfer is currently underway, timestamp is retrieved from the previous transfer order.

The date and time of the most recent update to the state of the transfer (which could be placement of an order, an owner request, an owner confirmation, a registry request, or completion/cancellation of an order).

Date format is DD MMM YYYY 00:00:00 GMT

transferrable

Included only when a transfer request has not been submitted for the specified domain

Whether the domain can be transferred.

  • 0—Cannot be transferred

  • 1—Can be transferred

type

Returned if is_success = true and transferrable = 1

Type of transfer initiated:

  • reg2reg—Transfer from one registrar to another.

  • rsp2rsp—Transfer between two resellers of the same registrar.

unixtime

Returned if is_success = true. If no transfer is currently underway, unixtime is retrieved from the previous transfer order.

Conversion of timestamp, in seconds since Epoch (1 Jan 1970 00:00:00 GMT).

Examples for check_transfer

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="action">CHECK_TRANSFER</item>
                <item key="object">DOMAIN</item>
                <item key="attributes">
                    <dt_assoc>
                        <item key="domain">example.com</item>
                        <item key="check_status">1</item>
                        <item key="get_request_address">1</item>
                    </dt_assoc>
                </item>
            </dt_assoc>
        </data_block>
    </body>
</OPS_envelope>

Response 1

Indicates that the transfer is awaiting approval by domain's admin contact .

ERROR

Response 2

Indicates that the transfer was successful. The status shows pending_registry because a cronjob needs to run to complete the transfer process; however, running the check transfer command causes the transfer to complete within 5 minutes.

<?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="action">REPLY</item>
                <item key="object">DOMAIN</item>
                <item key="is_success">1</item>
                <item key="response_code">200</item>
                <item key="response_text">Query successful. Transfer scheduled in 5 minutes.</item>
                <item key="attributes">
                    <dt_assoc>
                        <item key="transferrable">0</item>
                        <item key="noservice">0</item>
                        <item key="timestamp">Thu Jun 14 11:05:34 2012</item>
                        <item key="status">pending_registry</item>
                        <item key="reason">Transfer in progress</item>
                        <item key="unixtime">1339686334</item>
                        <item key="request_address">requester@example.com</item>
                    </dt_assoc>
                </item>
            </dt_assoc>
        </data_block>
    </body>
</OPS_envelope>

Response 3

This response indicates that the transfer request completed and the domain is now with OpenSRS.

<?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="is_success">1</item>
                <item key="response_text">Query successful</item>
                <item key="action">REPLY</item>
                <item key="response_code">200</item>
                <item key="attributes">
                    <dt_assoc>
                        <item key="transferrable">0</item>
                        <item key="reason_code">domain_already_belongs_to_current_reseller</item>
                        <item key="noservice">0</item>
                        <item key="timestamp">Mon Jun 18 15:15:25 2012</item>
                        <item key="status">completed</item>
                        <item key="reason">Domain already exists in RESELLER_NAME's account</item>
                        <item key="unixtime">1340046925</item>
                        <item key="request_address">requester@example.com</item>
                    </dt_assoc>
                </item>
            </dt_assoc>
        </data_block>
    </body>
</OPS_envelope>

check_transfer

Checks to see if the specified domain can be transferred in to OpenSRS, or from one OpenSRS reseller to another. This call can also be used to check the status of the last transfer request on a given domain name.

When you use the check_transfer action prior to initiating a transfer, the transferable response parameter is most relevant, and if transferable = 0, the reason field is also important.

When you use the check_transfer action to determine the progress of a transfer, the status parameter is most important. If the response indicates that the transfer is in progress and the status is pending_registry, the transfer will be scheduled to complete within 5 minutes of the query; running the query expedites the process and causes the transfer to complete within 5 minutes.