Getting Started With the DNSimple Sandbox

Table of Contents

• 1. Prerequisites
• 2. Verifying your setup
• 3. Creating DNS records
• 4. Listing and filtering records
• 5. Updating a DNS record
• 6. Checking domain availability
• 7. Moving to production
• Have more questions?

This tutorial walks you through setting up the DNSimple Sandbox and making your first API calls to that environment. By the end, you will have hands-on experience with common API operations using curl. 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 focuses on the API path.

1. Prerequisites

Before you begin, ensure you have:

• A DNSimple Sandbox account. Sign up at sandbox.dnsimple.com.
• A Sandbox API access token. See API Access Token for instructions on generating a token.
• curl installed on your system. Most macOS and Linux systems include it by default.

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

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": "teams-v1-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.

3. Creating DNS records

Add a domain to your Sandbox account through the web interface or the API, 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",
    "name": "",
    "content": "192.0.2.1",
    "ttl": 3600,
    "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

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

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
  }
}

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.

# 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. To learn more about the Sandbox environment, see What Is the DNSimple Sandbox?. 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.