Registrar API

Check domain

This API endpoint has stricter limits in place to avoid a high volume of requests. This endpoint should be used only to check a domain’s state before issuing a domain registration or a domain transfer. For other use cases, we recommend using other services like Domainr.

Checks a domain name for availability.

GET /:account/registrar/domains/:domain/check

Parameters

Name Type Description
:account integer The account id
:domain string The domain name

Example

Check the domain example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -X GET \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/check

Response

Responds with HTTP 200 on success, returns the domain availability information.

{
  "data": {
    "domain": "ruby.codes",
    "available": true,
    "premium": true
  }
}

If the domain is premium (premium: true), please check the premium price before to try to register, renew, transfer.

Errors

Responds with HTTP 400 if the domain availability cannot be checked.

Responds with HTTP 401 in case of authentication issues.

Check domain premium price

Deprecated in favor of getDomainPrices.

Get the premium price for a domain.

GET /:account/registrar/domains/:domain/premium_price

Please note that a premium price can be different for registration, renewal, transfer. By default this endpoint returns the premium price for registration. If you need to check a different price, you should specify it with the action param.

Parameters

Name Type Description
:account integer The account id
:domain string The domain name

Input

Name Type Description
action string Optional action between "registration", "renewal", and "transfer". If omitted, it defaults to "registration".

Examples

Check the premium price for example.com domain:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -X GET \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/premium_price

Check the premium price for example.com domain renewal:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -X GET \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/premium_price?action=renewal

Response

Responds with HTTP 200 on success, returns the domain premium price.

{
  "data": {
    "premium_price": "109.00",
    "action": "registration"
  }
}

Responds with HTTP 400, if the domain isn’t premium.

{
  "message": "`example.com` is not a premium domain for registration"
}

Retrieve domain prices

Get a domain’s price for registration, renewal, and transfer.

This endpoint is currently in Public Preview. During the Preview, period changes may occur at any time.

Consider using our official clients to reduce the likelihood of breaking changes. If you are using or planning to use this endpoint we'd like to hear your feedback.

GET /:account/registrar/domains/:domain/prices

Parameters

Name Type Description
:account integer The account id
:domain string The domain name

Examples

Check the registration, renewal, and transfer price for example.com domain:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -X GET \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/prices

Response

Responds with HTTP 200 on success, returns the domain pricing for registration, renewal, and transfer if the domain is premium.

{
  "data": {
    "domain": "bingo.pizza",
    "premium": true,
    "registration_price": 20.0,
    "renewal_price": 20.0,
    "transfer_price": 20.0,
    "restore_price": 20.0
  }
}

Responds with HTTP 400, if the domain TLD is not supported.

Errors

Responds with HTTP 400 if the TLD is not supported or the price cannot be checked.

Responds with HTTP 401 in case of authentication issues.

Register a domain

POST /:account/registrar/domains/:domain/registrations

Register a domain name with DNSimple.

Your account must be active for this command to complete successfully. You will be automatically charged the registration fee upon successful registration, so please be careful with this command.

When registering a domain using Solo or Teams subscription, the DNS services for the zone will be automatically enabled. This will be charged on your following subscription renewal invoices.

Parameters

Name Type Description
:account integer The account id
:domain string The domain name

Example

Register the domain example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X POST \
      -d '<json>' \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/registrations

Input

Name Type Description
registrant_id integer Required. The ID of an existing contact in your account.
whois_privacy bool Set to true will attempt to purchase/enable the whois privacy as part of the registration. An extra cost may apply. Default: false.
linked_provider string When set to the nickname of a linked provider, registration of the domain will go through that provider. Otherwise, registration of the domain will go through DNSimple.
auto_renew bool Set to true to enable the auto-renewal of the domain. Default: false.
extended_attributes hash Required for TLDs that require extended attributes.
premium_price string Required as confirmation of the price, only if the domain is premium.

The registrant_id can be fetched via the contacts endpoint and will be the registered contact for this domain.

The premium_price can be fetched via the prices endpoint.

Example
{
  "registrant_id": 1
}

Response

Responds with HTTP 201 when registration was processed and completed.

Responds with HTTP 202 when registration was processed but is pending completion.

{
  "data": {
    "id": 1,
    "domain_id": 999,
    "registrant_id": 2,
    "period": 1,
    "state": "new",
    "auto_renew": false,
    "whois_privacy": false,
    "created_at": "2016-12-09T19:35:31Z",
    "updated_at": "2016-12-09T19:35:31Z"
  }
}

