Domains API

Domain attributes

Please refer to the definition of the Domain data type in our OpenAPI documentation.

List domains

Lists the domains in the account.

GET /:account/domains

Parameters

Name Type Description
:account integer The account ID

Filters

Name Description
:name_like Only include domains containing given string
:registrant_id Only include domains containing given registrant ID

Sorting

For general information about sorting, please refer to the main guide.

Name Description
id Sort domains by ID
name Sort domains by name (alphabetical order)
expiration Sort domains by expiration date

The default sorting policy is by ascending name.

Examples

List all domains in the account 1385:

curl  -H 'Authorization: Bearer <token>' \
        -H 'Accept: application/json' \
        https://api.dnsimple.com/v2/1385/domains

List all domains in the account 1385 that have name matching "example":

curl  -H 'Authorization: Bearer <token>' \
        -H 'Accept: application/json' \
        https://api.dnsimple.com/v2/1385/domains?name_like=example

Response

Responds with HTTP 200.

{
  "data": [
    {
      "id": 181984,
      "account_id": 1385,
      "registrant_id": 2715,
      "name": "example-alpha.com",
      "unicode_name": "example-alpha.com",
      "state": "registered",
      "auto_renew": false,
      "private_whois": false,
      "expires_on": "2021-06-05",
      "expires_at": "2021-06-05T02:15:00Z",
      "created_at": "2020-06-04T19:15:14Z",
      "updated_at": "2020-06-04T19:15:21Z"
    },
    {
      "id": 181985,
      "account_id": 1385,
      "registrant_id": null,
      "name": "example-beta.com",
      "unicode_name": "example-beta.com",
      "state": "hosted",
      "auto_renew": false,
      "private_whois": false,
      "expires_on": null,
      "expires_at": null,
      "created_at": "2020-06-04T19:47:05Z",
      "updated_at": "2020-06-04T19:47:05Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 30,
    "total_entries": 2,
    "total_pages": 1
  }
}

Errors

Responds with HTTP 401 in case of authentication issues.

Create a domain

Adds a domain to the account.

When creating 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.

POST /:account/domains

Parameters

Name Type Description
:account integer The account id

Example

Create a domain in the account 1385:

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

Input

Name Type Description
name string Required.
Example
{
  "name": "example-beta.com"
}

Response

Responds with HTTP 201 on success, renders the domain.

{
  "data": {
    "id": 181985,
    "account_id": 1385,
    "registrant_id": null,
    "name": "example-beta.com",
    "unicode_name": "example-beta.com",
    "state": "hosted",
    "auto_renew": false,
    "private_whois": false,
    "expires_on": null,
    "expires_at": null,
    "created_at": "2020-06-04T19:47:05Z",
    "updated_at": "2020-06-04T19:47:05Z"
  }
}

Errors

Responds with HTTP 400 if the registration attempt is invalid.

Responds with HTTP 401 in case of authentication issues.

Responds with HTTP 402 if the account has outstanding payments.

Retrieve a domain

Retrieves the details of an existing domain.

GET /:account/domains/:domain

Parameters

Name Type Description
:account integer The account ID
:domain string, integer The domain name or ID

Example

Get the domain with ID 181984 in the account 1385:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1385/domains/181984

Get the domain example-alpha.com in the account 1385:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1385/domains/example-alpha.com

Response

Responds with HTTP 200, renders the domain.

{
  "data": {
    "id": 181984,
    "account_id": 1385,
    "registrant_id": 2715,
    "name": "example-alpha.com",
    "unicode_name": "example-alpha.com",
    "state": "registered",
    "auto_renew": false,
    "private_whois": false,
    "expires_on": "2021-06-05",
    "expires_at": "2021-06-05T02:15:00Z",
    "created_at": "2020-06-04T19:15:14Z",
    "updated_at": "2020-06-04T19:15:21Z"
  }
}

Errors

Responds with HTTP 401 in case of authentication issues.

Delete a domain

Permanently deletes a domain from the account. It cannot be undone.

DELETE /:account/domains/:domain

For domains registered with DNSimple, this will not delete the domain from the registry or perform a refund.

Parameters

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

Example

Delete the domain with ID 1 in the account 1010:

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

Delete the domain example.com in the account 1010:

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

Response

Responds with HTTP 204 on success.

Errors

Responds with HTTP 400 if the domain cannot be deleted.

Responds with HTTP 401 in case of authentication issues.