---
name: Namecom
description: Use when building domain registration, management, and DNS automation workflows. Reach for this skill when agents need to search domains, register/transfer domains, manage DNS records, handle contact verification, set up webhooks, or integrate domain operations into applications.
metadata:
    mintlify-proj: namecom
    version: "1.0"
---

# name.com Core API Skill

## Product summary

The name.com Core API is a RESTful domain management platform for registering, transferring, and managing domains, DNS records, WHOIS privacy, and email forwarding. Agents use it to build domain reseller platforms, automate domain operations, and integrate domain lifecycle management into applications.

**Key endpoints**: `POST /core/v1/domains` (register), `GET /core/v1/domains` (list), `POST /core/v1/domains:search` (search), `POST /core/v1/domains/{domainName}/records` (DNS), `POST /core/v1/notifications` (webhooks).

**Authentication**: HTTP Basic Auth with username and API token. Sandbox uses `-test` appended to username and a separate sandbox token.

**Environments**: Production (`https://api.name.com`) and Sandbox (`https://api.dev.name.com`).

**Primary docs**: https://docs.name.com

## When to use

Use this skill when:
- Building a domain search and registration flow (search → check availability → register)
- Managing DNS records, nameservers, or WHOIS privacy for existing domains
- Handling domain transfers (inbound or outbound)
- Integrating contact verification workflows (ICANN compliance)
- Setting up webhooks to track domain events (transfers, lock status, contact verification)
- Troubleshooting authentication, rate limits, or sandbox vs production issues
- Implementing idempotent operations with retries (using `X-Idempotency-Key`)

Do not use this skill for account billing, payment processing, or dashboard-only operations.

## Quick reference

### Authentication

```bash
# Sandbox (use -test username and sandbox token)
curl -u username-test:sandbox-token https://api.dev.name.com/core/v1/hello

# Production (use regular username and production token)
curl -u username:prod-token https://api.name.com/core/v1/hello
```

### Core domain operations

| Task | Endpoint | Method |
|------|----------|--------|
| Search domains | `POST /core/v1/domains:search` | POST |
| Check availability | `POST /core/v1/domains:checkAvailability` | POST |
| Register domain | `POST /core/v1/domains` | POST |
| List domains | `GET /core/v1/domains` | GET |
| Get domain details | `GET /core/v1/domains/{domainName}` | GET |
| Update domain (lock, autorenew, privacy) | `PATCH /core/v1/domains/{domainName}` | PATCH |
| Renew domain | `POST /core/v1/domains/{domainName}:renew` | POST |
| Set nameservers | `POST /core/v1/domains/{domainName}:setNameservers` | POST |
| Set contacts | `POST /core/v1/domains/{domainName}:setContacts` | POST |

### DNS management

| Task | Endpoint | Method |
|------|----------|--------|
| List DNS records | `GET /core/v1/domains/{domainName}/records` | GET |
| Create DNS record | `POST /core/v1/domains/{domainName}/records` | POST |
| Update DNS record | `PUT /core/v1/domains/{domainName}/records/{id}` | PUT |
| Delete DNS record | `DELETE /core/v1/domains/{domainName}/records/{id}` | DELETE |

### Contact verification

| Task | Endpoint | Method |
|------|----------|--------|
| List unverified contacts | `GET /core/v1/contacts/unverified` | GET |
| Verify contact | `POST /core/v1/contacts/verify/{verificationId}` | POST |
| Resend verification email | `POST /core/v1/contacts/verify/{verificationId}:resend` | POST |

### Webhooks

| Task | Endpoint | Method |
|------|----------|--------|
| Subscribe to event | `POST /core/v1/notifications` | POST |
| List subscriptions | `GET /core/v1/notifications` | GET |
| Modify subscription | `PATCH /core/v1/notifications/{id}` | PATCH |
| Delete subscription | `DELETE /core/v1/notifications/{id}` | DELETE |

### Rate limits

- **20 requests per second**
- **3,000 requests per hour**
- Exceeding limits returns `429 Too Many Requests`

## Decision guidance

### When to use sandbox vs production

| Scenario | Use |
|----------|-----|
| Testing registration flows, DNS changes, webhooks | Sandbox (`https://api.dev.name.com`) |
| Real domain registrations, live billing | Production (`https://api.name.com`) |
| Validating request/response shapes before launch | Sandbox |
| Final end-to-end verification before go-live | Production (limited test) |

**Key difference**: Sandbox data does not sync with production. Domains created in sandbox only exist in sandbox. DNS changes in sandbox are stored but not publicly resolvable.

### When to use search vs check availability

| Scenario | Use |
|----------|-----|
| Show purchasable domains to user | `POST /core/v1/domains:search` |
| Confirm domain is still available at checkout | `POST /core/v1/domains:checkAvailability` |
| Capture definitive purchase price before billing | `POST /core/v1/domains:checkAvailability` |

Always call `checkAvailability` before `Create Domain` to prevent failed purchases due to availability changes.

### When to use reseller contacts vs end-customer contacts

| Scenario | Use |
|----------|-----|
| Fast MVP (set reseller as domain contact) | Reseller contacts (your account) |
| Whitelabeled experience (customer sees their own contact) | End-customer contacts (requires setup) |

End-customer contacts require additional verification setup and support overhead. Use reseller contacts for MVP, upgrade later if needed.

## Workflow

### Typical domain registration flow