Errors

Responds with HTTP 400 if the domain cannot be registrered.

Responds with HTTP 401 in case of authentication issues.

Responds with HTTP 402 if the account has outstanding payments.

Retrieve a Domain Registration

Retrieves the details of an existing domain registration.

GET /:account/registrar/domains/:domain/registrations/:domain_registration

Parameters

Name Type Description
:account integer The account id
:domain string The domain name
:domain_registration integer The domain registration id

Example

Get the domain registration with ID 361 in the account 1010 for the domain example.com:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/registrations/361

Response

Responds with HTTP 200 on success.

{
  "data": {
    "id": 361,
    "domain_id": 104040,
    "registrant_id": 2715,
    "period": 1,
    "state": "registering",
    "auto_renew": false,
    "whois_privacy": false,
    "created_at": "2023-01-27T17:44:32Z",
    "updated_at": "2023-01-27T17:44:40Z"
  }
}

Errors

Responds with HTTP 401 in case of authentication issues.

Transfer a domain

POST /:account/registrar/domains/:domain/transfers

Transfer a domain name from another domain registrar into DNSimple.

Your account must be active for this command to complete successfully. You will be automatically charged the 1-year transfer fee upon successful transfer, so please be careful with this command. The transfer may take anywhere from a few minutes up to 7 days.

When transfering a domain using Solo or Teams subscription, the DNS services for the zone will be automatically enabled. This will be charged on your following subscription renewal invoices.

Parameters

Name Type Description
:account integer The account id
:domain string The domain name

Example

Transfer the domain example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X POST \
      -d '<json>' \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/transfers

Input

Name Type Description
registrant_id integer Required. The ID of an existing contact in your account.
auth_code string Required for TLDS that require authorization-based transfer (the vast majority of TLDs).
whois_privacy bool Set to true will attempt to purchase/enable the whois privacy as part of the transfer. An extra cost may apply. Default: false.
auto_renew bool Set to true to enable the auto-renewal of the domain. Default: false.
extended_attributes hash Required for TLDs that require extended attributes.
premium_price string Required as confirmation of the price, only if the domain is premium.
Example
{
  "registrant_id": 1,
  "auth_code": "xjfjfjvhc293"
}
Example with extended attributes
{
  "registrant_id": 1,
  "auth_code": "xjfjfjvhc293",
  "extended_attribute": {
    "us_nexus": "C11",
    "us_purpose": "P3"
  }
}

Response

Responds with HTTP 201 when transfer was processed and completed.

Responds with HTTP 202 when transfer was processed but is pending completion.

{
  "data": {
    "id": 1,
    "domain_id": 999,
    "registrant_id": 2,
    "state": "transferring",
    "auto_renew": false,
    "whois_privacy": false,
    "created_at": "2016-12-09T19:43:41Z",
    "updated_at": "2016-12-09T19:43:43Z"
  }
}

Errors

Responds with HTTP 400 if the domain transfer cannot be initiated.

Responds with HTTP 401 in case of authentication issues.

Responds with HTTP 402 if the account has outstanding payments.

Retrieve a Domain Transfer

Retrieves the details of an existing domain transfer.

GET /:account/registrar/domains/:domain/transfers/:domain_transfer

Parameters

Name Type Description
:account integer The account id
:domain string The domain name
:domain_transfer integer The domain transfer id

Example

Get the domain transfer with ID 361 in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/transfers/361

Response

Responds with HTTP 200 on success.

{
  "data": {
    "id": 361,
    "domain_id": 182245,
    "registrant_id": 2715,
    "state": "cancelled",
    "auto_renew": false,
    "whois_privacy": false,
    "status_description": "Canceled by customer",
    "created_at": "2020-06-05T18:08:00Z",
    "updated_at": "2020-06-05T18:10:01Z"
  }
}

Errors

Responds with HTTP 401 in case of authentication issues.

Cancel a Domain Transfer

Cancels an in progress domain transfer.

DELETE /:account/registrar/domains/:domain/transfers/:domain_transfer

Parameters

Name Type Description
:account integer The account id
:domain string The domain name
:domain_transfer integer The domain transfer id

Example

Cancel the in progress domain transfer with ID 361 in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -X DELETE \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/transfers/361

Response

Responds with HTTP 202 on success.

