Summary

The name.com API gives developers a clean REST interface for the full domain lifecycle — authentication, availability search, registration, and DNS configuration — over standard HTTP with JSON. Python's requests library is all you need: no SDK, no XML parsing, just Basic Auth and JSON responses. This guide walks through each step with working code, covers rate limiting and error handling, and includes equivalent examples in PHP, Node.js, and Ruby so you can adapt the patterns to your stack.

If your app lets users pick a custom domain, you have two options: send them to a registrar's website and hope they come back, or handle the whole flow yourself via API. Platforms like Vercel, Replit, and Netlify chose the second path. They integrated domain search, registration, and DNS management directly into their products — and they use name.com as the backend registrar.

This guide shows you how to build the same thing. We'll work through the core domain lifecycle — authentication, availability search, registration, and DNS configuration — using the name.com API. Python with the requests library is the primary language. The same concepts apply in most programming languages, so equivalent code blocks in PHP, Node.js, and Ruby are included throughout.

Section 1: Prerequisites and Authentication

You need your name.com username and an API token. Navigate to API → API Token Management in your name.com account and generate a new token. name.com provides a separate test environment at https://api.dev.name.com — always develop against the test environment first. Accidentally registering a live domain while debugging error handling is an expensive lesson.

Bash
# .env file (add to .gitignore)
NAMECOM_USERNAME=your_username
NAMECOM_API_TOKEN=your_api_token
NAMECOM_API_URL=https://api.dev.name.com  # switch to api.name.com for production

The name.com API uses HTTP Basic Auth — your username as the username and your API token as the password. No OAuth dance, no token exchange. Here's a minimal client class that verifies your credentials:

python
import os
import requests
from dotenv import load_dotenv

load_dotenv()