1. **Search**: Call `POST /core/v1/domains:search` with `purchaseType: "registration"` to show available domains and pricing.
2. **Pre-check**: Call `POST /core/v1/domains:checkAvailability` at checkout to confirm availability and capture `purchasePrice`.
3. **Register**: Call `POST /core/v1/domains` with `X-Idempotency-Key` header (safe retries). Set `autorenewEnabled: true`, `locked: true`, `privacyEnabled: true` as defaults.
4. **Verify contacts**: Call `GET /core/v1/contacts/unverified` to check if contact verification is required. Monitor with webhook `contact.verification.status_change` or poll every 10 minutes.
5. **Configure DNS**: Call `POST /core/v1/domains/{domainName}/records` to create DNS records, or `POST /core/v1/domains/{domainName}:setNameservers` to use external DNS.
6. **Monitor**: Subscribe to webhooks (`domain.transfer.status_change`, `domain.lock.status_change`) to track domain events without polling.

### Typical webhook integration

1. **Subscribe**: Call `POST /core/v1/notifications` with `eventName` (e.g., `"domain.transfer.status_change"`) and your callback URL.
2. **Verify signature**: On webhook receipt, verify `X-NAMECOM-SIGNATURE` header using HMAC-SHA256 with your API token.
3. **Process event**: Update your database with the domain state from the webhook payload.
4. **Respond**: Return HTTP 2xx to acknowledge receipt. name.com retries on 4xx/5xx.

### Typical contact verification flow

1. **Register domain**: After `POST /core/v1/domains`, contacts may be unverified.
2. **Check status**: Call `GET /core/v1/contacts/unverified` to see pending verifications (may take ~10 minutes to appear).
3. **Monitor**: Subscribe to `contact.verification.status_change` webhook or poll every 10 minutes.
4. **Alert user**: If unverified after 15 days, a verification lock is applied and the domain stops resolving.
5. **Resend email**: Call `POST /core/v1/contacts/verify/{verificationId}:resend` if user didn't receive the initial email (throttled to 1 per 15 minutes per contact).

## Common gotchas

- **Do not URL-encode the colon** in endpoints like `POST /core/v1/domains:search` and `POST /core/v1/domains:checkAvailability`. Some HTTP clients auto-encode `:` to `%3A`, which fails.

- **Always send `X-Idempotency-Key`** on `POST /core/v1/domains` (register) and `POST /core/v1/refund` (refund). Retrying without the key can double-charge or double-refund.

- **Sandbox domains must be registered before use**. Calling `GET /core/v1/domains/example.com/records` returns 404 if the domain doesn't exist in sandbox. Register it first.

- **DNS changes in sandbox are not publicly resolvable**. You can create and retrieve DNS records in sandbox, but `dig` and `nslookup` won't resolve them. Test your API request/response handling, not public DNS resolution.

- **Contact verification takes ~10 minutes to appear**. After registering a domain, unverified contacts may not appear in `GET /core/v1/contacts/unverified` for up to 10 minutes. Build UI with this delay in mind.

- **Verification locks apply after 15 days**. If contacts are not verified within 15 days of registration or contact change, a verification lock is applied and the domain stops resolving. Monitor with webhooks or polling.

- **Premium domain pricing differs in sandbox**. Sandbox pricing (especially premium and account-specific pricing) is non-authoritative. Validate production pricing before launch.

- **Sandbox credentials take up to 15 minutes to activate**. If you get 401 immediately after creating a sandbox token, wait and retry.

- **2FA blocks API access by default**. If your account has 2FA enabled, go to Account Settings → Security and toggle "name.com API Access" on.

- **Mixing production/sandbox credentials fails**. Ensure your API URL matches your credentials (production URL with production token, sandbox URL with sandbox token).

- **Rate limit is 20 req/sec, 3,000 req/hour**. Implement exponential backoff on 429 responses. Retry after a delay (e.g., 1s, 2s, 4s, 8s).

- **Webhook signature verification is required**. Always verify `X-NAMECOM-SIGNATURE` using HMAC-SHA256 with your API token. Use timing-safe comparison to prevent timing attacks.

- **Transfers are not deterministic in sandbox**. Sandbox transfer outcomes are driven by registry OT&E behavior and may not be predictable. Validate transfer logic in production.

- **Domain locks prevent operations**. Verification locks, compliance locks, and transfer locks restrict different operations. Check the domain's lock status before attempting transfers or modifications.

## Verification checklist

Before submitting domain registration or management work:

- [ ] Authenticated with correct credentials (production vs sandbox)
- [ ] Used `X-Idempotency-Key` on all POST create/refund operations
- [ ] Called `checkAvailability` before registering to confirm availability and price
- [ ] Set `autorenewEnabled: true`, `locked: true`, `privacyEnabled: true` as defaults on registration
- [ ] Verified webhook signature using HMAC-SHA256 if handling webhooks
- [ ] Checked contact verification status and set up monitoring (webhook or polling)
- [ ] Tested DNS record creation/update/delete in sandbox before production
- [ ] Implemented retry/backoff logic for 429 rate limit responses
- [ ] Confirmed domain exists in the current environment (sandbox vs production)
- [ ] Validated that colon (`:`) in endpoints is not URL-encoded

## Resources

**Comprehensive navigation**: https://docs.name.com/llms.txt

**Critical pages**:
- [Getting Started](https://docs.name.com/guides/getting-started) — Create tokens, authenticate, make first API call
- [Quickstart](https://docs.name.com/guides/quickstart) — Complete MVP flow (search → register → manage)
- [API Overview](https://docs.name.com/api/v1/overview) — Rate limits, error formats, authentication details

---

> For additional documentation and navigation, see: https://docs.name.com/llms.txt