The name.com API quickstart guide: From API token to registered domain

It wasn’t long ago that domain registration APIs treated the developer integration as an afterthought. They were XML-heavy, sparsely documented, and built around workflows that made sense in 2007. The name.com Core API takes a different approach, offering a RESTful interface with an OpenAPI 3.1 spec, HTTP Basic Auth, and a sandbox that mirrors production exactly.

By the end of this guide, you'll have a sandbox-tested flow from token generation to a registered domain with a live DNS record, all using core/v1 endpoints. Once this path works in sandbox, flipping to production is a credentials swap, not a rewrite.

This is a written tutorial for registering your first domain via the name.com API. You can also check out our Reseller Quickstart MVP Flow in our documentation if you’re building domain services into your own app.

1. Generate your API token

Log in to your name.com account, click the user icon in the top right, and select Settings. Under the Security section, click API Tokens, then Create API Token. Accept the API Access Agreement, name your token, and click Generate new token.

The flow issues two tokens at once, one for Production and one for the Development/Test Environment (sandbox). Keep them in separate environment variables from day one, because mixing them up is the most common mistake in early testing. You'll use the sandbox token throughout this guide.

If you have two-factor authentication (2FA) enabled on your account, note that our API does not support 2FA. You'll need to enable the NAME.COM API ACCESS toggle under Settings → Security → Security Settings, which allows API requests to authenticate without the 2FA security token. Without this, neither token will work regardless of whether they were generated correctly.

You can optionally whitelist specific IP addresses on the token to restrict API access, which is useful for production deployments but unnecessary in local development. Your API credential is the token itself (your account password won't authenticate API requests).

2. Authenticate and verify the connection

The name.com Core API uses HTTP Basic Auth, where your username is your name.com account username and your password is the API token. In the sandbox, append -test to your username, so acme becomes acme-test. The sandbox base URL is https://api.dev.name.com.

Before you write any integration code, verify the connection with a call to /core/v1/hello. The cURL example below uses the -u shorthand for credentials.

curl --request GET \
  --url https://api.dev.name.com/core/v1/hello \
  -u "acme-test:your-sandbox-token"

A 200 OK response confirms the connection. Don't proceed until you see it.

{
  "motd":"Welcome to Core API from Name.com","serverName":"b7bb","serverTime":"2026-08-10T19:00:20Z","username":acme-test"}

If you're using a non-cURL client, construct the Authorization header manually by Base64-encoding username:token.

# Generate the Base64 value on Linux/macOS:
echo -n 'acme-test:your-sandbox-token' | base64

# Then pass it as a header:
curl --request GET \
  --url https://api.dev.name.com/core/v1/hello \
  --header 'Authorization: Basic <your-base64-value>'

In Python, the requests library handles Base64 encoding automatically.

import requests

response = requests.get(
    "https://api.dev.name.com/core/v1/hello",
    auth=("acme-test", "your-sandbox-token")
)
print(response.status_code, response.json())

Newly generated sandbox credentials can take up to 15 minutes to activate. If you're getting auth errors immediately after token generation, wait a few minutes and retry. Railway's integration was built by a product engineer using an AI coding agent with our API documentation as the primary reference, covering everything from domain search and purchasing to transfers, billing, and custom nameservers.

3. Check domain availability

Before you attempt registration, confirm the domain is purchasable. POST /core/v1/domains:search accepts a keyword and optional TLD filter. Set purchaseType to registration to restrict results to domains available for registration.

curl --request POST \
  --url https://api.dev.name.com/core/v1/domains:search \
  --user "acme-test:your-sandbox-token" \
  --header "Content-Type: application/json" \
  --data '{
    "keyword": "myapp",
    "tldFilter": ["com"],
    "purchaseType": "registration"
  }'

The response returns an array of results. Check the purchasable field on each result: true means the domain can be purchased through the registration flow. Skip any result where purchasable is false.

One thing to watch is that the search response may include a purchasePrice field. For standard (non-premium) .com registrations, you don't need to pass this value to the Create Domain call. Premium registrations are different: the purchasePrice returned by the availability check must be included when registering the domain. For a production checkout flow, perform an availability check immediately before registration so you can confirm the domain is still purchasable and use the current purchase type and price.

Run an availability check before attempting registration, but still handle registration failures because availability can change between the search and registration requests.

4. Register the domain

POST /core/v1/domains accepts the domain name, registration period, and optional contact information. Contact requirements vary by TLD, and country-code domains can have additional requirements. For this .com-focused quick start, we'll explicitly provide the same contact for all four roles: registrant, admin, tech, and billing.

curl --request POST \ 
  --url https://api.dev.name.com/core/v1/domains \ 
  --user "acme-test:your-sandbox-token" \ 
  --header "Content-Type: application/json" \ 
  --header "X-Idempotency-Key: somekey" \ 
  --data '{
    "domain": {
        "domainName": "example-sandbox.com",
        "purchaseType": "registration",
        "years": 1,
        "contacts": {
            "registrant": {
                "firstName": "Jane",
                "lastName": "Doe",
                "companyName": "Acme Corp",
                "address1": "123 Main St",
                "city": "Denver",
                "state": "CO",
                "zip": "80203",
                "country": "US",
                "phone": "+1.5555550100",
                "email": "jane@acmecorp.com"
            },
            "admin": {
                "firstName": "Jane",
                "lastName": "Doe",
                "companyName": "Acme Corp",
                "address1": "123 Main St",
                "city": "Denver",
                "state": "CO",
                "zip": "80203",
                "country": "US",
                "phone": "+1.5555550100",
                "email": "jane@acmecorp.com"
            },
            "tech": {
                "firstName": "Jane",
                "lastName": "Doe",
                "companyName": "Acme Corp",
                "address1": "123 Main St",
                "city": "Denver",
                "state": "CO",
                "zip": "80203",
                "country": "US",
                "phone": "+1.5555550100",
                "email": "jane@acmecorp.com"
            },
            "billing": {
                "firstName": "Jane",
                "lastName": "Doe",
                "companyName": "Acme Corp",
                "address1": "123 Main St",
                "city": "Denver",
                "state": "CO",
                "zip": "80203",
                "country": "US",
                "phone": "+1.5555550100",
                "email": "jane@acmecorp.com"
            }
        }
    }
}'