class NameComClient:
    def __init__(self):
        self.base_url = os.environ["NAMECOM_API_URL"]
        self.auth = (
            os.environ["NAMECOM_USERNAME"],
            os.environ["NAMECOM_API_TOKEN"]
        )
        self.headers = {"Content-Type": "application/json"}

    def hello(self):
        """Verify credentials by calling the hello endpoint."""
        response = requests.get(
            f"{self.base_url}/core/v1/hello",
            auth=self.auth,
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

client = NameComClient()
print(client.hello())

Run this and you should see your username echoed back. If you get a 401, your token is wrong. If you get a 404, check the base URL.

Section 2: Checking Domain Availability

Domain availability is a POST call to the /domains:search endpoint. You POST a keyword, and name.com returns a list of domain suggestions with their availability status and pricing. The price data matters — some premium domains cost thousands at registration. Your code needs to handle both cases, or you'll accidentally surface $50,000 domains to users expecting a sub-$20 purchase.

python
def search_domains(self, keyword: str, tlds: list = None) -> list:
    """Search for available domains matching a keyword."""
    if tlds is None:
        tlds = ["com", "net", "org", "io"]

    payload = {
        "keyword": keyword,
        "tldFilter": tlds,
        "timeout": 10000
    }

    response = requests.post(
        f"{self.base_url}domains:search",
        auth=self.auth,
        headers=self.headers,
        json=payload
    )
    response.raise_for_status()
    data = response.json()

    results = []
    for result in data.get("results", []):
        domain_info = {
            "domain": result["domainName"],
            "available": result.get("purchasable", False),
            "price": result.get("purchasePrice", 0),
            "premium": result.get("premium", False)
        }
        if domain_info["available"]:
            results.append(domain_info)

    return results

# Usage
client = NameComClient()
results = client.search_domains("mycoolstartup")
for r in results:
    status = "[PREMIUM]" if r["premium"] else ""
    print(f"{r['domain']}: ${r['price']:.2f}/year {status}")

Section 3: Domain Registration

Registration carries more payload than the other calls — ICANN requires contacts for four roles: Registrant, Admin, Tech, and Billing. Each needs a name, organization, address, phone number, and email. In most cases these four roles would be the same person.

python
def register_domain(self, domain_name: str, contact_details: dict, years: int = 1) -> dict:
    """Register a domain."""
    payload = {
        "domain": {
            "domainName": domain_name,
            "years": years,
            "contacts": {
                "tech": {
                    "firstName": contact_details['firstName'],
                    "lastName": contact_details['lastName'],
                    "companyName": contact_details['companyName'],
                    "address1": contact_details['address1'],
                    "city": contact_details['city'],
                    "state": contact_details['state'],
                    "zip": contact_details['zip'],
                    "country": contact_details['country'],
                    "email": contact_details['email'],
                    "phone": contact_details['phone']
                }
            },
            "privacyEnabled": True
        }
    }

    try:
        response = requests.post(
            f"{self.base_url}/core/v1/domains",
            auth=self.auth,
            headers=self.headers,
            json=payload
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        raise ValueError(f"Registration failed for {domain_name}: {e.response.text}")

Section 4: Configuring DNS After Registration

After registration, the domain exists but has no DNS records configured. Add an A record to point the domain at your server:

python
def add_dns_record(self, domain: str, record_type: str, host: str, answer: str, ttl: int = 300) -> dict:
    url = f"{self.base_url}/core/v1/domains/{domain}/records"
    payload = {"host": host, "type": record_type, "answer": answer, "ttl": ttl}
    response = requests.post(url, auth=self.auth, headers=self.headers, json=payload)
    response.raise_for_status()
    return response.json()

# Complete domain provisioning workflow
client = NameComClient()

# 1. Check availability
results = client.search_domains("mycoolstartup")
if not results:
    print("No domains available")
else:
    target = results[0]
    print(f"Registering {target['domain']} for ${target['price']:.2f}/year")

    # 2. Register the domain
    contact = {"firstName": "Jane", "lastName": "Dev", "companyName": "Acme",
               "address1": "123 Main St", "city": "Austin", "state": "TX",
               "zip": "78701", "country": "US",
               "email": "jane@acme.com", "phone": "+15125551234"}
    client.register_domain(target['domain'], contact)

    # 3. Configure DNS
    client.add_dns_record(target['domain'], "A", "", "203.0.113.10")
    client.add_dns_record(target['domain'], "A", "www", "203.0.113.10")
    print(f"Done. {target['domain']} is registered and pointing to your server.")

This entire workflow — authentication, search, registration, DNS configuration — runs in under 200 lines of code. No heavy SDK to download. No XML to parse. Just HTTP calls and JSON responses.

FAQs

What is a domain registration API?

A domain registration API is a programmatic interface that lets developers search for domain availability, register domains, and manage DNS records directly within their application — without redirecting users to a registrar's website. The name.com RESTful API exposes these capabilities over standard HTTPS with JSON request and response bodies.

Which Python library should I use for the name.com domain API?

The requests library is the clearest choice for making HTTP calls to the name.com API. It handles Basic Auth in a single line and parses JSON responses natively. No SDK or domain-specific library is required.

How do I check domain availability programmatically?

Send a POST request to /core/v1/domains:search with your keyword and an optional list of TLD filters. The response includes each domain's purchasable status and purchasePrice. Filter on purchasable: true and check the premium flag before surfacing results to users — premium domains can cost orders of magnitude more than standard registrations.

What HTTP status codes should I handle from the name.com domain API?

The most important ones are: 401 Unauthorized (bad credentials), 400 Bad Request (invalid request data), 409 Conflict (domain was registered between your availability check and registration attempt), and 429 Too Many Requests (rate limit hit — implement exponential backoff).

Does the name.com API require a special SDK or client library?

No. The name.com API uses standard HTTP Basic Auth and JSON — any language with a decent HTTP library works out of the box. The examples in this guide use Python's requests, PHP's GuzzleHttp, Node.js's axios, and Ruby's Faraday. There's no proprietary SDK to install and no XML to parse.