Search... ⌘ K
Get Started Contact Sales

Getting Started With the DNSimple Sandbox

Table of Contents

This tutorial walks you through making your first API calls to the DNSimple Sandbox with curl: verifying your token, creating, listing, and updating DNS records, and checking domain availability. The same endpoints and request formats work with any HTTP client or DNSimple client library. The Sandbox also has a full web interface. This tutorial covers the API.

Video walk-through

1. Prerequisites

Before you begin, ensure you have:

Set your token and account ID as environment variables so you can copy and paste the examples directly:

export DNSIMPLE_TOKEN=your_sandbox_token_here
export DNSIMPLE_ACCOUNT_ID=your_account_id_here

Warning

Never commit API tokens to version control or share them publicly.

2. Verifying your setup

Confirm your token works by calling the whoami endpoint:

curl -H "Authorization: Bearer $DNSIMPLE_TOKEN" \
     -H "Accept: application/json" \
     https://api.sandbox.dnsimple.com/v2/whoami

A successful response returns your account details:

{
  "data": {
    "user": null,
    "account": {
      "id": 12345,
      "email": "you@example.com",
      "plan_identifier": "solo-v2-monthly",
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T10:30:00Z"
    }
  }
}

The account.id value is the account ID you will use in all subsequent API calls. If you do not already have it, copy it from this response.

Note

If you use a user token instead of an account token, whoami returns your user and "account": null. To find the account ID, list the accounts your user can access:

curl -H "Authorization: Bearer $DNSIMPLE_TOKEN" \
     -H "Accept: application/json" \
     https://api.sandbox.dnsimple.com/v2/accounts

3. Creating DNS records

Add a domain to your Sandbox account through the web interface or the API. This adds the domain to the account without registering it:

curl -H "Authorization: Bearer $DNSIMPLE_TOKEN" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"name":"example.com"}' \
     https://api.sandbox.dnsimple.com/v2/$DNSIMPLE_ACCOUNT_ID/domains

Note

If creating the domain fails because the name is already taken, use a different name. The Sandbox is a shared system.

Then create DNS records for it. This example creates an A record pointing the apex domain to an IP address:

curl -H "Authorization: Bearer $DNSIMPLE_TOKEN" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"name":"","type":"A","content":"192.0.2.1","ttl":3600}' \
     https://api.sandbox.dnsimple.com/v2/$DNSIMPLE_ACCOUNT_ID/zones/example.com/records

A successful response returns HTTP 201 with the created record:

{
  "data": {
    "id": 1,
    "zone_id": "example.com",
    "parent_id": null,
    "name": "",
    "content": "192.0.2.1",
    "ttl": 3600,
    "priority": null,
    "type": "A",
    "regions": ["global"],
    "system_record": false,
    "created_at": "2026-03-18T12:00:00Z",
    "updated_at": "2026-03-18T12:00:00Z"
  }
}

Create additional records the same way. For example, a www A record and an MX record:

curl -H "Authorization: Bearer $DNSIMPLE_TOKEN" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"name":"www","type":"A","content":"192.0.2.1","ttl":3600}' \
     https://api.sandbox.dnsimple.com/v2/$DNSIMPLE_ACCOUNT_ID/zones/example.com/records

curl -H "Authorization: Bearer $DNSIMPLE_TOKEN" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"name":"","type":"MX","content":"mail.example.com","ttl":3600,"priority":10}' \
     https://api.sandbox.dnsimple.com/v2/$DNSIMPLE_ACCOUNT_ID/zones/example.com/records

4. Listing and filtering records

Retrieve all records for a zone:

curl -H "Authorization: Bearer $DNSIMPLE_TOKEN" \
     -H "Accept: application/json" \
     https://api.sandbox.dnsimple.com/v2/$DNSIMPLE_ACCOUNT_ID/zones/example.com/records

The list includes the SOA and NS records that DNSimple creates for every zone, marked "system_record": true, alongside the records you created.

Filter by record type or name using query parameters:

curl -H "Authorization: Bearer $DNSIMPLE_TOKEN" \
     -H "Accept: application/json" \
     "https://api.sandbox.dnsimple.com/v2/$DNSIMPLE_ACCOUNT_ID/zones/example.com/records?type=A&name="

The response includes pagination metadata. See DNSimple API Best Practices for how to handle paginated results.

5. Updating a DNS record

Update an existing record by its ID. This example changes the IP address of an A record. Replace RECORD_ID with the id value from a previous response:

curl -H "Authorization: Bearer $DNSIMPLE_TOKEN" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d '{"content":"198.51.100.1"}' \
     https://api.sandbox.dnsimple.com/v2/$DNSIMPLE_ACCOUNT_ID/zones/example.com/records/RECORD_ID

Tip

In a CI/CD pipeline, you can script these curl commands to update DNS records automatically after deployment.

6. Checking domain availability

The registrar API lets you check whether a domain is available for registration:

curl -H "Authorization: Bearer $DNSIMPLE_TOKEN" \
     -H "Accept: application/json" \
     https://api.sandbox.dnsimple.com/v2/$DNSIMPLE_ACCOUNT_ID/registrar/domains/example-check.com/check

The response indicates availability:

{
  "data": {
    "domain": "example-check.com",
    "available": true,
    "premium": false
  }
}

Note

Sandbox domain checks run against registry OT&E environments. Results may not match production availability. See Sandbox Common Pitfalls for details.

7. Moving to production

When your integration works in the Sandbox, switching to production requires two changes:

  1. Update the base URL: Change api.sandbox.dnsimple.com to api.dnsimple.com.
  2. Update your API token: Replace your Sandbox token with a production API access token. A Sandbox token does not work in production, and production returns 401 with Authentication failed.
# Sandbox
curl -H "Authorization: Bearer $DNSIMPLE_SANDBOX_TOKEN" \
     https://api.sandbox.dnsimple.com/v2/whoami

# Production
curl -H "Authorization: Bearer $DNSIMPLE_TOKEN" \
     https://api.dnsimple.com/v2/whoami

For the complete API reference, visit the DNSimple Developer Documentation. For tips on avoiding common mistakes, see Sandbox Common Pitfalls and DNSimple API Best Practices.

Have more questions?

If you have additional questions or need any assistance with the DNSimple Sandbox, contact support, and we’ll be happy to help.