{
  "data": {
    "id": 361,
    "domain_id": 182245,
    "registrant_id": 2715,
    "state": "transferring",
    "auto_renew": false,
    "whois_privacy": false,
    "status_description": null,
    "created_at": "2020-06-05T18:08:00Z",
    "updated_at": "2020-06-05T18:08:04Z"
  }
}

Errors

Responds with HTTP 400 if the transfer cannot be canceled.

Responds with HTTP 401 in case of authentication issues.

Renew a domain

POST /:account/registrar/domains/:domain/renewals

Renew a domain name already registered with DNSimple.

Your account must be active for this command to complete successfully. You will be automatically charged the renewal fee upon successful renewal, so please be careful with this command.

Parameters

Name Type Description
:account integer The account id
:domain string The domain name

Example

Renew the domain example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X POST \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/renewals

Input

Name Type Description
period integer The number of years. Unless specified it will default to whatever value is set for the TLD.
premium_price string Required as confirmation of the price, only if the domain is premium.
Example with optional period
{
  "period": 2
}

Response

Responds with HTTP 201 when renewal was processed and completed.

Responds with HTTP 202 when renewal was processed but is pending completion.

{
  "data": {
    "id": 1,
    "domain_id": 999,
    "period": 1,
    "state": "new",
    "created_at": "2016-12-09T19:46:45Z",
    "updated_at": "2016-12-09T19:46:45Z"
  }
}

Errors

Responds with HTTP 400 if the domain cannot be renewed.

Responds with HTTP 401 in case of authentication issues.

Responds with HTTP 402 if the account has outstanding payments.

Retrieve a Domain Renewal

Retrieves the details of an existing domain renewal.

GET /:account/registrar/domains/:domain/renewals/:domain_renewal

Parameters

Name Type Description
:account integer The account id
:domain string The domain name
:domain_renewal integer The domain renewal id

Example

Get the domain renewal with ID 1 in the account 1010 for the domain example.com:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/renewals/1

Response

Responds with HTTP 200 on success.

{
  "data": {
    "id": 1,
    "domain_id": 999,
    "period": 1,
    "state": "renewed",
    "created_at": "2016-12-09T19:46:45Z",
    "updated_at": "2016-12-12T19:46:45Z"
  }
}

Errors

Responds with HTTP 401 in case of authentication issues.

Restore a domain

POST /:account/registrar/domains/:domain/restores

Restore a eligable expired domain name where your registration with DNSimple lapsed.

Your account must be active for this command to complete successfully. You will be automatically charged the restore fee upon successful restore, so please be careful with this command.

Parameters

Name Type Description
:account integer The account id
:domain string The domain name

Example

Restore the domain example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X POST \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/restores

Input

Name Type Description
premium_price string Required as confirmation of the price, only if the domain is premium.
Example with optional premium_price
{
  "premium_price": '109.00'
}

Response

Responds with HTTP 201 when restore was processed and completed.

Responds with HTTP 202 when restore was processed but is pending completion.

{
  "data": {
    "id": 43,
    "domain_id": 214,
    "state": "new",
    "created_at": "2024-02-14T14:40:42Z",
    "updated_at": "2024-02-14T14:40:42Z"
  }
}

Errors

Responds with HTTP 400 if the domain cannot be restored.

Responds with HTTP 401 in case of authentication issues.

Responds with HTTP 402 if the account has outstanding payments.

Retrieve a Domain Restore

Retrieves the details of an existing domain restore.

GET /:account/registrar/domains/:domain/restores/:domain_restore

Parameters

Name Type Description
:account integer The account id
:domain string The domain name
:domain_restore integer The domain restore id

Example

Get the domain restore with ID 1 in the account 1010 for the domain example.com:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/restores/1

Response

Responds with HTTP 200 on success.

{
  "data": {
    "id": 43,
    "domain_id": 214,
    "state": "new",
    "created_at": "2024-02-14T14:40:42Z",
    "updated_at": "2024-02-14T14:40:42Z"
  }
}

Errors

Responds with HTTP 401 in case of authentication issues.

Authorize a domain transfer out

POST /:account/registrar/domains/:domain/authorize_transfer_out

Prepare a domain for transferring out. This will unlock a domain and send the authorization code to the domain’s administrative contact.

Parameters

Name Type Description
:account integer The account id
:domain string The domain name

Example

Transfer out the domain example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X POST \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/authorize_transfer_out

Response

Responds with HTTP 204 on success.

Errors

Responds with HTTP 400 if the transfer out cannot be authorized.

Responds with HTTP 401 in case of authentication issues.