A successful response returns the registered domain and its status details. In the sandbox, register the domain before attempting to manage its DNS records: DNS operations apply to domains that exist in the sandbox account.

The X-Idempotency-Key header helps make retries safe if the request times out or the connection fails after the registration has been submitted. Use a unique value for each intended registration.

The Python equivalent below uses the same contact object for all four roles.

import requests
import uuid

contact = {
    "firstName": "Jane",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "address1": "123 Main St",
    "city": "Denver",
    "state": "CO",
    "zip": "80203",
    "country": "US",
    "phone": "+1.5555550100",
    "email": "jane@acmecorp.com"
}

payload = {
    "domain": {
        "domainName": "example-sandbox.com",
        "purchaseType": "registration",
        "years": 1,
        "contacts": {
            "registrant": contact,
            "admin": contact,
            "tech": contact,
            "billing": contact
        }
    }
}

response = requests.post(
    "https://api.dev.name.com/core/v1/domains",
    auth=("acme-test", "your-sandbox-token"),
    headers={"X-Idempotency-Key": str(uuid.uuid4())},
    json=payload
)

print(response.status_code, response.json())

You don't necessarily need to provide all four contacts. If no contacts are supplied, we can use the default contacts configured on the account. Providing all four explicitly here keeps the example self-contained and makes the contact roles clear.

The registration call looks detailed, but it can be integrated quickly. Hercules went from API key to production in three days, using AI coding agents and our OpenAPI specification to accelerate its integration.

For the full endpoint reference, see Create Domain in the name.com API documentation.

5. Add a DNS record

With the domain registered in sandbox, you can create DNS records against it, giving you an immediately verifiable result. POST /core/v1/domains/{domainName}/records creates a DNS record. The example below creates an A record pointing the apex domain to a documentation IP, then confirms that the record exists.

# Create an A record
curl --request POST \
  --url https://api.dev.name.com/core/v1/domains/example-sandbox.com/records \
  --user "acme-test:your-sandbox-token" \
  --header "Content-Type: application/json" \
  --data '{
    "host": "@",
    "type": "A",
    "answer": "203.0.113.1",
    "ttl": 300
  }'

# Confirm the record exists
curl --request GET \
  --url https://api.dev.name.com/core/v1/domains/example-sandbox.com/records \
  --user "acme-test:your-sandbox-token"

The GET returns the DNS records for the domain. If your new A record appears in that response, the registration-to-DNS API flow is working end-to-end. This confirms that the record was successfully created; it does not by itself verify DNS propagation or resolution.

Riley & Grey uses a similar sandbox-first approach in its production integration. Their Rails application records sandbox API responses with the VCR gem, allowing the team to run its automated tests without repeatedly hitting live API endpoints. The team also credits our sandbox environment with making it quick to validate integration changes before deploying them to production.

For the full reference on the DNS create endpoint, see Create DNS Record.

What you've built

You now have a working sandbox flow from API token to registered domain with DNS. Generate a token, verify authentication against /core/v1/hello, check availability with /core/v1/domains:search, register with /core/v1/domains, and create and verify DNS records with /core/v1/domains/{domainName}/records.

Moving to production primarily means switching to your production credentials and endpoint. Before going live, test your integration against production-specific availability, pricing, supported TLDs, and account configuration. From there, our API gives you renewals, WHOIS privacy purchase and management, nameserver configuration, and other domain lifecycle operations through the same core/v1 API.

For production-scale patterns, the name.dev case studies from Hercules, Railway, Riley & Grey, and Beacons show how teams have shipped domain registration as a native product feature.

Ready to ship domain registration to your users? Start for free at name.com/nameapi, or talk to our team about custom pricing and direct collaboration at name.com/nameapi/contact.