# Changelog
Source: https://docs.name.com/api/v1/changelog
name.com CORE API updates and announcements
### Changed
* **List Records** (`GET /core/v1/domains/{domainName}/records`): Documented `400 Bad Request` for invalid request parameters. See [List Records](/api/v1/reference/dns/list-records).
* **List Endpoints**: Cleaned up validation for invalid pagination params.
### Changed
* **OpenAPI spec**: Documentation updates for DNSSEC and URL Forwarding endpoints. No intended changes to API behavior.
### Added
* **Create Domain** (`POST /core/v1/domains`): Per-account-per-domain registration rate limiting for TLDs served by selected registry connections. Throttling is enforced before registry availability checks are dispatched. Additional registry connections may be added to this policy over time without API contract changes. See [Create Domain](/api/v1/reference/domains/create-domain).
### Changed
* **Rate Limits** ([API Overview](/api/v1/overview#rate-limits)): Documented the new domain registration rate limit in addition to existing account-wide limits (20 req/s, 3,000 req/hour). Clarified that the limit applies per account and per domain name, returns `429 Too Many Requests` with a `Retry-After` header and a distinct error message from the account-wide rate limit, and that other account–domain pairs are unaffected. Integrations should honor `Retry-After` and use retry/backoff.
### Changed
* **Create vanity nameserver** (`POST /core/v1/domains/{domainName}/vanity_nameservers`): Documented `409 Conflict` when a vanity nameserver with the same hostname already exists for the domain. See [Create Vanity Nameserver](/api/v1/reference/vanity-nameservers/create-vanity-nameserver).
### Added
* **Domain object**: Added optional read-only field `transferLockExpiresAt` (ISO 8601 UTC) on single-domain responses. When present, an active ICANN-mandated transfer lock (new registration, transfer-in, or material registrant contact change) blocks client unlock via the API until this time. When omitted, there is no active policy transfer lock with a known expiry — the domain may still be `locked: true` due to a voluntary user lock or other reasons. Returned by [Get Domain](/api/v1/reference/domains/get-domain) and other single-domain operations (create domain, set contacts, update domain, lock/unlock, internal transfer-in, etc.). Not returned on [List Domains](/api/v1/reference/domains/list-domains).
### Added
* **TLD requirements (`tldInfo`)**: Added `requireIdnSld` on `tldInfo`. When `true`, ASCII/Latin SLDs are not valid for registration.
### Changed
* **Pagination (`perPage`)**: List endpoints now enforce a maximum of **1,000** records per request when `perPage` is explicitly set. When omitted, endpoint-specific defaults apply:
* **250** — `GET /core/v1/domains`
* **100** — `GET /core/v1/contacts/unverified`
* **500** — `GET /core/v1/orders`, `GET /core/v1/transfers`, `GET /core/v1/domains/{domainName}/records`, `GET /core/v1/domains/{domainName}/email/forwarding`, `GET /core/v1/domains/{domainName}/url/forwarding`, `GET /core/v1/urlforwarding/{domainName}`, `GET /core/v1/domains/{domainName}/vanity_nameservers`
* **25** — `GET /core/v1/tldpricing`
* **OpenAPI spec**: Cleaned up some language in the spec to make pricing documentation clearer and more concise. No intended changes to API behavior.
### Changed
* **Internal transfer in** (`POST /core/v1/transfers/internal/in`): `contacts` previously required all four roles or none; omitted roles now use the gaining account's default contacts. See [Create Internal Transfer In](/api/v1/reference/transfers/create-internal-transfer-in).
### Added
* **Transfer eligibility**: New `GET /core/v1/transfers/eligibility/{domainName}` endpoint for checking whether a domain is currently registered at name.com and whether its TLD supports internal transfer between name.com accounts. Useful for routing transfer-in flows to either [Create External Transfer In](/api/v1/reference/transfers/create-transfer) or [Create Internal Transfer In](/api/v1/reference/transfers/create-internal-transfer-in) without an RDAP lookup. See [Check Transfer Eligibility](/api/v1/reference/transfers/get-transfer-eligibility).
### Changed
* **OpenAPI spec**: Cleaned up mismatched numeric types in the published schema (e.g. integer fields that were incorrectly typed as `number`). No intended changes to API behavior.
### Added
New optional request parameter filter **`purchaseType`** was added to below endpoints. Omit to return all types. Recommended setting is **`registration`** for standard reseller flows.
* **Check Availability** — `POST /core/v1/domains:checkAvailability` → [Check Availability](/api/v1/reference/domains/check-availability)
* **Search** — `POST /core/v1/domains:search` → [Search](/api/v1/reference/domains/search)
### Added
* **TLD requirements (`tldInfo`)**: `GET /core/v1/domaininfo/requirements/{tld}` and `GET /core/v1/domaininfo/requirementsV2/{tld}` now include `supportsInternalTransfer` on `tldInfo`—whether the TLD supports internal transfer between reseller accounts. See [Get Specific TLD Requirements](/api/v1/reference/domain-info/get-specific-tld-requirements) and [Get Specific TLD Requirements (JSON Schema)](/api/v1/reference/domain-info/get-specific-tld-requirements-v2). Use these in conjunction with [Create Internal Transfer In](/api/v1/reference/transfers/create-internal-transfer-in): resolve the TLD first and confirm `supportsInternalTransfer` before calling `POST /core/v1/transfers/internal/in`.
### Added
* **Internal transfer in**: New `POST /core/v1/transfers/internal/in` endpoint to pull a domain from another name.com account into the authenticated reseller account using `domainName` and `authCode`. The losing account must unlock the domain and supply the authorization code from the name.com dashboard. Restricted to approved enterprise resellers. See [Create Internal Transfer In](/api/v1/reference/transfers/create-internal-transfer-in).
### Fixed
* **Error response coverage**: Added missing documented error responses on affected operations, including `404 Not Found` and `400 Bad Request`, so endpoint contracts align with observed API behavior.
* **Content-Type enforcement in spec**: `415 Unsupported Media Type` is now applied consistently for `POST`, `PUT`, and `PATCH` operations.
* **Request schema validation**: Tightened domain list item validation in request bodies for availability/zone-check style endpoints to better reflect server-side rejection of empty domain entries.
* **getDomain**: `locks` array now returns all registry locking statuses, including `clientHold`. `lock` value still refers specifically to **transfer lock** status.
### Changed
* **Webhook HMAC (`X-NAMECOM-SIGNATURE`)**: When an account has multiple API v4 tokens, outbound webhook signatures now use the token with the lowest id. Previously, there was no explicit rule leading to signature mismatches for accounts with multiple tokens.
### Added
* **Domain Registry Rejection webhook** (`domain.registry.rejection`): New webhook for resellers subscribed to this event. Some registries complete domain **create** asynchronously; when such a request ultimately fails after initial acceptance, this notification is delivered. Successful creates do not emit this event. See [Domain Registry Rejection](/api/v1/reference/webhook-notifications/domain-registry-rejection).
### Changed
* **Error Responses**: Added `400` (Bad Request) to `POST core/v1/domains/{domainName}/records` with improved answer input validation.
### Added
* **Cancel outbound transfer**: New `POST /core/v1/transfers/external/out/{domainName}:cancel` endpoint. Cancels a transfer out of name.com before the transfer completes, when the registrant or reseller requests it. The domain must belong to the authenticated account and be in a cancelable pending transfer-out state. Response returns the domain name and updated transfer-out status.
### Added
* **Contact object**: Unverified contacts returned by the GetDomain `GET /core/v1/domains/{domainName}` response will include the numeric verificationId if it exists (Unverified contacts should have an id if they are pending.)
### Changed
* **Domain Transfer Out Status Change webhook** (`domain.transfer_out.status_change`): The webhook now fires for additional statuses. In addition to `completed`, the `status` field may now be `initiated` (transfer out was started) or `canceled` (transfer out was canceled before completion). Subscribers should handle all three status values.
### Added
* **Domain object**: Added `locks` array to the Domain response. Lists the lock types currently applied to the domain (e.g. `RegistrarLock`, `ClientHold`, `ExpirationClientHold`), so you can see whether and how a domain is locked. Returned by **List Domains** (`GET /core/v1/domains`) and **Get Domain** (`GET /core/v1/domains/{domainName}`). When no locks are applied, `locks` is an empty array.
* **URL Forwarding by ID**: New endpoints so you can list, get, update, and delete URL Forwarding records by server-assigned ID. Create still uses `POST /core/v1/domains/{domainName}/url/forwarding`.
* **List**: `GET /core/v1/urlforwarding/{domainName}` — returns all URL Forwarding entries for the domain. Each entry includes an `id` for use with the by-ID endpoints.
* **Get**: `GET /core/v1/urlforwarding/{domainName}/{id}` — fetch a single record by ID.
* **Update**: `PATCH /core/v1/urlforwarding/{domainName}/{id}` — update a single record by ID.
* **Delete**: `DELETE /core/v1/urlforwarding/{domainName}/{id}` — delete a single record by ID.
* **URL Forwarding response**: Added `id` (integer) to the URL Forwarding entry response. Returned in list and single-record responses so you can use the by-ID endpoints.
* **Error Responses**: Added `502` (Bad Gateway) and `504` (Gateway Timeout) response codes to all endpoints.
* **Retry Policy**: `502` errors are safe for immediate exponential backoff, while `504` errors should be preceded by a status `/core/v1/hello` check to avoid duplicate operations.
### Changed
* **URL Forwarding (host-based)**: The following operations are now **deprecated**: **List** (`GET /core/v1/domains/{domainName}/url/forwarding`), **Get** (`GET /core/v1/domains/{domainName}/url/forwarding/{host}`), **Update** (`PUT /core/v1/domains/{domainName}/url/forwarding/{host}`), **Delete** (`DELETE /core/v1/domains/{domainName}/url/forwarding/{host}`). **Create** (`POST /core/v1/domains/{domainName}/url/forwarding`) is unchanged and not deprecated.
### Added
* Added new webhook: `domain.transfer.internal_in` which fires when a **name.com** domain is transferred **to** a subscriber's account.
* **Check Availability**: Added optional string response property `reason` to the Search result object. When present, it provides additional context (e.g. why a domain is not purchasable).
### Fixed
* Added missing error codes `401` `403` `405` `429` and `500` response codes to all API response objects.
### Added
* **Create Domain**: Added optional `promoCode` parameter to `POST /core/v1/domains` endpoint. Valid promotional codes can be applied to domain purchases to receive discounts. Only one promo code can be applied per request.
### Added
**Contact Verification**:
* Added new webhook: `contact.verification.status_change` that fires when a contact verification status changes.
* Added `POST /core/v1/contacts/verify/{verificationId}:resend` endpoint to resend the verification email for a pending verification record.
### Changed
* **Blocked TLD Filtering**: API endpoints now reject or filter out all .in TLDs (including co.in, firm.in, gen.in, ind.in, net.in, org.in) as these are not supported in the Reseller API. API requests using unsupported TLDs will return `422 Unprocessable Entity` errors or be excluded from results.
### Fixed
* **Requirements**: Both original and V2 Requirements endpoints now return `422 Unprocessable Entity` when blocked or unsupported tlds are requested instead of `500 Internal Server Error`.
### Changed
* No functional changes. Schema updates to ensure no broken URLs between docs pages due to doumentation restructuring.
### Fixed
* Transfer-ins with a rejected status can now be cancelled.
### Changed
* **Transfer Status**: Clarified that `failed` and `rejected` statuses will not be retried. Improved transfer status information for endpoints & webhooks.
### Added
* **Domain Info v2 API**: New `GET /core/v1/domaininfo/requirementsV2/{tld}` endpoint that returns TLD registration requirements in JSON Schema Draft-07 format.
* **Automatic Form Generation**: The JSON Schema Draft-07 format enables direct integration with form generation libraries (e.g., react-jsonschema-form, jsonforms, Form.io), allowing developers to automatically generate dynamic registration forms without manual schema parsing or custom form logic.
* **Conditional Validation**: The schema uses `if/then/else` structures to express complex conditional requirements (e.g., "if entity type is X, then require field Y"), making it easier to understand and implement TLD-specific registration rules that vary based on user selections.
* **Standardized Validation**: JSON Schema Draft-07 is a widely-supported standard, enabling developers to leverage existing validation libraries and tooling instead of building custom validation logic for each TLD's unique requirements.
* **Structured Data**: The schema clearly separates TLD information (`tldInfo`), contact requirements (`contacts`), and TLD-specific fields (`tldRequirements`), providing a consistent structure that simplifies form rendering and data collection workflows.
### Fixed
**Get Order** The Get Order API was incorrectly returning the response object wrapped in an extraneous `order` object. This has been fixed, and the response now matches the specification.
### Added
* **Refunds Endpoint**: New `POST /core/v1/refund` endpoint to delete eligible domains and privacy products during the Add Grace Period (AGP) and automatically issue refunds for the associated order items.
* Accepts `orderId` and `orderItemIds` array in the request body
* Supports `registration` and `whois_privacy` product types only
* Includes idempotency support via `X-Idempotency-Key` header for safe request retries
* Returns detailed refund results including individual item status and total refund amount
* Refunds are issued to the original payment method on file, with fallback to account credit
* **OrderItem `isRefundable` Property**: New boolean field on `OrderItem` indicating whether the item is currently eligible for refund through the Refunds endpoint based on name.com's refund rules.
* **List Orders Endpoint**: Updated request has new optional filters to narrow response by domainName, tld, createDate, type and orderStatus.
### Fixed
* **Purchase Privacy**: Now returns `409 Conflict` when privacy protection already exists on a domain instead of `500 Internal Server Error`.
### Added
* **Domain Transfer Out Status Change Webhook**: New `domain.transfer_out.status_change` webhook that fires when a domain transfer out from name.com to another registrar has completed and the domain has been removed from the account.
### Changed
* **Domain Transfer Status Change Webhook**: Clarified that `domain.transfer.status_change` represents transfer IN to name.com (where name.com is the gaining registrar), and updated webhook descriptions to reflect this.
### Added
* **TLD Pricing Response Enhancement**: The TLD Price List endpoint now includes retail pricing information in addition to account-level pricing, which applies to registration, renewal, domain restoration, and transfer purchase types. Each pricing entry now provides three price tiers:
* Account-level price (includes account discounts)
* Retail price (includes rebates/promotions/sales, but no account discounts)
* Original/MSRP price (before any discounts)
### Changed
* **Contact Schema Validation**: Contact schemas have been refactored to separate validation requirements between request and response operations:
* **GET Operations (Responses)**: The `Contact` and `RegistrantContact` schemas used in API responses now allow nullable fields to accommodate legacy data that may contain null or empty values. This ensures GET operations can successfully return domains with legacy contact information without validation errors.
* **POST/PUT Operations (Requests)**: The `ContactRequest` and `RegistrantContactRequest` schemas used for creating and updating contacts enforce all validation requirements including:
* Required fields (firstName, lastName, address1, city, state, zip, country, email, phone)
* Minimum length constraints (minLength: 1)
* Format validation (email format, phone/fax E.164 pattern, country code pattern)
* This separation ensures that while GET operations can handle legacy data gracefully, all contact creation and update operations continue to enforce proper data validation and formatting requirements.
### Fixed
* **Get Domain Pricing**: Fixed validation order in `getPricingForDomain` endpoint to check TLD support before year validation. Unsupported TLDs now return `422 Unprocessable Entity` with the message "TLD not supported" instead of `400 Bad Request` with a misleading "Invalid value for years for this domain" message.
* **Create Domain**: Added TLD privacy support check before adding WhoIs Privacy to orders. Privacy is only added when the TLD supports it, preventing failed order items for unsupported TLDs.
* **Purchase Privacy**: Added TLD privacy support validation. Returns `422 Unprocessable Entity` with message "TLD does not support WhoIs Privacy" when attempting to purchase privacy for unsupported TLDs.
### Changed
* Cancel Transfer endpoint now returns a 409 conflict if an existing transfer is in a state that cannot be canceled.
### Fixed
* A handful of new contact schemas were missing updates to separate Request vs Response. This has been fixed.
### Added
* Create Transfer: Added `504 Gateway Timeout` response when domain status cannot be retrieved due to blocked-hostname.
* Create Transfer: Added optional `warnings` object to `CreateTransferResponse` with `message` and `statuses` to surface non-blocking registry status advisories.
* Domain Lock Status Change Webhook: Added `ExpirationClientHold` to the `lockType` enum. This lock type is applied to expired domains of configured API Reseller accounts.
### Fixed
* Create Transfer: Fixed issue where a `400 Bad Request` was returned for Insufficient Funds instead of the correct `402 Payment Required` status.
* Get Domain: Fixed intermittent `500 Server Error` caused by legacy contact data by updating API definitions to allow legacy contacts to be returned while still enforcing correct formatting in requests.
### Added
* Domain Claims Period Support: Register domains during trademark claims period.
* New endpoint: `GET /core/v1/domaininfo/claims/{domain}` returns claim identifiers and validity dates.
### Changed
* TLD Requirements: `GET /core/v1/domaininfo/requirements/{tld}` now returns `claimsCheckRequired`.
* Domain Create: `POST /core/v1/domains` now accepts optional `claims` object (`claimId`, `notBefore`, `notAfter`) when required by the TLD.
### Added
* List Domains: New `includeRenewalPrice` query parameter.
* `true` (default) includes renewal pricing in responses.
* `false` omits renewal pricing for better performance.
### Changed
* `renewalPrice` field is optional when `includeRenewalPrice=false`.
* Default pagination for List Domains changed from 1000 to 250.
* Removed access restriction on `GET /core/v1/contacts/unverified` (now available to all reseller accounts).
* `.at` TLD requirement now enforces data acknowledgement.
### Fixed
* Create Transfer: Block transfers for domains registered less than 60 days; returns `409 Conflict` with clear `message` and `details`.
### Changed
* Webhook documentation: standardized response code capitalization from `4xx/5xx` to `4XX/5XX`.
### Added
* `Get Specific TLD Requirements`: Added `registryOperator` parameter.
* Webhook HMAC Header Documentation: `X-NAMECOM-SIGNATURE` now shown on all webhook endpoints.
### Fixed
* Request validation now enforces required fields as described in the API documentation.
### Fixed
* Create Domain: Now correctly honors `privacyEnabled=false` instead of overriding with account default when provided.
### Fixed
* Get Specific TLD Requirements: Clarified that punycode is expected (not URL-encoded params).
### Added
* Contact model: Added verification status fields.
* Create Domain: Returns `451 Unavailable for Legal Reasons` where restricted by law.
* Create Domain: Returns detailed validation errors for contact creation failures.
* Webhooks: All webhooks now send `X-NAMECOM-SIGNATURE` to verify authenticity.
### Fixed
* Contact Verification List: Corrected `createDate` and `verifyBy` values for some contacts.
### Added
* New webhook: `domain.lock.status_change` with `registryStatuses` in payload.
* New contact verification APIs:
* List Unverified Contacts
* Verify Contact (account-restricted)
### Changed
* TLD Pricing: Clarified that null pricing indicates unavailability for specific TLD/duration combinations.
* DNS Record Update: Duplicate record DB errors now return `409 Conflict` instead of a generic server error.
### Added
* Domain Info: New capabilities returned per TLD:
* `supportsPrivacy`
* `requiresPreDelegation`
### Added
* Get Specific TLD Requirements: Added `hsts`, `minDomainLength`, `minIdnDomainLength`.
* Subscribe to Notifications: Documented `409 Conflict` response when already subscribed.
* Zone Check API: Documented existing error responses.
### Added
* Download Premium Domain Lists: New account-restricted API endpoint to download premium domain lists.
### Added
* Transfers: `GET /transfers` and `GET /transfers/{id}` now include a full list of possible transfer statuses.
### Changed
* Transfers: Status field standardized to snake\_case; aligned with Domain Transfer Status Change webhook.
### Fixed
* Create Domain: Now honors account setting for Automatic Advanced Security for new purchases.
### Changed
* Domain Get Pricing: When a pricing category is not available, `purchasePrice`, `renewalPrice`, and `transferPrice` return `null` instead of a `422`.
### Fixed
* Create Transfer: Supports multiple concurrent transfer requests; `429` now used solely for rate limiting scenarios.
* Pricing error handling: Added `422 Unprocessable Entity` for temporary pricing unavailability across:
* Domain Create
* Domain Renew
* Domain Get Pricing
* Domain Get Pricing: Added missing `400 Bad Request` documentation for invalid parameters/malformed requests.
### Changed
* Error Response Consistency: More descriptive pricing-related error details across domain endpoints.
### Fixed
* createDomain: Returns `400 Bad Request` (not `403 Forbidden`) for missing/invalid registration requirements.
### Added
* Zone Check API: Fast availability checks via cached zone file data.
* Idempotency: Support for `X-Idempotency-Key` on Create Domain and Purchase Privacy.
* Replayed requests respond with header `X-Idempotent-Replay: 1`.
* Domain Create docs: Improved examples including IDN domain creation.
### Fixed
* TLD Pricing API: Ensured required fields are always present in responses.
* Check Availability: Returns `422 Unprocessable Entity` when all domains have unsupported TLDs (replacing malformed dual-object JSON).
### Changed
* Check Availability: Implementation optimized for speed; no behavioral changes.
* Organization field docs updated due to ICANN policy changes.
* `429 Rate Limited` response in OpenAPI now indicates `message` is optional.
### Changed
* TLD Pricing API:
* Enforced `duration` parameter validation.
* Filter invalid/unsupported `tlds`; if list becomes empty after filtering, return `400 Bad Request`.
### Fixed
* Domain Info: Return empty objects `{}` instead of empty arrays `[]` for relevant parameters.
### Added
* TLD Pricing API: View general price list with account-level pricing.
### Changed
* Response Schemas: Clarified which parameters are `required` and always present in responses.
### Added
* Domain Info API: Returns general TLD info and any additional registration requirements; formatted for dynamic form generation.
### Changed
* OpenAPI: Adjusted several descriptions to use v3.0-compatible structures (no functional changes).
* Webhook docs: DomainTransferStatusChange updated with list of triggering statuses.
### Fixed
* List Domains: Optional filters no longer cause `500 Internal Server Error` or incorrect result sets; filters are applied reliably.
### Fixed
* Create Domain: Missing required contact phone number returns `400 Bad Request` instead of `500`.
* Validation Enforcement:
* Contact `phone` and `fax` fields strictly validate E.164 format (`^\+[1-9]\d{7,14}$`); examples updated.
* All email fields validated per RFC 822 `addr-spec` (with common practical exceptions).
* Appropriate enums added; empty strings rejected for fields like `first_name`.
### Fixed
* Authentication failures return `401 Unauthorized` instead of `500`.
* Pagination: `perPage=0` now defaults to `perPage=1000` instead of returning `500`.
### Fixed
* Create Transfer: Intermittent `500` replaced with `409 Conflict` when a transfer is already in process.
* Message: `A transfer is already processing for this domain`.
name.com is launching a new Core API — a modern, RESTful API for managing domains, DNS records, and related services. It is the successor to the legacy v4 API.
### Changed
* Documentation format upgraded to OpenAPI 3.1 for better tooling and interactivity.
* Internal implementation rebuilt for faster iteration, better error handling, and consistent endpoint behavior.
* Error messaging:
* Authentication errors now return `401 Unauthorized` (previously conflated with `403 Forbidden` which is now reserved for actual permission issues).
* Insufficient account credit returns `402 Payment Required` instead of `500`.
* Consistent default values in responses (e.g., `false`, `0`, `""`) instead of omitting them.
* Correct `Content-Type` headers for JSON responses (`application/json`).
* `Content-Type: application/json` strictly required for all `PUT`, `POST`, and `PATCH` requests (including body-less `POST` actions due to server behavior).
### Removed
* SearchStream endpoint (may return in a future version with a revised implementation).
### Added
* Domain Update endpoint for autorenew, WHOIS Privacy, and locking. See DomainUpdate docs.
# API Overview
Source: https://docs.name.com/api/v1/overview
Complete overview of name.com Core API structure, environments, and key features
# name.com API (CORE) Overview
The name.com API lets you search, register, and manage domains, DNS records, WHOIS privacy, and more — all through a secure, RESTful interface.
CORE is the latest version of our API, built for developers, SaaS platforms, and businesses.
For legacy v4 integrations, view the [v4 API documentation](https://www.name.com/api-docs). For a summary of what's new in name.com API (CORE), see the [Changelog](/api/v1/changelog)
## Base URLs
**Base URL:** `https://api.name.com`\
**Purpose:** Manage live domains in your production account
**Base URL:** `https://api.dev.name.com`\
**Purpose:** Test and simulate actions without affecting real domains
## API Versioning
The name.com API uses path-based versioning (e.g., `core/v1/` in the endpoint URLs). Going forward, our API will be following semantic versioning on changes to the API.
* **Current version:** name.com API (CORE v1), released June 2025
* **Versioning model:** Major version in the URL path (e.g., `https://api.name.com/core/v1`)
* **Previous versions:** v4 is still supported and will sunset at a predetermined time in 2026
For a detailed timeline of updates, breaking changes, deprecations, and upcoming features, see our [Changelog](/api/v1/changelog).
## Download the Latest OpenAPI Specification
Ready to start building? Download the latest version of name.com CORE API OpenAPI 3.1 specification below.
Download the OpenAPI specification in YAML format
***
## Key Characteristics
Standard HTTP methods (GET, POST, PUT, DELETE)
HTTP Basic Auth (username + API token). Sandbox requires a -test username and a sandbox token. See the full [Authentication](/guides/authentication) guide for curl `-u` vs explicit header and Base64 generation on Linux/macOS and Windows PowerShell.
HTTPS only (port 443)
APIs are organized around Domains, DNS Records, Transfers, URL Forwarding, Vanity Nameservers, and Webhook Notifications
## Authentication
All API requests require **Basic Authentication** using your API credentials. See the [Authentication](/guides/authentication) guide for curl `-u` shorthand vs explicit header, and how to generate the Base64 value on Linux/macOS and Windows PowerShell.
```bash theme={null}
curl -X GET "https://api.dev.name.com/core/v1/hello" \
-u "username:token"
```
The API uses HTTP Basic Authentication where:
* **Username**: Your name.com API username
* **Token**: Your API token (not your account password)
## Environment Details
The name.com API provides two fully separated environments for safe development and live operations:
### Production Environment
* **Base URL:** `https://api.name.com`
* **Purpose:** Manage real domains and billing
* **Credentials:** Use your name.com username and production API token
### Sandbox (Development) Environment
* **Base URL:** `https://api.dev.name.com`
* **Purpose:** Safe for testing — no real charges
* **Credentials:** Use your username with -test appended (e.g., `reseller123-test`) and your sandbox API token
* **Features:** Preloaded testing credit available, domains and orders do not sync with production
**Important:** Domains must be created in sandbox before using them. For example, `GET /core/v1/domains/example.com` will return "Not Found" unless you register it first in the sandbox environment.
## Response Format
* API responses are returned in JSON format
* Fields set to default values (empty strings, false, 0) are omitted to simplify payloads
* On success (HTTP 200 OK), you receive a structured JSON response
* On error (HTTP 4xx/5xx), you receive an error JSON such as:
```json theme={null}
{
"message": "Permission Denied",
"details": "Authentication Error - Account Has Two-Step Verification Enabled"
}
```
Always check both the HTTP status code and the message/details fields to debug responses.
## API Usage Guidelines
### Path Parameters
Insert actual values where `{}` appears in endpoints.
**Example:**
* `GET /core/v1/domains/{domainName}/records`
* `GET /core/v1/domains/example.org/records`
### HTTP Methods and Content-Type
Use the correct HTTP verb:
| Method | Action |
| ------ | --------------------------- |
| GET | Retrieve a resource |
| POST | Create a new resource |
| PUT | Update an existing resource |
| DELETE | Delete a resource |
When sending JSON payloads (POST/PUT), always set the header: `Content-Type: application/json`
### Pagination
* For list endpoints, use the `perPage` and `page` query parameters
* The API provides Link headers for easy pagination: `Link: ; rel="next"`
* You can use these headers to automate paging through large lists of results
### Important Note on Colon (:) in Endpoint Paths
For the following endpoints:
* `POST /core/v1/domains:checkAvailability`
* `POST /core/v1/domains:search`
* `POST /core/v1/domains:searchStream`
**Do not URL-encode the colon (`:`) in the request path.**
Some HTTP clients or SDKs may automatically encode `:` to `%3A` (e.g., `/v4/domains%3AcheckAvailability`), which will cause the request to fail.
Always use the literal colon character `:` in the endpoint URL.
### Rate Limits
* **20 requests per second**
* **3,000 requests per hour**
If you exceed the account-wide rate limit, the server responds with `429 Too Many Requests`.
#### Domain registration limits (selected registry connections)
For domain registrations (`POST /core/v1/domains`) on TLDs served by certain registry connections, an additional limit applies **per account and per domain name**. This limit is separate from the account-wide limits above and is intended to protect registry operations from abusive retry patterns—for example, rapid repeated attempts to register the same name.
* The limit is evaluated independently for each account–domain pair.
* Registering a different domain on the same account, or the same domain from a different account, is not affected by another pair's limit.
* The set of registry connections subject to this limit may expand over time.
* When this limit is exceeded, the API returns `429 Too Many Requests` with a `Retry-After` header indicating when you may retry. The response message differs from the account-wide rate limit message.
Implement retry and backoff logic in your integration, and honor `Retry-After` when present.
## Common API Errors
Resource not found in environment. Make sure the domain or record exists in the correct environment.
2FA-enabled accounts are not supported. Disable Two-Factor Authentication on your account.
Invalid or malformed input value. Correct the input, such as providing a valid IPv4 address.
Mixing production/sandbox credentials. Double-check that your API URL matches your credentials.
Authentication missing or invalid. Fix your Basic Auth headers and verify no typos in URLs.
Incorrect or revoked API token. Regenerate a new API token and use it for your requests.
## Languages
The API can be accessed using any HTTP client in your preferred programming language:
Command-line tool
Browser & Node.js
Python HTTP libraries
PHP HTTP clients
Java HTTP clients
.NET HTTP clients
Go HTTP packages
Node.js libraries
## Next Steps
You're ready to start building!
Explore the latest CORE API Resources
View the v4 API Documentation
### Accessing the Legacy v4 API
We continue to maintain the v4 API documentation for existing integrations and legacy systems. While the current documentation focuses on the latest CORE API, you can still reference the full v4 guides if your systems depend on them.
* v4 remains supported for legacy users
* All new integrations should use CORE v1
* Only CORE v1+ will receive new features
* Any v4 deprecation will be announced via the Changelog
All API access requires HTTPS and authentication with your name.com credentials and API token.
***
**Account Services**
Contact us at [reseller@name.com](mailto:reseller@name.com)
Review our API Access Agreement and Terms of Service
# Check Account Balance
Source: https://docs.name.com/api/v1/reference/account-info/check-account-balance
get /core/v1/accountinfo/balance
Returns the current account credit balance for the authenticated user.
# List Unverified Contacts
Source: https://docs.name.com/api/v1/reference/contact-verification/list-unverified-contacts
get /core/v1/contacts/unverified
Returns a list of contacts, related to domains within your account, that require verification as per ICANN procedures.
When a new domain is created, unverified contacts are not immediately available in API responses. Records are added by a scheduled process that runs approximately every 10 minutes. As a result, there may be up to a 10-minute delay before unverified contacts appear in the API. This delay also applies to related events such as webhooks or other downstream systems that depend on contact verification data.
# Resend Contact Verification Email
Source: https://docs.name.com/api/v1/reference/contact-verification/resend-verification-email
post /core/v1/contacts/verify/{verificationId}:resend
Resend the contact verification email for a pending verification record.
### Throttling
This endpoint enforces strict throttling to prevent abuse:
- Per `verificationId`: max 1 resend per 15 minutes
- Per reseller account: max 200 resends per rolling hour
`nextEligibleAt` is always returned so the client knows when it can try again.
On `429`, the response uses the standard error envelope, and `details` contains the earliest retry time (RFC3339 UTC).
# Verify Contact
Source: https://docs.name.com/api/v1/reference/contact-verification/verify-contact
post /core/v1/contacts/verify/{verificationId}
Use this API to verify a contact.
This API is only available to approved reseller accounts. Contact name.com support to request access.
# Create Record
Source: https://docs.name.com/api/v1/reference/dns/create-record
post /core/v1/domains/{domainName}/records
Adds a new DNS record to the specified domain zone. Provide the record type (e.g. A, MX, CNAME), host, value, and TTL. This is used for configuring domain-based services such as email, website hosting, or third-party verifications.
# Delete Record
Source: https://docs.name.com/api/v1/reference/dns/delete-record
delete /core/v1/domains/{domainName}/records/{id}
Removes a DNS record by ID. Often used during cleanup operations or when replacing outdated DNS settings with updated records.
# Get Record
Source: https://docs.name.com/api/v1/reference/dns/get-record
get /core/v1/domains/{domainName}/records/{id}
Retrieves details of a specific DNS record.
# List Records
Source: https://docs.name.com/api/v1/reference/dns/list-records
get /core/v1/domains/{domainName}/records
Lists all DNS records for a specified domain.
# Update Record
Source: https://docs.name.com/api/v1/reference/dns/update-record
put /core/v1/domains/{domainName}/records/{id}
Replaces an existing DNS record with new data. This is a full overwrite — all required fields (host, type, answer, ttl) must be included in the request body. If you omit a field, the existing value will not be preserved and the request may fail. Use [GetRecord](/api/v1/reference/dns/get-record) beforehand to retrieve the current values if you intend to modify just one field. The record ID must belong to a domain you manage.
# Create DNSSEC
Source: https://docs.name.com/api/v1/reference/dnssecs/create-dnssec
post /core/v1/domains/{domainName}/dnssec
Adds (registers) a new DNSSEC DS record for a domain.
# Delete DNSSEC
Source: https://docs.name.com/api/v1/reference/dnssecs/delete-dnssec
delete /core/v1/domains/{domainName}/dnssec/{digest}
Deletes a DNSSEC record from a domain.
# Get DNSSEC
Source: https://docs.name.com/api/v1/reference/dnssecs/get-dnssec
get /core/v1/domains/{domainName}/dnssec/{digest}
Retrieves details of a specific DNSSEC record for a domain.
# List DNSSECs
Source: https://docs.name.com/api/v1/reference/dnssecs/list-dnssecs
get /core/v1/domains/{domainName}/dnssec
Lists all DNSSEC (DS) records configured for a domain.
# Check Domain Claims
Source: https://docs.name.com/api/v1/reference/domain-info/check-domain-claims
post /core/v1/domaininfo/claims/{domain}
Performs the actual claims check for a specific domain. This endpoint checks if a specific domain has trademark claims against it, returning detailed information about any matching trademarks and their holders. Use this to verify if a domain can be registered without trademark conflicts. Please see the [claims flow](/guides/claims-flow) for information on how to use this endpoint in your domain purchase flow.
# Get Specific TLD Requirements
Source: https://docs.name.com/api/v1/reference/domain-info/get-specific-tld-requirements
get /core/v1/domaininfo/requirements/{tld}
Returns the registration requirements some general information for a specific TLD. The response contains a detailed description of eligibility criteria and a fields object with all required and optional fields, including validation rules, conditional logic, and nested field structures. Provide the TLD as a path parameter to retrieve its complete registration requirements. Useful when you only need details for one TLD (e.g., when a user selects .fr from a dropdown).
# Get TLD Requirements as JSON Schema
Source: https://docs.name.com/api/v1/reference/domain-info/get-specific-tld-requirements-v2
get /core/v1/domaininfo/requirementsV2/{tld}
Returns the registration requirements as a JSON Schema (Draft 7) document. This endpoint is designed for form generation and validation libraries that consume JSON Schema directly.
# Check Availability
Source: https://docs.name.com/api/v1/reference/domains/check-availability
post /core/v1/domains:checkAvailability
Checks whether up to 50 domain names are purchasable and returns **discovery** pricing for each result.
**Discovery endpoint:** Returns `SearchResult` fields — `purchaseType`, `purchasePrice`, `premium`, `purchasable`. [Search](/api/v1/reference/domains/search) returns the same fields for keyword/suggestion flows. Use this endpoint to determine what to send on [Create Domain](/api/v1/reference/domains/create-domain).
When results show `premium: true` or a non-`registration` `purchaseType`, follow the [Domain pricing guide](/guides/domain-pricing) before calling Create Domain. For non-registration types, re-check Check Availability immediately before create — acquisition prices can change.
**Recommendation:** Set `purchaseType` to `registration`. Most resellers
restrict results to domains with a `purchaseType` of `registration`
to ensure predictable pricing and immediate fulfillment. Other purchase types
(such as aftermarket variants) can introduce higher costs and non-instant
transactions that may be delayed or declined by third parties.
# Create Domain
Source: https://docs.name.com/api/v1/reference/domains/create-domain
post /core/v1/domains
Registers a new domain under your account. You must provide `domain.domainName` at minimum.
This endpoint is commonly used to programmatically onboard new domains through user signup flows or checkout experiences.
If no contacts are passed in this request, the default contacts for your name.com account will be used.
### Create Domain pricing
See the [Domain purchase pricing guide](/guides/domain-pricing) for the full reference.
**Recommendation:** For most integrations, scope discovery to `purchaseType: registration`. Other purchase types are supported but add complexity — details in the guide above.
**Discovery (required before create):** Call [Search](/api/v1/reference/domains/search) or [Check Availability](/api/v1/reference/domains/check-availability), not Get Pricing alone. Both return the same `SearchResult` fields (`purchaseType`, `purchasePrice`, `premium`, `purchasable`). [Zone Check](/api/v1/reference/domains/zone-check) is designed for rapid availability checks only; it is not sufficient to complete a purchase.
### Getting the price for Create Domain
1. **Search or Check Availability** → copy `purchaseType`, `premium`, note `purchasePrice`.
2. Branch on `purchaseType`:
- **`registration` + `premium: false`** — omit `purchasePrice` on create, set `years`. Optional: Get Pricing with same `years` to preview the total.
- **`registration` + `premium: true`** — Get Pricing with same `years` → pass `purchasePrice` exactly.
- **aftermarket / expiring / backorder** — use discovery `purchasePrice` (flat fee). Re-check discovery before create. Do not use Get Pricing for create price. `years` does not multiply price or guarantee registration length.
3. If `purchasePrice` is sent, it must match exactly or the request fails with `400` and `"Purchase price does not match"`.
**Years on acquisition types:** For `aftermarket_s`, `aftermarket_b`, `aftermarket_i`, `expiring`, and `backorder`: omit `years` or pass the TLD default. Check `domain.expireDate` in the response; [Renew](/api/v1/reference/domains/renew-domain) to extend registration.
### Best Practices For Domain Creates
In general, you should check that a domain is available prior to attempting to purchase a domain.
You can use either the [checkAvailability](/api/v1/reference/domains/check-availability) endpoint, or the [Search](/api/v1/reference/domains/search) endpoint
to confirm that a domain is purchasable.
#### Important Note on Dropcatching and Abuse Prevention
_The createDomain endpoint is designed for standard domain registrations and is not intended for automated dropcatching (i.e., mass or high-frequency attempts to register domains the moment they become available after expiration). The use of drop-catching tools or services to acquire expired domains is strictly prohibited. All domain acquisitions must go through approved channels to ensure fair and transparent access._
#### Contact Verification
When a new domain registration is created and a contact is submitted, name.com may need to validate the contact's email address in accordance with ICANN policy. This validation involves sending an email to the provided address, prompting the recipient to click a link to verify their email address.
# Disable Autorenew
Source: https://docs.name.com/api/v1/reference/domains/disable-autorenew
post /core/v1/domains/{domainName}:disableAutorenew
Turns off automatic renewal for a domain. **DEPRECATED** This endpoint is deprecated in favor of the new UpdateDomain API. This will be removed in a future release.
# Disable Whois Privacy
Source: https://docs.name.com/api/v1/reference/domains/disable-whois-privacy
post /core/v1/domains/{domainName}:disableWhoisPrivacy
Disables WHOIS privacy protection on a domain. **DEPRECATED** This endpoint is deprecated in favor of the new UpdateDomain API. This will be removed in a future release.
# Enable Autorenew
Source: https://docs.name.com/api/v1/reference/domains/enable-autorenew
post /core/v1/domains/{domainName}:enableAutorenew
Turns on automatic renewal for a domain. **DEPRECATED** This endpoint is deprecated in favor of the new UpdateDomain API. This will be removed in a future release.
# Enable Whois Privacy
Source: https://docs.name.com/api/v1/reference/domains/enable-whois-privacy
post /core/v1/domains/{domainName}:enableWhoisPrivacy
Enables WHOIS privacy protection on a domain. **DEPRECATED** This endpoint is deprecated in favor of the new UpdateDomain API. This will be removed in a future release.
# Get Auth Code For Domain
Source: https://docs.name.com/api/v1/reference/domains/get-auth-code-for-domain
get /core/v1/domains/{domainName}:getAuthCode
Retrieves the transfer authorization code (EPP code) for a domain.
# Get Domain
Source: https://docs.name.com/api/v1/reference/domains/get-domain
get /core/v1/domains/{domainName}
Retrieves detailed information for a specific domain in your account.
# Get Pricing For Domain
Source: https://docs.name.com/api/v1/reference/domains/get-pricing-for-domain
get /core/v1/domains/{domainName}:getPricing
Returns registration, renewal, and transfer pricing for a domain and term.
**Not a discovery endpoint:** Does not return `purchaseType`. Cannot determine whether a domain is acquired via registration vs aftermarket/expiring/backorder — call [Search](/api/v1/reference/domains/search) or [Check Availability](/api/v1/reference/domains/check-availability) first.
**Scope:** `purchasePrice` and `premium` reflect **standard and registry-premium registration** only. They do **not** return aftermarket, expiring, or backorder acquisition prices. For those types, use `purchasePrice` from Search or Check Availability.
**Registration create (`purchaseType: registration`):** When create requires `purchasePrice` (registry premium), call with the **same** `years` you will send on create. Pass `purchasePrice` directly — it is the **total** for that term, not a per-year component.
**Renew:** Pass `renewalPrice` as `purchasePrice` on [Renew Domain](/api/v1/reference/domains/renew-domain) for premium renewals — not for computing Create Domain totals.
**Transfer:** Pass `transferPrice` as `purchasePrice` on [Create Transfer](/api/v1/reference/transfers/create-transfer) for premium transfers. The `years` query parameter does not affect `transferPrice`.
See the [Domain pricing guide](/guides/domain-pricing) for the full workflow.
# List Domains
Source: https://docs.name.com/api/v1/reference/domains/list-domains
get /core/v1/domains
Lists all domains in your account (basic details for each domain).
# Lock Domain
Source: https://docs.name.com/api/v1/reference/domains/lock-domain
post /core/v1/domains/{domainName}:lock
Locks a domain to prevent it from being transferred. **DEPRECATED** This endpoint is deprecated in favor of the new UpdateDomain API. This will be removed in a future release.
# Purchase Privacy
Source: https://docs.name.com/api/v1/reference/domains/purchase-privacy
post /core/v1/domains/{domainName}:purchasePrivacy
Adds or renews WHOIS privacy protection for a domain. This is used to ensure personal contact details remain hidden from public WHOIS lookups. If WHOIS privacy is already enabled, this will extend the protection. If it’s not yet active, this will both purchase and enable the service. This is a billable action unless covered by a bundled privacy plan.
# Renew Domain
Source: https://docs.name.com/api/v1/reference/domains/renew-domain
post /core/v1/domains/{domainName}:renew
Renews an existing domain for an additional registration period. Include the domain name and renewal term. Omit `purchasePrice` for standard (non-premium) renewals. For premium renewals, pass `renewalPrice` from [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) with matching `years` as `purchasePrice`. Renewal pricing is separate from Create Domain registration/acquisition pricing. This is typically used to extend ownership before a domain’s expiration.
# Search
Source: https://docs.name.com/api/v1/reference/domains/search
post /core/v1/domains:search
Searches for domain name suggestions based on a keyword or term. Important: Do not
encode the `:` in the path. Use `/core/v1/domains:search`, not `/core/v1/domains%3Asearch`.
**Discovery endpoint:** Returns `SearchResult` fields — `purchaseType`, `purchasePrice`, `premium`, `purchasable`.
**Recommendation:** Set `purchaseType` to `registration`. Most resellers restrict
results to domains with a `purchaseType` of `registration` to ensure predictable
pricing and immediate fulfillment. Other purchase types (such as aftermarket) can
introduce higher costs and non-instant transactions that may be delayed or declined
by third parties.
With `purchaseType: registration`, domains that do not match the filter are **omitted** from results (unlike Check Availability, which returns them with `purchasable: false`).
When results show `premium: true` or a non-`registration` `purchaseType`, follow the [Domain pricing guide](/guides/domain-pricing) before calling Create Domain. For all types, re-check with Check Availability immediately before create — prices and availability can change.
# Set Contacts
Source: https://docs.name.com/api/v1/reference/domains/set-contacts
post /core/v1/domains/{domainName}:setContacts
Updates WHOIS contact information for a domain. This includes the registrant, administrative, technical, and billing contacts. All contact objects must be complete — partial updates are not supported. You should fetch the existing contact data first (e.g., via [GetDomain](/api/v1/reference/domains/get-domain) and modify only the values you wish to change. This call replaces all four contact sets at once.
#### Contact Verification
When registrant contact information is updated, validation may be triggered if the new contact information has not been previously validated. This validation is required by ICANN for all TLDs except country-code TLDs (ccTLDs). This validation involves sending an email to the provided address, prompting the recipient to click a link to verify their email address.
# Set Nameservers
Source: https://docs.name.com/api/v1/reference/domains/set-nameservers
post /core/v1/domains/{domainName}:setNameservers
SetNameservers will set the nameservers for the Domain. This operation updates the DNS configuration by changing which nameservers are responsible for the domain's zone.
# Unlock Domain
Source: https://docs.name.com/api/v1/reference/domains/unlock-domain
post /core/v1/domains/{domainName}:unlock
Unlocks a domain to allow it to be transferred. **DEPRECATED** This endpoint is deprecated in favor of the new UpdateDomain API. This will be removed in a future release.
# Update a domain
Source: https://docs.name.com/api/v1/reference/domains/update-a-domain
patch /core/v1/domains/{domainName}
Allows updating of the autorenew, WhoIs Privacy and lock status of the specified domain. The request requires one, or any combination of the parameters in order to pass validation. If any of the requested updates failed, the domain will be returned to it's original state.
# Zone Check
Source: https://docs.name.com/api/v1/reference/domains/zone-check
post /core/v1/zonecheck
Zone Check offers a rapid, preliminary check for domain availability by leveraging cached zone file data. Ideal for large-batch queries, it provides a high confidence indication of a domain's availability significantly faster than live registry checks. For definitive, real-time availability and pricing, you can follow up with the standard [Check Availability](/api/v1/reference/domains/check-availability) call.
The API normalizes and validates each submitted domain string. Domains that fail validation, use an unsupported TLD for this service, or are otherwise not eligible for zone check are **removed** from the request before the zone file lookup runs. The response includes **only** a numeric count of removed domains (`removed`); individual removed strings are not returned. A future API version may extend the contract to include details about removed domains.
For the best results and to avoid `400 Bad Request` errors after cleaning, ensure each domain string meets the criteria described for `domainNames` in the request body schema.
If no valid domains remain after this process, the API returns a `400 Bad Request` response.
**Note:** The cached zone files used for this check are refreshed twice daily based on the latest available data from the registries.
# Create Email Forwarding
Source: https://docs.name.com/api/v1/reference/email-forwardings/create-email-forwarding
post /core/v1/domains/{domainName}/email/forwarding
Creates a new email forwarding rule for a domain, such as redirecting info@example.com to an external inbox. If this is the first email forwarding rule created for the domain, the API may also update your MX records automatically to enable mail routing. The alias must not conflict with existing email services or MX records. To modify a forwarding rule later, use [UpdateEmailForwarding](/api/v1/reference/email-forwardings/update-email-forwarding).
# Delete Email Forwarding
Source: https://docs.name.com/api/v1/reference/email-forwardings/delete-email-forwarding
delete /core/v1/domains/{domainName}/email/forwarding/{emailBox}
Deletes an email forwarding rule from a domain.
# Get Email Forwarding
Source: https://docs.name.com/api/v1/reference/email-forwardings/get-email-forwarding
get /core/v1/domains/{domainName}/email/forwarding/{emailBox}
Retrieves the details of a specific email forwarding entry.
# List Email Forwardings
Source: https://docs.name.com/api/v1/reference/email-forwardings/list-email-forwardings
get /core/v1/domains/{domainName}/email/forwarding
Returns a paginated list of all email forwarding rules for a domain.
# Update Email Forwarding
Source: https://docs.name.com/api/v1/reference/email-forwardings/update-email-forwarding
put /core/v1/domains/{domainName}/email/forwarding/{emailBox}
Updates the destination email address for an existing forwarding rule.
# Hello
Source: https://docs.name.com/api/v1/reference/hello/hello
get /core/v1/hello
Returns basic information about the API server (useful for testing connectivity and version checks).
# Get Order
Source: https://docs.name.com/api/v1/reference/orders/get-order
get /core/v1/orders/{orderId}
Fetches full details about a specific order using its ID. This includes domains, prices, and timestamps. Useful for confirming transactions, receipts, or generating invoices.
# List Orders
Source: https://docs.name.com/api/v1/reference/orders/list-orders
get /core/v1/orders
Retrieves a list of all orders placed in the account.
# Download Premium Domain Lists
Source: https://docs.name.com/api/v1/reference/premium-domains/download-premium-domain-lists
get /core/v1/premiumdomainslist
Gets a pre-signed URL that will allow a user to download a list of premium domains, with their registration and renewal pricing.
**Please Note:** The pre-signed URL will only be valid for 10 minutes. This endpoint is only available to approved reseller accounts. Contact name.com support to request access.
# Process Refund
Source: https://docs.name.com/api/v1/reference/refunds/process-refund
post /core/v1/refund
Deletes eligible domains and security products during the Add Grace Period (AGP) and automatically issues refunds for the associated order items.
### Eligibility Requirements
- **Product Types**: Only `registration` and `whois_privacy` product types are eligible for refunds.
- **AGP Timing**: Items must be within the Add Grace Period (typically 5 days from registration, varies by TLD).
- **Order Ownership**: All `orderItemIds` must belong to the specified `orderId`.
### Refund Processing
Refunds are processed in the following order:
1. Domain deletion is attempted for each eligible order item
2. Upon successful deletion, the refund is issued
3. Refunds are sent to the original payment method on file
4. If the original payment method is unavailable, the refund is credited to the account balance
### Idempotency
This endpoint supports idempotent requests via the `X-Idempotency-Key` header. If you retry a request with the same idempotency key, you will receive the same response as the original request. This is useful for safely retrying requests without risk of processing duplicate refunds.
# TLD Price List
Source: https://docs.name.com/api/v1/reference/tld-pricing/tld-price-list
get /core/v1/tldpricing
This endpoint returns an alphabetical list of all TLDs supported by name.com, including pricing for each supported order type. All prices are in US Dollars (USD) and apply to non-premium domains. name.com provides three pricing types for each TLD:
- Account-Level Pricing - Your price, including any applicable rebates, promotions, or account-level discounts. This is referenced as 'registrationprice', 'renewalprice', 'transferinprice' and 'domainrestorationprice' in this endpoint.
- Original Pricing (No Discounts Applied) - The suggested retail price (MSRP) before any discounts are applied.
- Retail Pricing (Public Site Pricing) - The current public retail price on name.com, including any public rebates or promotions, but before any account-level discounts.
**Important Notes:**
- Promo codes are not supported through the API, and therefore are not reflected in any pricing values returned.
- General TLD pricing only: This represents standard pricing for domains registered under the specified TLD. Pricing for specific domains may differ based on multiple factors (e.g., premium classifications, registry pricing rules). To retrieve pricing for an individual domain, use the GetPricingForDomain endpoint.
- Availability: If a pricing value is returned as null, that product type is not currently supported for the TLD. (Example: registrationPrice = null means registrations are not currently available.)
- If you do not have account level pricing, the retail price will always match your account level price. (e.g., registration price = registration retail price)
# Cancel External Transfer Out
Source: https://docs.name.com/api/v1/reference/transfers/cancel-external-transfer-out
post /core/v1/transfers/external/out/{domainName}:cancel
Cancels an outbound transfer for the given domain. Use this when the domain is being transferred out of name.com (losing registrar) to another (gaining) registrar and the registrant or reseller wants to cancel that transfer.
The endpoint validates that the domain exists and belongs to the authenticated account. Only domains in a pending transfer (out) state can be canceled.
# Cancel External Transfer In
Source: https://docs.name.com/api/v1/reference/transfers/cancel-transfer
post /core/v1/transfers/{domainName}:cancel
Cancels a pending transfer request. This can be used if the transfer was initiated in error or if the authorization code provided was incorrect.
The price of the transfer will refund the amount to account credit.
Cancelable statuses:
- pending
- submitting_transfer
- pending_new_auth_code
- pending_unlock
- pending_registry_unlock
- rejected
Non-cancelable statuses:
- pending_transfer
- pending_insert
- completed
- failed
- canceled
- canceled_pending_refund
# Create Internal Transfer In
Source: https://docs.name.com/api/v1/reference/transfers/create-internal-transfer-in
post /core/v1/transfers/internal/in
Pulls a domain from another [name.com](https://www.name.com) account into your reseller (gaining) account using a valid authorization code. This is an **internal** name.com-to-name.com move; it is separate from [Create Transfer](/api/v1/reference/transfers/create-transfer), which brings domains in from **external** registrars.
Check if a TLD is eligible for internal transfer in by calling [Tld Requirements](/api/v1/reference/domaininfo/requirementsV2) for the TLD and checking property `supportsInternalTransfer`.
This API is only available to approved reseller accounts. Contact name.com support to request access.
#### Losing account (dashboard only)
The party that holds the domain today must use the name.com dashboard on the **losing** account to **unlock** the domain (remove registrar transfer lock) and to **copy the authorization code** to provide to your integration. This endpoint does not unlock the domain or retrieve the auth code for the losing account.
#### Gaining account (this API)
Call this endpoint with `domainName`, `authCode`, and optional `contacts` using the **gaining** reseller's API credentials.
#### Contacts and post-transfer lock
If `contacts` is omitted, the gaining account's default contacts are applied. If `contacts` is provided, any roles included in the request are applied and omitted roles use the gaining account's default contacts (same pattern as [Create Domain](/api/v1/reference/domains/create-domain) and [Set Contacts](/api/v1/reference/domains/set-contacts)). The 60-day contact-change transfer lock is enforced based on the **gaining** account's settings, consistent with Set Contacts.
#### Access
Restricted to approved enterprise resellers; other callers receive `403 Forbidden`.
# Create External Transfer In
Source: https://docs.name.com/api/v1/reference/transfers/create-transfer
post /core/v1/transfers
Initiates a domain transfer into your name.com account from another registrar. You must provide the domain name and its valid transfer authorization code (EPP code). The domain must not be locked or under any transfer restrictions (e.g. clientTransferProhibited). If successful, the transfer is submitted and tracked through the ICANN transfer process. Once a transfer has been created, you can track its progress via the [GetTransfer](/api/v1/reference/transfers/get-transfer) endpoint.
**Transfer pricing:** Omit `purchasePrice` for standard (non-premium) transfers. For premium transfers, pass `transferPrice` from [Get Pricing For Domain](/api/v1/reference/domains/get-pricing-for-domain) as `purchasePrice`. If sent, it must match Get Pricing `transferPrice` exactly or the request will fail. Premium transfers without `purchasePrice` will fail. See the [Domain pricing guide](/guides/domain-pricing) for how [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) `transferPrice` relates to the `years` query parameter.
# Get Transfer Status
Source: https://docs.name.com/api/v1/reference/transfers/get-transfer
get /core/v1/transfers/{domainName}
Retrieves details of a specific domain transfer request.
# Check Transfer Eligibility
Source: https://docs.name.com/api/v1/reference/transfers/get-transfer-eligibility
get /core/v1/transfers/eligibility/{domainName}
Returns whether a domain is currently registered at [name.com](https://www.name.com) and whether the TLD supports internal transfer between name.com accounts. Use this to decide whether to send your user through the [Create Transfer](/api/v1/reference/transfers/create-transfer) external transfer flow or the [Create Internal Transfer In](/api/v1/reference/transfers/create-internal-transfer-in) flow before initiating a transfer-in.
#### Response semantics
`atName` is `true` if the domain is currently registered at name.com in any account. This information is also publicly available via RDAP.
`supportsInternalTransfer` mirrors the TLD-level value returned by [Tld Requirements](/api/v1/reference/domain-info/get-specific-tld-requirements). It indicates whether the TLD is eligible for internal transfer between name.com accounts. It does not reflect per-account allowlist eligibility — if your account is not allowlisted for internal transfer in, calling [Create Internal Transfer In](/api/v1/reference/transfers/create-internal-transfer-in) will return `403 Forbidden`.
#### Privacy
This endpoint never reveals which account a domain is in. To check whether a domain is in your own account, use [Get Domain](/api/v1/reference/domains/get-domain) instead.
# List Transfers
Source: https://docs.name.com/api/v1/reference/transfers/list-transfers
get /core/v1/transfers
Returns all domain transfer requests for the account, including in-progress and recent transfers.
# Create URLForwarding
Source: https://docs.name.com/api/v1/reference/url-forwardings/create-urlforwarding
post /core/v1/domains/{domainName}/url/forwarding
Sets up a new URL forwarding (redirect) for a domain or subdomain. If this is the first URL forwarding entry, it may modify the A records for the domain accordingly. Note that changes may take up to 24 hours to fully propagate.
# Delete URLForwarding
Source: https://docs.name.com/api/v1/reference/url-forwardings/delete-urlforwarding
delete /core/v1/domains/{domainName}/url/forwarding/{host}
Removes a URL forwarding configuration from the domain. This operation cannot be undone. **Deprecated.** Use [Delete URL Forwarding by ID](/api/v1/reference/url-forwardings/delete-urlforwarding-by-id) instead.
# Delete URL Forwarding by ID
Source: https://docs.name.com/api/v1/reference/url-forwardings/delete-urlforwarding-by-id
delete /core/v1/urlforwarding/{domainName}/{id}
Removes a URL forwarding configuration by ID. The domain must be owned by the authenticated account. This operation cannot be undone.
# Get URLForwarding
Source: https://docs.name.com/api/v1/reference/url-forwardings/get-urlforwarding
get /core/v1/domains/{domainName}/url/forwarding/{host}
Retrieves the details of a specific URL forwarding configuration. **Deprecated.** Use [Get URL Forwarding by ID](/api/v1/reference/url-forwardings/get-urlforwarding-by-id) instead.
# Get URL Forwarding by ID
Source: https://docs.name.com/api/v1/reference/url-forwardings/get-urlforwarding-by-id
get /core/v1/urlforwarding/{domainName}/{id}
Retrieves the details of a specific URL forwarding configuration by ID. The domain must be owned by the authenticated account.
# List URLForwardings
Source: https://docs.name.com/api/v1/reference/url-forwardings/list-urlforwardings
get /core/v1/domains/{domainName}/url/forwarding
Returns all URL forwarding settings configured for a domain. **Deprecated.** Use [List URL Forwardings by domain](/api/v1/reference/url-forwardings/list-urlforwardings-by-domain) instead, which returns entries with an `id` for use with by-ID endpoints.
# List URL Forwardings by domain
Source: https://docs.name.com/api/v1/reference/url-forwardings/list-urlforwardings-by-domain
get /core/v1/urlforwarding/{domainName}
Returns all URL forwarding settings configured for a domain. Each entry includes an `id` that can be used with the URL Forwarding by-ID endpoints to get, update, or delete records.
# Update URLForwarding
Source: https://docs.name.com/api/v1/reference/url-forwardings/update-urlforwarding
put /core/v1/domains/{domainName}/url/forwarding/{host}
Modifies an existing URL forwarding rule. Changes may take up to 24 hours to fully propagate. **Deprecated.** Use [Update URL Forwarding by ID](/api/v1/reference/url-forwardings/update-urlforwarding-by-id) instead.
# Update URL Forwarding by ID
Source: https://docs.name.com/api/v1/reference/url-forwardings/update-urlforwarding-by-id
patch /core/v1/urlforwarding/{domainName}/{id}
Modifies an existing URL forwarding rule by ID. The domain must be owned by the authenticated account. Changes may take up to 24 hours to fully propagate.
# Create Vanity Nameserver
Source: https://docs.name.com/api/v1/reference/vanity-nameservers/create-vanity-nameserver
post /core/v1/domains/{domainName}/vanity_nameservers
Register a new vanity nameserver for the specified domain.
# Delete Vanity Nameserver
Source: https://docs.name.com/api/v1/reference/vanity-nameservers/delete-vanity-nameserver
delete /core/v1/domains/{domainName}/vanity_nameservers/{hostname}
Deletes a vanity nameserver from the domain’s registry settings. This operation might fail if the registry detects the nameserver is still in use.
# Get Vanity Nameserver
Source: https://docs.name.com/api/v1/reference/vanity-nameservers/get-vanity-nameserver
get /core/v1/domains/{domainName}/vanity_nameservers/{hostname}
Retrieves details for a of a specific vanity nameserver (including its IP addresses).
# List Vanity Nameservers
Source: https://docs.name.com/api/v1/reference/vanity-nameservers/list-vanity-nameservers
get /core/v1/domains/{domainName}/vanity_nameservers
Lists all vanity nameserver hostnames configured for a domain.
# Update Vanity Nameserver IP
Source: https://docs.name.com/api/v1/reference/vanity-nameservers/update-vanity-nameserver-ip
put /core/v1/domains/{domainName}/vanity_nameservers/{hostname}
Updates the glue record IP addresses for a vanity nameserver.
# Account Credit Balance Change
Source: https://docs.name.com/api/v1/reference/webhook-notifications/account-credit-balance-change
webhook accountCreditBalanceChange
This is the payload that will be sent to the subscribed URL, when a changed to the amount of account credit for an account changes. This will trigger on both increases and decreases in account credit for the account.
# Contact Verification Status Change
Source: https://docs.name.com/api/v1/reference/webhook-notifications/contact-verification-status-change
webhook contactVerificationStatusChange
This is the payload that will be sent to the subscribed URL, when a change to contact verification status occurs. This will trigger on both verified and unverified contact status change events.
# Delete Subscription
Source: https://docs.name.com/api/v1/reference/webhook-notifications/delete-subscription
delete /core/v1/notifications/{id}
Removes a webhook subscription from the account.
# Domain Lock Status Change
Source: https://docs.name.com/api/v1/reference/webhook-notifications/domain-lock-status-change
webhook domainLockStatusChange
Sent when a domain lock is added or removed, which may restrict or lift normal operations. This event is triggered automatically whenever covered lock types (e.g., compliance or verification holds) are added or removed. A webhook payload is delivered to the subscribed endpoint, providing details about the domain and its updated status.
# Domain Registry Rejection
Source: https://docs.name.com/api/v1/reference/webhook-notifications/domain-registry-rejection
webhook domainRegistryRejection
Sent when you have subscribed to this event on your account, and a domain **create** request fails after asynchronous registry processing. Most registrations complete successfully at create time; this webhook covers the uncommon case where processing completes later with a failure.
# Internal Transfer In Status Change
Source: https://docs.name.com/api/v1/reference/webhook-notifications/domain-transfer-internal-in-status-change
webhook domainTransferInternalInStatusChange
Sent when you have subscribed to the event on your account, and a name.com domain transfers into your account.
# Domain Transfer Out Status Change
Source: https://docs.name.com/api/v1/reference/webhook-notifications/domain-transfer-out-status-change
webhook domainTransferOutStatusChange
Sent when you have subscribed to the event on your account, and a domain transfer OUT from name.com to another registrar has a status change. Status may be "initiated" (transfer out was started), "completed" (domain has been removed from name.com), or "canceled" (transfer out was canceled before completion).
When status is "completed", the domain has been removed from name.com. In some edge cases (including near-expiration scenarios) the data may not be fully accurate. For example, registry sync delays or edge timing around expiration can cause temporary discrepancies between the payload and the registry’s eventual state.
# Domain Transfer In Status Change
Source: https://docs.name.com/api/v1/reference/webhook-notifications/domain-transfer-status-change
webhook domainTransferStatusChange
Sent when you have subscribed to the event on your account, and a domain transfer IN to name.com is processing.
This webhook reports status changes for transfers where name.com is the gaining registrar (i.e., transfers into your name.com account).
# Get Subscribed Notifications
Source: https://docs.name.com/api/v1/reference/webhook-notifications/get-subscribed-notifications
get /core/v1/notifications
Retrieves all active webhook subscriptions on the account.
# Modify Subscription
Source: https://docs.name.com/api/v1/reference/webhook-notifications/modify-subscription
put /core/v1/notifications/{id}
Updates an existing webhook’s configuration. This may include changing the callback URL or updating whether the webhook is currently active.
# Webhooks Overview
Source: https://docs.name.com/api/v1/reference/webhook-notifications/overview
How name.com webhook notifications work and how to subscribe.
# Webhooks
name.com can send **HTTP POST** requests to a URL you provide when specific domain or account events occur. Each request includes a JSON body with an `eventName` field that identifies the event type.
## How it works
1. **Choose event types** — Pick one or more `eventName` values (for example `domain.transfer.status_change`).
2. **Create a subscription** — Call [Subscribe to Notification](/api/v1/reference/webhook-notifications/subscribe-to-notification) with your callback URL and the event names you want.
3. **Handle POST requests** — Your server receives payloads when those events occur. Respond with `2xx` to acknowledge delivery.
4. **Verify signatures** — Every request includes `X-NAMECOM-SIGNATURE`. Validate it before processing. See [HMAC signature verification](/guides/hmac-examples).
Manage subscriptions anytime with [Get Subscribed Notifications](/api/v1/reference/webhook-notifications/get-subscribed-notifications), [Modify Subscription](/api/v1/reference/webhook-notifications/modify-subscription), or [Delete Subscription](/api/v1/reference/webhook-notifications/delete-subscription).
Event names are stable API identifiers. Use the exact `eventName` string from the payload reference page when subscribing and when routing in your handler (for example `domain.transfer.status_change`, not a display label).
# Subscribe to Notification
Source: https://docs.name.com/api/v1/reference/webhook-notifications/subscribe-to-notification
post /core/v1/notifications
Creates a webhook subscription to receive real-time notifications about specific domain or account events (e.g. transfer completions, renewals). Pass the callback URL and event types. This allows external systems to stay in sync with name.com changes.
Supported webhook event names:
- `account.credit.balance_change` – account credit balance changes (increases or decreases).
- `domain.lock.status_change` – domain lock added or removed.
- `domain.transfer.status_change` – domain transfer IN to name.com; status updates while name.com is the gaining registrar.
- `domain.transfer_out.status_change` – domain transfer OUT from name.com to another registrar; fires when the domain is removed from the account.
- `domain.transfer.internal_in` - name.com domain transfers in to the subscribing account.
- `contact.verification.status_change` - contact verification status changes (verified or unverified).
- `domain.registry.rejection` – domain **create** failed after asynchronous registry processing (uncommon; most creates succeed at request time).
# Authentication
Source: https://docs.name.com/guides/authentication
How to authenticate with the name.com Core API using HTTP Basic Auth.
The Core API uses **HTTP Basic Authentication** with your name.com API credentials. You can either use cURL's convenient `-u` shorthand or provide the explicit `Authorization` header.
Using `-u username:token` is equivalent to sending `Authorization: Basic `.
## Quick Example
```bash theme={null}
curl -u your-username:your-api-token https://api.dev.name.com/core/v1/hello
```
## Understanding Basic Authentication Examples
You may notice some examples show the explicit `Authorization: Basic ` header. This is functionally identical to the simpler cURL shorthand:
```bash theme={null}
# Preferred, user-friendly syntax
curl -u : ...
```
The server requires the header format; the `-u` flag tells `curl` to automatically create and Base64-encode your `:` string.
If you need to manually generate the required Base64 `` for use in another tool (or to copy into examples):
1. Combine your credentials: `:` (e.g., `janedoe:tok_12345`)
2. Encode the string using one of the following methods:
| Environment | Command to Generate Encoded Value | |
| :----------------------- | :------------------------------------------------------------------------------- | -------- |
| **Linux/macOS (Bash)** | \`echo -n 'janedoe:tok\_12345' | base64\` |
| **Windows (PowerShell)** | `[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("janedoe:tok_12345"))` | |
Once you have the encoded value, you can use it with an explicit header:
```bash theme={null}
curl --request GET \
--url https://api.dev.name.com/core/v1/hello \
--header 'Authorization: Basic '
```
## Sandbox vs Production
Use your sandbox credentials for the development environment (`https://api.dev.name.com`) and production credentials for `https://api.name.com`.
```bash Sandbox theme={null}
curl -u your-username-test:your-sandbox-token https://api.dev.name.com/core/v1/hello
```
```bash Production theme={null}
curl -u your-username:your-api-token https://api.name.com/core/v1/hello
```
If your account has 2FA enabled, enable API Access in Account Settings → Security. Always keep tokens secure and never commit them to source control.
# Claims Flow
Source: https://docs.name.com/guides/claims-flow
4-step guide with examples on how to register domains with claims. Note: Example domain names, trademarks, and other data shown below are dummy data used for illustrative purposes only.
# Steps to Register a Domain with a Claims Check
## 1. Check TLD Info for Claims Support
Use the [TLD Requirements](/api/v1/reference/domain-info/get-specific-tld-requirements) (Domain Info) endpoint to determine whether a TLD supports claims.
**Example Response:**
```json theme={null}
"claimsCheckRequired": [
"registration"
]
```
Until additional pre-order types are supported in the API, the `purchaseType` should always be `registration`.
## 2. Retrieve Claims Data (if applicable)
If `claimsCheckRequired` is not an empty array, you will need to check your domain using the Claims Lookup endpoint.
Please note: A TLD may support claims, but an individual domain under that TLD might not have any active claims.
The POST `/core/v1/domaininfo/claims/{domain}` returns:
* any trademark claims that apply to the domain (message you must display to the registrant). The purchaser isn’t required to submit any documentation, and it’s not the reseller's responsibility to verify their trademark rights. The reseller's only obligation is to display the required notice before they complete the purchase.
* a `claimID` and `notAfter` that must be included on the Domain Create request. The `notBefore` and `notAfter` is the validity window of the response data. If you are getting claims response data, it's valid only for about 2 days and it needs to be submitted to domainCreate within that validity window. In order to use the claimID output, you'll need to submit the domainCreate before `notAfter` expires.
If there are claims, `claimsNotice` will contain generic copy in markdown. You must display this mandatory trademark notice to your end users. Use the claims array to loop through and display each claim.
**Example Response:**
```json theme={null}
{
"domain": "hello.page",
"claims": [
{
"trademark": "EXAMPLE",
"holder": "Acme Global Holdings Inc.",
"jurisdiction": "United States Patent and Trademark Office (USPTO)",
"description": "Class 9: Computer software; Class 42: Software as a service (SaaS) - 123 Main Street, Anytown, CA, 90210, US"
},
{
"trademark": "E.X.A.M.P.L.E",
"holder": "Beta Financial Group",
"jurisdiction": "Office of the European Union for Intellectual Property (EUIPO)",
"description": "Class 36: Financial services, banking, insurance, investment consultation, and electronic funds transfer. - Avenue des Champs-Élysées, PARIS, 75008, FR"
},
{
"trademark": "Example!",
"holder": "Zeta Media Partners",
"jurisdiction": "Canadian Intellectual Property Office (CIPO)",
"description": "Class 16: Printed publications, magazines, and periodicals; Class 41: Entertainment services, namely, providing online video content. - 456 Queen Street, TORONTO, ON, M5V 2H7, CA"
}
],
"claimsProcessActive": true,
"claimId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"notBefore": "2025-12-01T00:00:00.0Z",
"notAfter": "2025-12-08T00:00:00.0Z",
"claimsNotice": "You have received this Trademark Notice because you have applied for a domain name which matches at least one trademark record submitted to the Trademark Clearinghouse.\n\nYou may or may not be entitled to register the domain name depending on your intended use and whether it is the same or significantly overlaps with the trademark listed below. **Your rights to register this domain name may or may not be protected as noncommercial use or \"Fair use\" by the laws of your country.**\n\nPlease read the trademark information below carefully, including the trademarks, jurisdictions, and goods and service for which the trademarks are registered. Please be aware that not all jurisdictions review trademark applications closely, so some of the trademark information may exist in a national or regional registry which does not conduct a thorough or substantive review of trademark rights prior to registration. **If you have questions, you may want to consult an attorney or legal expert on trademarks and intellectual property for guidance.**\n\nIf you continue with this registration, you represent that, you have received and you understand this notice and to the best of your knowledge, your registration and use of the requested domain name will not infringe on the trademark rights listed below. For more information concerning the records included in this notice, see [http://claims.clearinghouse.org](http://claims.clearinghouse.org).\n\nThe following Trademarks are listed in the Trademark Clearinghouse:"
}
```
## 3. Check Domain Availability, Fetch Pricing and Purchase Type
Use the [Check Availability](/api/v1/reference/domains/check-availability) endpoint to ensure the domain is available for purchase and to retrieve `purchasePrice` and `purchaseType` needed for the registration request. Domains with active claims may have premium pricing so in these cases pricing information must also be passed on the create domain request.
Please note: If you are using the [ZoneCheck](/api/v1/reference/domains/zone-check) endpoint, continue using it for your existing search experience. Use the Check Availability endpoint only when you need to purchase a domain that has claims.
**Example Response:**
```json theme={null}
{
"domainName": "hello.page",
"premium": true,
"purchasable": true,
"purchasePrice": 349.95,
"purchaseType": "registration",
"renewalPrice": 349.95,
"sld": "hello",
"tld": "page"
}
```
## 4. Submit Domain Create Request
Finally, call the [Create Domain](/api/v1/reference/domains/create-domain) endpoint to register the domain.
**Important Notes:**
* The `claims` parameter must be passed.
* The `purchasePrice` parameter also must be passed. The `purchaseType` parameter should be set (and currently defaults) to `registration`.
**Example Request:**
```json theme={null}
{
"domain": {
"domainName": "hello.page"
},
"claims": {
"claimId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"notBefore": "2025-12-01T00:00:00.0Z",
"notAfter": "2025-12-08T00:00:00.0Z"
},
"purchasePrice": 349.95,
"purchaseType": "registration"
}
```
Please Note: If the If the trademark owner takes issue with the registration, the trademark owner could:
* Directly contact the registrant - They can attempt to contact the registrant using the email listed in WHOIS. Even when privacy protection is enabled, the privacy or proxy service typically forwards messages to the actual registrant. From there, the registrant can decide whether to transfer, cancel, or otherwise resolve the issue directly.
* File a complaint under the Uniform Domain Name Dispute Resolution Policy (UDRP) - A dispute-resolution process under the UDRP, offered by providers such as WIPO and others, that allows trademark owners to request the transfer or cancellation of a domain by showing that the name is identical or confusingly similar to their mark, the registrant lacks legitimate rights or interests, and the domain was registered and used in bad faith.
# Contact Verification Compliance
Source: https://docs.name.com/guides/contact-verification
ICANN contact verification email requirements, reseller logging obligations, and how to integrate contact verification endpoints + webhooks without duplicating documentation.
## What this guide covers
This guide covers:
* **How name.com contact verification works** (timelines, email types, and how to observe verification status).
* **How to integrate status updates** via the `contact.verification.status_change` webhook.
* **What changes when you handle verification yourself** (approved/contracted resellers): logging requirements, required email content, and account-restricted endpoints.
If you’re looking for endpoint request/response schemas, use the API reference pages directly:
* `GET /core/v1/contacts/unverified` → [List Unverified Contacts](/api/v1/reference/contact-verification/list-unverified-contacts)
* `POST /core/v1/contacts/verify/{verificationId}` → [Verify Contact](/api/v1/reference/contact-verification/verify-contact)
* `POST /core/v1/contacts/verify/{verificationId}:resend` → [Resend Verification Email](/api/v1/reference/contact-verification/resend-verification-email)
* `contact.verification.status_change` → [Contact Verification Status Change webhook](/api/v1/reference/webhook-notifications/contact-verification-status-change)
## When this guide applies
You should follow this guide if you do any of the following:
* Need to understand **when verification emails are sent** and what the **15-day verification timeline** means for domains.
* Want to **monitor verification status** in your product using endpoints and/or webhooks.
* Have an approved / contracted setup where you **send your own verification emails** and/or **sync verified state** to name.com.
For most reseller integrations, **name.com sends the ICANN-required verification emails** for you. If you want to handle verification emails (or verification state syncing) yourself, this is typically an **approved / contracted** workflow so we can confirm you will meet ICANN requirements (including logging and required email content).
## Part 1: How contact verification works (most resellers)
This section is for most resellers. It explains how verification works, the ICANN-required email timeline, and how to observe verification status in your integration.
### What “verification” means
Verification means the registrant has demonstrated control of the email address (or phone number, where applicable) associated with the registrant contact.
If verification is not completed within the required window, a verification lock will be applied and the domain will stop resolving. See [Understanding Domain Locks](/guides/domain-locks).
### ICANN verification email timeline (what gets sent)
These requirements apply when **ICANN requires verification** of the registrant contact (typically email).
| Email | Trigger | Required content |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Registrant verification (expires in 15 days)** | Domain registration, incoming transfer with an unverified registrant email, or changes to the registrant’s email, name, or organization | A clear statement that ICANN requires verification of the registrant contact. A unique verification link or token the user must click or use. A warning that failure to verify within 15 days will result in domain suspension. |
| **Verification reminder** | Before the 15‑day window expires | A clear statement that ICANN requires verification of the registrant contact. A unique verification link or token the user must click or use. A warning that failure to verify within 15 days will result in domain suspension, including how many days remain. |
| **Verification expired / suspension notice** | Day 16+ (when the domain is disabled) | Notification that the domain is suspended and the reason (failure to verify registrant contact). Mention that this is ICANN-required. Provide a path to resolve (for example: a verification link). |
For new registrants, you must also communicate:
The Organization field in your domain’s contact details relates to legal ownership. If this field contains information, the listed organization is considered the legal “Registered Name Holder” (domain owner).
### How to observe verification status
* `GET /core/v1/contacts/unverified` → [List Unverified Contacts](/api/v1/reference/contact-verification/list-unverified-contacts)
After a new domain registration or contact change, unverified contacts may take up to \~10 minutes to appear in the API. Build your UI and automation with this delay in mind.
### Status updates via webhook
To avoid polling, subscribe to the contact verification status webhook:
* Event: `contact.verification.status_change`
* Reference: [Contact Verification Status Change webhook](/api/v1/reference/webhook-notifications/contact-verification-status-change)
Verify webhook authenticity using HMAC signatures. See [HMAC Signature Verification](/guides/hmac-examples).
To create/manage webhook subscriptions:
* [Subscribe to notification](/api/v1/reference/webhook-notifications/subscribe-to-notification)
* [Get subscribed notifications](/api/v1/reference/webhook-notifications/get-subscribed-notifications)
* [Modify subscription](/api/v1/reference/webhook-notifications/modify-subscription)
* [Delete subscription](/api/v1/reference/webhook-notifications/delete-subscription)
## Part 2: Handling your own verification (approved / contracted resellers)
This section is for resellers who have agreed to additional terms and are handling contact verification themselves. This typically includes additional compliance requirements and may include account-restricted endpoint access.
If you want to discuss enablement, email [reseller@name.com](mailto:reseller@name.com).
### Logging requirements
If you send your own verification emails (and disable name.com-sent emails) and/or use account-restricted contact verification endpoints, you must maintain the following logs.
#### Email logs (ICANN verification emails)
Keep logs for every verification-related email you send:
* **Domain**
* **Email send event**
* **Timestamp**
* **Recipient**
* **Subject**
* **Content** (or a reference to a stored template + the rendered variables used)
#### Verification logs
Keep logs that show how you verified the registrant contact off-platform:
* **Domain** and the **`verificationId`** being verified
* **Verification method** (email or phone)
* **Email address or phone number** used for verification
* **Verification timestamp**
#### Retention and access
* **Retention**: All required logs must be kept for the duration of the domain registration and for at least **two (2) years thereafter**.
* **Access**: name.com may request access to these logs at any time.
#### What you must provide before enablement
Before we grant you access to programmatic contact verification and allow you to disable name.com-sent emails, you must provide:
* **Sample logs** demonstrating the format above
* **Sample email copies** (templates and/or example sends)
### Endpoint usage & policy
Some Contact Verification endpoints are **account-restricted**. The reference pages will call this out, and you can email [reseller@name.com](mailto:reseller@name.com) to request access.
#### List Unverified Contacts
**Purpose**: Identify contacts that require verification under ICANN rules.
* Endpoint: `GET /core/v1/contacts/unverified` → [List Unverified Contacts](/api/v1/reference/contact-verification/list-unverified-contacts)
* Typical use: Drive your own verification flow (email or phone) before calling Verify Contact (if approved).
#### Verify Contact
**Purpose**: Programmatically marks a contact’s email address as verified for domains under your account (to satisfy ICANN contact-verification requirements).
* Endpoint: `POST /core/v1/contacts/verify/{verificationId}` → [Verify Contact](/api/v1/reference/contact-verification/verify-contact)
* Availability: **Account-restricted (approved reseller accounts only)**
* Retry safety: Send `X-Idempotency-Key` so retries are safe
This endpoint is account-restricted. Enablement is typically associated with handling your own verification process and meeting ICANN compliance requirements (logging and required email content).
#### Allowed use
* **You are the reseller of record** and the contact belongs to a domain in your account.
* You have **already verified** control of the email address or phone number **off-platform** (for example: your own email verification link flow) and are syncing that verified state to name.com.
* You are acting on behalf of the registrant and have their permission to mark the contact as verified.
#### Not allowed
* Verifying contacts you don’t manage
* Marking contacts verified without actually verifying the email/phone
* Acting without registrant authorization
#### Enforcement
We may suspend access to this endpoint if we detect misuse.
#### Resend the initial verification email
If a contact verification is pending and you need to resend the initial verification email, use:
* `POST /core/v1/contacts/verify/{verificationId}:resend` → [Resend Verification Email](/api/v1/reference/contact-verification/resend-verification-email)
This endpoint is throttled (for example: per-`verificationId` and per-account rate limits). See the endpoint reference for the current limits and the `nextEligibleAt` cooldown timestamp returned in responses.
## Other ICANN-required emails
For more detailed information about ICANN-required emails, see [Registrant Communication Options](/guides/registrant-communications).
# Understanding Domain Locks
Source: https://docs.name.com/guides/domain-locks
Overview of verification, compliance/security, and customer-controlled domain locks, including when they apply and their impact.
## Verification Locks
These locks are applied due to the mandatory ICANN requirement to verify domain contact information within 15 days of registration or change.
### VerificationClientHold (High Volume Reseller Domains)
* Applied to: Reseller domains when contacts are not verified within 15 days. This lock is applied at the registry level.
* Impact: The domain is removed from the DNS and will not resolve (it goes completely offline).
### VerificationHold (Retail Customers and Medium-Low Volume Reseller Domains)
* Applied to: Retail customer and medium-low volume reseller domains when contacts are not verified within 15 days.
* Impact: The domain is redirected to a name.com landing page that explains the ICANN contact verification requirement.
## Compliance & Security Locks
These locks are applied for policy, security, legal reasons, or by the customer for enhanced protection.
### ClientHold (Compliance/Abuse)
* Applied to: Deactivate a domain, typically for serious policy violations or abusive activity (e.g., DNS Abuse, CSAM, Fraud).
* Impact: The domain is removed from the DNS and will not resolve (it goes completely offline).
### ExpirationClientHold (Post-Expiration)
* Applied to: Domains for certain reseller accounts after expiration.
* Purpose: Applies a ClientHold status at the registry to ensure the domain is removed from the DNS and will not resolve. This status removes the domain from the global DNS system, meaning the domain's website, email, and other services will be inaccessible.
### RegistrarLock / AccountLock (Administrative/Legal)
* Applied to: Domains due to compliance or legal complaints.
* Restrictions: Prohibits Client Transfers (Registrar to Registrar) and Account Transfers (internal name.com transfers). All domain modifications are disabled (DNS/nameservers and contact changes).
### TransferLock (60-Day Lock)
* Applied to: Triggered by new domain registrations, transfers into name.com, and specific contact updates (unless the registrant opts out of the 60-day lock).
* Restriction: Prohibits Client Transfers (registrar to registrar) for 60 days.
* Key Difference: This lock does NOT prevent DNS, nameserver, or contact changes—only transfers out are blocked.
### PrivacyLock (Customer Controlled - Requires 2FA)
* Applied to: A security lock controlled by the customer that has the same strong restrictions as RegistrarLock/AccountLock.
* Requirement: Two-Factor Authentication (2FA) must be set up on the account to enable this lock, and a 2FA code is required to disable it.
* API Note: This lock cannot be managed via the API and must be done on the name.com retail site.
# Domain Purchase Pricing
Source: https://docs.name.com/guides/domain-pricing
Which endpoints to call for Create, Renew, and Transfer pricing — Search, Check Availability, Zone Check, Get Pricing, and every purchaseType.
Use this guide to answer: **which endpoint(s) do I call to get the price I must send on Create Domain, Renew, or Transfer?**
**Recommended:** Scope discovery to `purchaseType: registration` unless you explicitly need aftermarket, expiring, or backorder inventory. Registration is the simplest path — predictable pricing, immediate fulfillment, and standard [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) flows. Other types are supported but add complexity (flat acquisition fees, term quirks, third-party delays). Pass `purchaseType: registration` on [Search](/api/v1/reference/domains/search) and [Check Availability](/api/v1/reference/domains/check-availability) to filter them out; if checkout returns a different type, treat it as unsupported in your UI until you are ready to handle acquisition pricing.
## Endpoint roles
| Endpoint | Role | Pricing data | `purchaseType`? |
| ------------------------------------------------------------------ | ------------------------------------------ | ---------------------------------------------------- | --------------- |
| [Zone Check](/api/v1/reference/domains/zone-check) | Fast DNS signal for bulk browse UI | **No** — `available` only | **No** |
| [Check Availability](/api/v1/reference/domains/check-availability) | **Discovery** at checkout | **Yes** — `purchasePrice`, `premium`, `purchaseType` | **Yes** |
| [Search](/api/v1/reference/domains/search) | **Discovery** for keyword/suggestion flows | **Yes** — `purchasePrice`, `premium`, `purchaseType` | **Yes** |
| [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) | Registry reg/renew/transfer calculator | `purchasePrice`, `renewalPrice`, `transferPrice` | **No** |
| [TLD Pricing](/api/v1/reference/tld-pricing/tld-price-list) | TLD-level list prices (non-premium) | TLD tables only | **No** |
**Check Availability and Search** return the same result field set but serve different use cases. Search offers keyword-based suggestions while Check Availability is used for specific domain checks.
**Zone Check** cannot price a purchase or determine `purchaseType`. It only indicates whether a name appears free in DNS. Use Check Availability or Search to gather information needed to complete a purchase.
## Two pricing sources for Create Domain
1. **Registry pricing** (`purchaseType: registration`) — standard + registry premium
* [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) returns authoritative totals for a given `years`
* Standard non-premium: omit `purchasePrice` on create
* Registry premium: **required** `purchasePrice` from Get Pricing with matching `years`
2. **Acquisition pricing** (`aftermarket_s`, `aftermarket_b`, `aftermarket_i`, `expiring`, `backorder`) — *advanced; only if you support non-registration inventory*
* **Search or Check Availability** returns the flat acquisition `purchasePrice`
* **Always required** on create; does **not** multiply by `years`
## Create Domain: `purchasePrice` and `years`
| Scenario | `purchaseType` | `premium` | `purchasePrice` | `years` |
| --------------------- | ------------------------------------------------- | ------------ | ------------------------------------------- | ---------------------------------------------------------------------- |
| Standard registration | `registration` | `false` | **Omit** (optional quote from Get Pricing) | **Set term** |
| Registry premium | `registration` | `true` | **Yes** — from Get Pricing | **Set term** — same value on Get Pricing |
| Aftermarket | `aftermarket_s`, `aftermarket_b`, `aftermarket_i` | often `true` | **Yes** — from Search or Check Availability | **Omit or TLD default** — does not affect price or registration length |
| Expiring | `expiring` | varies | **Yes** — from Search or Check Availability | **Omit or TLD default** — does not affect price or registration length |
| Backorder | `backorder` | varies | **Yes** — from Search or Check Availability | **Omit or TLD default** — does not affect price or registration length |
For `purchaseType: registration`, `premium` determines whether `purchasePrice` is required; `years` sets the registration term. When using Get Pricing to preview or validate, pass the same `years`. For any other `purchaseType`, `purchasePrice` is **always required** — regardless of `premium`.
`purchasePrice` is the domain fee only; Whois Privacy is charged separately when `privacyEnabled` is true.
If you send `purchasePrice`, it must match exactly to the cent or the request will fail.
## Getting the price for Create Domain
1. Call **Search** or **Check Availability** (not Zone Check, not Get Pricing alone). Copy `purchaseType`, `premium`, and note `purchasePrice`.
2. Branch on `purchaseType`:
**`registration` + `premium: false`**
* Optional: call Get Pricing with the same `years` to quote the total.
* On create: omit `purchasePrice`, set `years` (no prior Get Pricing call required).
**`registration` + `premium: true`** (registry premium)
* Call Get Pricing with same `years` → pass `purchasePrice` exactly to the cent on create.
**`aftermarket_s` | `aftermarket_b` | `aftermarket_i` | `expiring` | `backorder`**
* Use Search or Check Availability `purchasePrice` (flat acquisition fee).
* Re-check discovery immediately before create — price can change.
* Do **not** use Get Pricing for create price.
* `years` does not multiply price or guarantee multi-year registration.
3. Renew and Transfer use Get Pricing separately — see sections below.
## Integrator workflow patterns
Pick the path that matches your UX. Every path should re-run [Check Availability](/api/v1/reference/domains/check-availability) right before [Create Domain](/api/v1/reference/domains/create-domain) as pricing and availability can change.
### Pattern A: Registration only (recommended default)
Standard reseller checkout: fresh registrations and registry premiums only. Pass `purchaseType: registration` on discovery calls.
1. **Discover:** [Search](/api/v1/reference/domains/search) with `purchaseType: registration` — show suggestions, `purchasePrice`, `renewalPrice`; mark premiums.
2. **Checkout:** [Check Availability](/api/v1/reference/domains/check-availability) with `purchaseType: registration` — confirm `purchasable`, `premium`, and `purchasePrice`.
3. **Price:** `premium: false` → omit `purchasePrice`, set `years`. `premium: true` → [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) with same `years` → pass `purchasePrice` on create.
4. **Purchase:** [Create Domain](/api/v1/reference/domains/create-domain) with `purchaseType: registration`.
Non-matching domains: Check Availability returns them with `purchasable: false`; Search omits them. If checkout still surfaces a non-registration `purchaseType`, treat it as unsupported in your UI.
### Pattern B: Zone Check + Check Availability combination
For bulk browse UIs powered by [Zone Check](/api/v1/reference/domains/zone-check). No Search required — still registration-only.
1. **Browse:** Zone Check → `available` hint for UI only (no pricing or `purchaseType`).
2. **Checkout → purchase:** Follow steps 2–4 of **Registration only** above (`purchaseType: registration` on Check Availability).
### Pattern C: All purchase types (advanced)
Only if you explicitly support aftermarket, expiring, or backorder. **Omit** the `purchaseType: registration` filter.
1. **Discover:** [Search](/api/v1/reference/domains/search) or [Check Availability](/api/v1/reference/domains/check-availability) without a filter — acquisition types may appear alongside registration.
2. **Checkout:** Re-run Check Availability without a filter — confirm `purchaseType`, `premium`, and `purchasePrice` (see [Getting the price for Create Domain](#getting-the-price-for-create-domain); acquisition types use flat discovery fees, not Get Pricing).
3. **Purchase:** [Create Domain](/api/v1/reference/domains/create-domain) with matching `purchaseType` and `purchasePrice` when required.
## Renew Domain
| Scenario | Price source | `purchasePrice` on renew |
| ---------------- | ------------------------------------------------ | ------------------------------------------------ |
| Standard renewal | Get Pricing (optional quote) | **Omit** |
| Premium renewal | Get Pricing `renewalPrice` with matching `years` | **Yes** — pass `renewalPrice` as `purchasePrice` |
Do not use Search or Check Availability `renewalPrice` for premium renewals.
## Transfers
| Scenario | Price source | `purchasePrice` on transfer |
| ----------------- | ---------------------------- | ------------------------------------------------- |
| Standard transfer | Get Pricing (optional quote) | **Omit** |
| Premium transfer | Get Pricing `transferPrice` | **Yes** — pass `transferPrice` as `purchasePrice` |
Get Pricing `transferPrice` is not affected by the `years` query parameter. `purchasePrice` is the domain transfer fee only; Whois Privacy is charged separately when `privacyEnabled` is true. If you send `purchasePrice`, it must match Get Pricing `transferPrice` exactly to the cent or Create Transfer returns `400` and `"Invalid Price"`. Premium transfers without `purchasePrice` return `"PurchasePrice is required if the domain to transfer is a premium domain"`.
## Registry premium vs acquisition
*Skip this section if you scope discovery to `purchaseType: registration` only.*
Both can show `premium: true` in discovery results, but pricing works differently.
### Registry premium
`purchaseType: registration` with `premium: true`. Call Get Pricing with matching `years`; pass `purchasePrice` on create.
```json theme={null}
{
"domain": { "domainName": "premiumexample.com" },
"purchaseType": "registration",
"years": 2,
"purchasePrice": 699.90
}
```
### Aftermarket, expiring, and backorder
Flat acquisition fee from Search or Check Availability — `years: 5` with `purchasePrice: 5000` still charges **\$5,000**. Omit `years` or pass the TLD default.
```json theme={null}
{
"domain": { "domainName": "rarename.com" },
"purchaseType": "aftermarket_s",
"purchasePrice": 5000.00
}
```
Check `domain.expireDate` after create; renew to extend registration.
## Standard registration (non-premium)
```json theme={null}
{
"domain": { "domainName": "example.com" },
"years": 2
}
```
Omit `purchasePrice` on create. Optionally call Get Pricing with matching `years` to quote the total.
## What not to do
* Do **not** use Zone Check for `purchaseType`, `purchasePrice`, or checkout pricing
* Do **not** use Get Pricing alone to discover how a domain is acquired
* Do **not** use Get Pricing `purchasePrice` for aftermarket, expiring, or backorder create
* Do **not** multiply discovery `purchasePrice` × `years` for acquisition types
* Do **not** use discovery `renewalPrice` for create or premium renew totals
* Do **not** include VAT in `purchasePrice` or derive it from `totalPaid`
## Related endpoints
* [Check Availability](/api/v1/reference/domains/check-availability)
* [Create Domain](/api/v1/reference/domains/create-domain)
* [Create Transfer](/api/v1/reference/transfers/create-transfer)
* [Get Pricing For Domain](/api/v1/reference/domains/get-pricing-for-domain)
* [Renew Domain](/api/v1/reference/domains/renew-domain)
* [Search](/api/v1/reference/domains/search)
* [TLD Price List](/api/v1/reference/tld-pricing/tld-price-list)
* [Zone Check](/api/v1/reference/domains/zone-check)
# External Transfers Flow
Source: https://docs.name.com/guides/external-transfers-flow
How to transfer domains into name.com (transfer in) and prepare domains for transfer out via the Core API, including timing rules and webhooks.
# External Transfers Support — In and Out
This guide covers **external** transfers: moving a domain **from another registrar into name.com** (transfer in), and **preparing a domain to leave name.com** for another registrar (transfer out). The gaining registrar always starts a transfer-out; name.com’s API helps you unlock domains, retrieve auth codes, monitor status, and cancel an outbound transfer when needed.
## Important timing notes
Domains must typically be registered for **at least 60 days** before they can be transferred to a different registrar (ICANN rule).
***
## A) Transfer into name.com (transfer in)
### How it works via the API
#### 1. Initiate a transfer
**`POST /core/v1/transfers`**
Required inputs:
* `domainName`
* `authCode` — EPP / authorization code from the current registrar
See [Create External Transfer In](/api/v1/reference/transfers/create-transfer) for the full request and response schema.
#### 2. Monitor transfer status
* **`GET /core/v1/transfers`** — list transfers\
[List Transfers](/api/v1/reference/transfers/list-transfers)
* **`GET /core/v1/transfers/{domainName}`** — status for a specific domain\
[Get Transfer Status](/api/v1/reference/transfers/get-transfer)
Statuses include **pending**, **complete**, **failed**, and others, depending on the API response.
#### 3. Webhook monitoring
Subscribe to **`domain.transfer.status_change`** webhook events to track progress automatically.
See [Webhooks overview](/api/v1/reference/webhook-notifications/overview) (Transfers — external), [Domain Transfer Status Change](/api/v1/reference/webhook-notifications/domain-transfer-status-change), and [Subscribe to Notification](/api/v1/reference/webhook-notifications/subscribe-to-notification).
***
## B) Transfer out of name.com
### How it works
#### 1. Unlock the domain for transfer out
**`PATCH /core/v1/domains/{domainName}`**
Set the domain lock so the domain can leave name.com:
* **`locked`**: `false` (JSON boolean)
See [Update a Domain](/api/v1/reference/domains/update-a-domain).
#### 2. Get the auth code for the customer
**`GET /core/v1/domains/{domainName}:getAuthCode`**
Retrieve the EPP / authorization code to give to the registrant or the gaining registrar.
See [Get Auth Code for Domain](/api/v1/reference/domains/get-auth-code-for-domain).
#### 3. Cancel a transfer-out request (optional)
If you need to cancel a transfer-out request:
**`POST /core/v1/transfers/external/out/{domainName}:cancel`**
See [Cancel External Transfer Out](/api/v1/reference/transfers/cancel-external-transfer-out).
The name.com Core API **does not initiate** transfer-out requests; those are started by the **gaining registrar** after you provide the auth code and the domain is eligible.
#### Webhook monitoring
Subscribe to **`domain.transfer_out.status_change`** to be notified when a domain has fully transferred away.
See [Webhooks overview](/api/v1/reference/webhook-notifications/overview) (Transfers — external) and [Domain Transfer Out Status Change](/api/v1/reference/webhook-notifications/domain-transfer-out-status-change).
# Funding Your name.com Account
Source: https://docs.name.com/guides/funding-your-namecom-account
How to fund your account using Account Credit via ACH or wire transfer.
To ensure uninterrupted access to name.com services and enable seamless transactions, clients are encouraged to utilize **Account Credit**. This approach simplifies financial operations and improves control over ongoing domain and digital asset management.
## Overview: Account Credit
Account Credit is a prepayment mechanism that allows funds to be securely stored within your name.com account. These funds are automatically applied to future purchases, including domain registrations, renewals, and associated services.
**Key advantages**
* Streamlined checkout experience
* Improved budget forecasting and control
* Centralized transaction management
* Priority processing for funded accounts
For additional reference, see the support article: [Adding Account Credit to your name.com account](https://www.name.com/support/articles/205188968-adding-account-credit-to-your-name-com-account).
If you're integrating via API, you can programmatically monitor credit using:
* [Account Info: Check Account Balance](/api/v1/reference/account-info/check-account-balance)
* [Account Credit Balance Change](/api/v1/reference/webhook-notifications/account-credit-balance-change)
## Purchase limits and prerequisites
To increase the default purchase limit above **\$2,500**, contact [`reseller@name.com`](mailto:reseller@name.com) to learn more.
## Funding methods
### 1. Wire transfer
Wire transfers are particularly suitable for international clients or high-value funding requirements.
**Process**
1. Initiate the transfer via your financial institution.
2. Funds are remitted directly to name.com’s designated banking details.
3. Upon receipt, funds are allocated to your account as Account Credit.
**Considerations**
* Standard processing times vary by financial institution.
* Funds become available after confirmation and reconciliation.
**Recommendation:** Include your name.com account ID in the wire memo for expedited processing.
### 2. ACH transfer (U.S. clients only)
ACH (Automated Clearing House) transfers provide a faster, more integrated funding solution for U.S.-based clients.
**Process**
1. Log in to your name.com Account Dashboard.
2. Add the intended credit amount to your cart (up to **\$20,000** per transaction).
3. Select the ACH payment option during checkout.
4. Upon successful transaction processing, credit is immediately reflected in your account.
**Advantages**
* Reduced processing time compared to wire transfers
* Direct integration with your name.com account
* No intermediary bank involvement
ACH must be enabled as a payment method within your account. Contact [`reseller@name.com`](mailto:reseller@name.com) to learn more.
## Client support & assistance
For enterprise accounts or specialized billing arrangements, please contact your account manager or reach out to our dedicated support team via your dashboard.
We are committed to ensuring a secure and efficient funding process tailored to your operational needs.
# Getting Started
Source: https://docs.name.com/guides/getting-started
Learn how to authenticate and make your first API call with name.com Core API
# Follow these steps to quickly get up and running with the name.com Core API.
Download our latest [OpenAPI spec](https://namedotcom-cdn.name.tools/api-info/namecom.api.yaml) before you begin, especially if you plan to use code generation. It is the simplest way to wire up clients and validate requests early.
## Step 1: Get Your API Token
Create a name.com account if you don't have one already.
We recommend **not** using Google/SSO when creating a reseller account. SSO-based signup often sets your **account username to your email address**, which is not ideal for reseller/API usage.
Pick a **generic, company-wide** username you can share across the team (e.g., `resellercompanyname`, `company-eng`, `company-dev`). This is the username you’ll use for HTTP Basic Auth, and your sandbox username will be this value with `-test` appended.
Go to Account Settings → Security → API Tokens and issue both development and production tokens
Keep your API token secure — treat it like a password
Newly generated sandbox (OT\&E) credentials can occasionally take **up to 15 minutes** to become active in the test environment. If you get a `401 Unauthorized` immediately after creating a token, wait a bit and retry. See [Testing Environment](/guides/testing-environment).
If your account has two-factor authentication (2FA) enabled, go to Account Settings → Security, and toggle name.com API Access on at the bottom.
## Step 2: Choose Your Environment
name.com offers two separate environments:
**Base URL:** `https://api.name.com`\
**Purpose:** Live domain registrations, renewals, and management
**Base URL:** `https://api.dev.name.com`\
**Purpose:** Safe testing and development — no real charges
### Sandbox Environment Details
* Use your username with `-test` appended (e.g., `reseller123-test`)
* Requires a separate sandbox API token
* The sandbox is API-only — not accessible through the browser
* Supports the Try It feature (limited to test environment)
* Includes preloaded testing credit
* Data does not sync with production
* Test domains must be registered in sandbox before use
* Domain availability and pricing may differ from production
* Some TLDs are not available in sandbox environment
## Step 3: Authenticate Your API Requests
Use HTTP Basic Auth with your username and API token. See the full guide in [Authentication](/guides/authentication) for curl shorthand vs explicit header, and how to generate a Base64 token on Linux/macOS and Windows PowerShell.
```bash Production theme={null}
curl -u your-username:your-api-token https://api.name.com/core/v1/hello
```
```bash Sandbox theme={null}
curl -u your-username-test:your-sandbox-token https://api.dev.name.com/core/v1/hello
```
## Step 4: Make Your First API Call
Call the GET `/core/v1/hello` endpoint to verify connectivity:
```bash Production theme={null}
curl -u your-username:your-api-token https://api.name.com/core/v1/hello
```
```bash Sandbox theme={null}
curl -u your-username-test:your-sandbox-token https://api.dev.name.com/core/v1/hello
```
A successful response should look like this:
```json theme={null}
{
"motd": "Welcome to Core API from Name.com",
"serverName": "nameapiserver",
"serverTime": "2025-01-01T12:15:00Z",
"username": "myapiusername"
}
```
If you see this message — your authentication was successful!
## Using "Try it" Feature
Go to an endpoint you'd like to test (e.g., `GET /core/v1/domains` → `ListDomains`)
Click the "**Try it**" button at the top right of the endpoint panel
In the "**Environment**" dropdown (next to "**History**"):
* Select **Mock Server** to test with sample responses (no credentials needed)
* Select **Testing** to use the name.com sandbox environment
Use your sandbox credentials from Account Settings → API Tokens ([https://www.name.com/account/settings/api](https://www.name.com/account/settings/api))
Click **Send** to make your test request
Only use sandbox credentials when testing in the development environment. Never use production credentials unless you are working with real data.
## Troubleshooting Common Issues
Check your username and API token; verify you're using the right environment
If 2FA is enabled, go to Account Settings → Security and enable API Access
Make sure the domain or resource exists; in sandbox, register test domains first
## Next Steps
Browse the complete API reference
Understand API structure and features
Get help with troubleshooting
# HMAC Signature Verification
Source: https://docs.name.com/guides/hmac-examples
Practical examples to verify name.com webhook HMAC signatures including header format, generation steps, and security best practices in common programming languages.
## Signature Format
name.com webhooks include an `X-NAMECOM-SIGNATURE` header containing the HMAC signature with additional security measures. The header value format is:
```
X-NAMECOM-SIGNATURE: algorithmName=encodedSignature,timestamp,nonce
```
Where:
* `algorithmName=encodedSignature` is the HMAC signature (e.g., "sha256=a1b2c3d4...")
* `timestamp` is the Unix timestamp when the signature was generated
* `nonce` is a unique identifier (UUID) to prevent replay attacks
## Signature Generation Process
name.com generates signatures using the following process:
1. Convert payload to object and sort keys alphabetically
2. JSON encode the sorted payload
3. Combine the exact full webhook subscription URL and JSON payload with a pipe delimiter (`|`)
4. Compute HMAC using the specified algorithm, combined data, and your API token (earliest if multiple exist)
5. Convert binary signature to hexadecimal and prefix with algorithm name
6. Generate Unix timestamp and unique nonce (UUID)
7. Combine signature, timestamp, and nonce as comma-separated values
## Accounts with multiple API tokens
* Webhook HMAC is computed with your account's earliest API v4 token.
* If the account has only one token, that token is the signing key.
## URL Canonicalization Requirement
When verifying `X-NAMECOM-SIGNATURE`, construct the HMAC input using the exact full webhook subscription URL (including scheme, host, and path; include query string if present), not a path-only value.
Canonical input format: `|`.
## Verification Examples
### PHP
```php theme={null}
$maxAgeSeconds) {
throw new InvalidArgumentException('Signature timestamp is too old');
}
// Parse the signature to extract algorithm and value
if (strpos($signaturePart, '=') === false) {
throw new InvalidArgumentException('Invalid signature format');
}
list($algorithm, $signatureValue) = explode('=', $signaturePart, 2);
// Convert payload to array and sort keys
if (!is_array($payload)) {
$payload = (array)$payload;
}
ksort($payload);
// JSON encode the sorted payload
$jsonPayload = json_encode($payload, JSON_UNESCAPED_SLASHES);
// Combine URL and payload as done in signature generation
$signatureData = $webhookUrl . '|' . $jsonPayload;
// Compute expected signature
$expectedSignature = hash_hmac($algorithm, $signatureData, $apiToken, true);
$expectedHex = bin2hex($expectedSignature);
// Compare signatures using timing-safe comparison
return hash_equals($expectedHex, $signatureValue);
}
// Example usage
$payload = ['domain' => 'example.com', 'action' => 'created'];
$headerValue = 'sha256=a1b2c3d4e5f6...,1640995200,550e8400-e29b-41d4-a716-446655440000'; // From X-NAMECOM-SIGNATURE header
$apiToken = 'your-api-token';
$webhookUrl = 'https://partner.example.com/webhook/domain-created'; // The exact full webhook subscription URL
try {
if (verifyHmacSignature($payload, $headerValue, $apiToken, $webhookUrl)) {
echo "Signature is valid\n";
} else {
echo "Signature is invalid\n";
}
} catch (InvalidArgumentException $e) {
echo "Error: " . $e->getMessage() . "\n";
}
```
### Python
```python theme={null}
import hmac
import hashlib
import json
import time
def verify_hmac_signature(payload, header_value, api_token, webhook_url, max_age_seconds=300):
"""
Verify HMAC signature for name.com webhook
"""
# Parse the header value: signature,timestamp,nonce
parts = header_value.split(',')
if len(parts) != 3:
raise ValueError('Invalid header format')
signature_part, timestamp, nonce = parts
# Validate timestamp to prevent replay attacks
current_time = int(time.time())
if abs(current_time - int(timestamp)) > max_age_seconds:
raise ValueError('Signature timestamp is too old')
# Parse the signature to extract algorithm and value
if '=' not in signature_part:
raise ValueError('Invalid signature format')
algorithm, signature_value = signature_part.split('=', 1)
# Convert payload to dict and sort keys
if not isinstance(payload, dict):
payload = dict(payload)
# Sort keys alphabetically
sorted_payload = dict(sorted(payload.items()))
# JSON encode the sorted payload
json_payload = json.dumps(sorted_payload, separators=(',', ':'), ensure_ascii=False)
# Combine URL and payload as done in signature generation
signature_data = webhook_url + '|' + json_payload
# Get the hash function based on algorithm
hash_func = getattr(hashlib, algorithm, None)
if hash_func is None:
raise ValueError(f'Unsupported algorithm: {algorithm}')
# Compute expected signature
expected_signature = hmac.new(
api_token.encode('utf-8'),
signature_data.encode('utf-8'),
hash_func
).hexdigest()
# Compare signatures using timing-safe comparison
return hmac.compare_digest(expected_signature, signature_value)
# Example usage
payload = {'domain': 'example.com', 'action': 'created'}
header_value = 'sha256=a1b2c3d4e5f6...,1640995200,550e8400-e29b-41d4-a716-446655440000' # From X-NAMECOM-SIGNATURE header
api_token = 'your-api-token'
webhook_url = 'https://partner.example.com/webhook/domain-created' # The exact full webhook subscription URL
try:
if verify_hmac_signature(payload, header_value, api_token, webhook_url):
print("Signature is valid")
else:
print("Signature is invalid")
except ValueError as e:
print(f"Error: {e}")
```
### Go
```go theme={null}
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"fmt"
"sort"
"strconv"
"strings"
"time"
)
func verifyHmacSignature(payload map[string]interface{}, headerValue, apiToken, webhookUrl string, maxAgeSeconds int) (bool, error) {
// Parse the header value: signature,timestamp,nonce
parts := strings.Split(headerValue, ",")
if len(parts) != 3 {
return false, fmt.Errorf("invalid header format")
}
signaturePart, timestampStr, nonce := parts[0], parts[1], parts[2]
// Validate timestamp to prevent replay attacks
timestamp, err := strconv.ParseInt(timestampStr, 10, 64)
if err != nil {
return false, fmt.Errorf("invalid timestamp: %v", err)
}
currentTime := time.Now().Unix()
if abs(currentTime-timestamp) > int64(maxAgeSeconds) {
return false, fmt.Errorf("signature timestamp is too old")
}
// Parse the signature to extract algorithm and value
signatureParts := strings.SplitN(signaturePart, "=", 2)
if len(signatureParts) != 2 {
return false, fmt.Errorf("invalid signature format")
}
algorithm, signatureValue := signatureParts[0], signatureParts[1]
// Sort keys alphabetically
keys := make([]string, 0, len(payload))
for k := range payload {
keys = append(keys, k)
}
sort.Strings(keys)
// Create sorted map
sortedPayload := make(map[string]interface{})
for _, k := range keys {
sortedPayload[k] = payload[k]
}
// JSON encode the sorted payload
jsonPayload, err := json.Marshal(sortedPayload)
if err != nil {
return false, err
}
// Combine URL and payload as done in signature generation
signatureData := webhookUrl + "|" + string(jsonPayload)
// Get the hash function based on algorithm
var hashFunc func() hash.Hash
switch algorithm {
case "sha256":
hashFunc = sha256.New
default:
return false, fmt.Errorf("unsupported algorithm: %s", algorithm)
}
// Compute expected signature
mac := hmac.New(hashFunc, []byte(apiToken))
mac.Write([]byte(signatureData))
expectedSignature := hex.EncodeToString(mac.Sum(nil))
// Compare signatures using timing-safe comparison
return hmac.Equal([]byte(expectedSignature), []byte(signatureValue)), nil
}
func abs(x int64) int64 {
if x < 0 {
return -x
}
return x
}
// Example usage
func main() {
payload := map[string]interface{}{
"domain": "example.com",
"action": "created",
}
headerValue := "sha256=a1b2c3d4e5f6...,1640995200,550e8400-e29b-41d4-a716-446655440000" // From X-NAMECOM-SIGNATURE header
apiToken := "your-api-token"
webhookUrl := "https://partner.example.com/webhook/domain-created" // The exact full webhook subscription URL
maxAgeSeconds := 300
valid, err := verifyHmacSignature(payload, headerValue, apiToken, webhookUrl, maxAgeSeconds)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
if valid {
fmt.Println("Signature is valid")
} else {
fmt.Println("Signature is invalid")
}
}
```
### JavaScript (Node.js)
```javascript theme={null}
const crypto = require('crypto');
function verifyHmacSignature(payload, headerValue, apiToken, webhookUrl, maxAgeSeconds = 300) {
// Parse the header value: signature,timestamp,nonce
const parts = headerValue.split(',');
if (parts.length !== 3) {
throw new Error('Invalid header format');
}
const [signaturePart, timestampStr, nonce] = parts;
// Validate timestamp to prevent replay attacks
const timestamp = parseInt(timestampStr, 10);
const currentTime = Math.floor(Date.now() / 1000);
if (Math.abs(currentTime - timestamp) > maxAgeSeconds) {
throw new Error('Signature timestamp is too old');
}
// Parse the signature to extract algorithm and value
if (!signaturePart.includes('=')) {
throw new Error('Invalid signature format');
}
const [algorithm, signatureValue] = signaturePart.split('=', 2);
// Convert payload to object and sort keys
let sortedPayload;
if (Array.isArray(payload)) {
sortedPayload = payload;
} else if (typeof payload === 'object' && payload !== null) {
// Sort keys alphabetically
const sortedKeys = Object.keys(payload).sort();
sortedPayload = {};
for (const key of sortedKeys) {
sortedPayload[key] = payload[key];
}
} else {
sortedPayload = payload;
}
// JSON encode the sorted payload
const jsonPayload = JSON.stringify(sortedPayload);
// Combine URL and payload as done in signature generation
const signatureData = webhookUrl + '|' + jsonPayload;
// Compute expected signature
const expectedSignature = crypto
.createHmac(algorithm, apiToken)
.update(signatureData, 'utf8')
.digest('hex');
// Compare signatures using timing-safe comparison
return crypto.timingSafeEqual(
Buffer.from(expectedSignature, 'hex'),
Buffer.from(signatureValue, 'hex')
);
}
// Example usage
const payload = { domain: 'example.com', action: 'created' };
const headerValue = 'sha256=a1b2c3d4e5f6...,1640995200,550e8400-e29b-41d4-a716-446655440000'; // From X-NAMECOM-SIGNATURE header
const apiToken = 'your-api-token';
const webhookUrl = 'https://partner.example.com/webhook/domain-created'; // The exact full webhook subscription URL
try {
if (verifyHmacSignature(payload, headerValue, apiToken, webhookUrl)) {
console.log('Signature is valid');
} else {
console.log('Signature is invalid');
}
} catch (error) {
console.error('Error:', error.message);
}
```
### Java
```java theme={null}
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.*;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;
public class HmacVerifier {
public static boolean verifyHmacSignature(Object payload, String headerValue, String apiToken, String webhookUrl, int maxAgeSeconds)
throws Exception {
// Parse the header value: signature,timestamp,nonce
String[] parts = headerValue.split(",");
if (parts.length != 3) {
throw new IllegalArgumentException("Invalid header format");
}
String signaturePart = parts[0];
String timestampStr = parts[1];
String nonce = parts[2];
// Validate timestamp to prevent replay attacks
long timestamp = Long.parseLong(timestampStr);
long currentTime = System.currentTimeMillis() / 1000;
if (Math.abs(currentTime - timestamp) > maxAgeSeconds) {
throw new IllegalArgumentException("Signature timestamp is too old");
}
// Parse the signature to extract algorithm and value
if (!signaturePart.contains("=")) {
throw new IllegalArgumentException("Invalid signature format");
}
String[] signatureParts = signaturePart.split("=", 2);
String algorithm = signatureParts[0];
String signatureValue = signatureParts[1];
// Convert payload to sorted JSON
String jsonPayload = createSortedJson(payload);
// Combine URL and payload as done in signature generation
String signatureData = webhookUrl + "|" + jsonPayload;
// Compute expected signature
String expectedSignature = computeHmac(signatureData, apiToken, algorithm);
// Compare signatures using timing-safe comparison
return constantTimeEquals(expectedSignature, signatureValue);
}
private static String createSortedJson(Object payload) throws Exception {
ObjectMapper mapper = new ObjectMapper();
JsonNode node = mapper.valueToTree(payload);
// Convert to sorted map
Map sortedMap = new TreeMap<>();
node.fields().forEachRemaining(entry -> {
sortedMap.put(entry.getKey(), entry.getValue());
});
return mapper.writeValueAsString(sortedMap);
}
private static String computeHmac(String data, String key, String algorithm)
throws NoSuchAlgorithmException, InvalidKeyException {
String hmacAlgorithm = "Hmac" + algorithm.toUpperCase();
Mac mac = Mac.getInstance(hmacAlgorithm);
SecretKeySpec secretKeySpec = new SecretKeySpec(
key.getBytes(StandardCharsets.UTF_8),
hmacAlgorithm
);
mac.init(secretKeySpec);
byte[] hash = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
return bytesToHex(hash);
}
private static String bytesToHex(byte[] bytes) {
StringBuilder result = new StringBuilder();
for (byte b : bytes) {
result.append(String.format("%02x", b));
}
return result.toString();
}
private static boolean constantTimeEquals(String a, String b) {
if (a.length() != b.length()) {
return false;
}
int result = 0;
for (int i = 0; i < a.length(); i++) {
result |= a.charAt(i) ^ b.charAt(i);
}
return result == 0;
}
// Example usage
public static void main(String[] args) {
try {
Map payload = new HashMap<>();
payload.put("domain", "example.com");
payload.put("action", "created");
String headerValue = "sha256=a1b2c3d4e5f6...,1640995200,550e8400-e29b-41d4-a716-446655440000"; // From X-NAMECOM-SIGNATURE header
String apiToken = "your-api-token";
String webhookUrl = "https://partner.example.com/webhook/domain-created"; // The exact full webhook subscription URL
int maxAgeSeconds = 300;
if (verifyHmacSignature(payload, headerValue, apiToken, webhookUrl, maxAgeSeconds)) {
System.out.println("Signature is valid");
} else {
System.out.println("Signature is invalid");
}
} catch (Exception e) {
System.err.println("Error: " + e.getMessage());
}
}
}
```
### Ruby
```ruby theme={null}
require 'openssl'
require 'json'
def verify_hmac_signature(payload, header_value, api_token, webhook_url, max_age_seconds = 300)
# Parse the header value: signature,timestamp,nonce
parts = header_value.split(',')
unless parts.length == 3
raise ArgumentError, 'Invalid header format'
end
signature_part, timestamp_str, nonce = parts
# Validate timestamp to prevent replay attacks
timestamp = timestamp_str.to_i
current_time = Time.now.to_i
if (current_time - timestamp).abs > max_age_seconds
raise ArgumentError, 'Signature timestamp is too old'
end
# Parse the signature to extract algorithm and value
unless signature_part.include?('=')
raise ArgumentError, 'Invalid signature format'
end
algorithm, signature_value = signature_part.split('=', 2)
# Convert payload to hash and sort keys
payload_hash = payload.is_a?(Hash) ? payload : payload.to_h
sorted_payload = payload_hash.sort.to_h
# JSON encode the sorted payload
json_payload = JSON.generate(sorted_payload)
# Combine URL and payload as done in signature generation
signature_data = webhook_url + '|' + json_payload
# Get the digest class based on algorithm
digest_class = case algorithm
when 'sha256'
OpenSSL::Digest.new('sha256')
else
raise ArgumentError, "Unsupported algorithm: #{algorithm}"
end
# Compute expected signature
expected_signature = OpenSSL::HMAC.hexdigest(
digest_class,
api_token,
signature_data
)
# Compare signatures using timing-safe comparison
secure_compare(expected_signature, signature_value)
end
def secure_compare(a, b)
return false if a.bytesize != b.bytesize
result = 0
a.bytes.zip(b.bytes) { |x, y| result |= x ^ y }
result == 0
end
# Example usage
payload = { 'domain' => 'example.com', 'action' => 'created' }
header_value = 'sha256=a1b2c3d4e5f6...,1640995200,550e8400-e29b-41d4-a716-446655440000' # From X-NAMECOM-SIGNATURE header
api_token = 'your-api-token'
webhook_url = 'https://partner.example.com/webhook/domain-created' # The exact full webhook subscription URL
begin
if verify_hmac_signature(payload, header_value, api_token, webhook_url)
puts 'Signature is valid'
else
puts 'Signature is invalid'
end
rescue => e
puts "Error: #{e.message}"
end
```
## Important Notes
1. **Key Sorting**: The payload keys must be sorted alphabetically before JSON encoding to ensure consistent signature generation.
2. **JSON Encoding**: Use consistent JSON encoding settings across all implementations to match name.com's signature generation.
3. **URL Inclusion**: Use the exact full webhook subscription URL in the signature calculation (`|`), not a path-only value.
4. **Timing-Safe Comparison**: Always use timing-safe comparison functions to prevent timing attacks when comparing signatures.
5. **Timestamp Validation**: The timestamp validation prevents replay attacks by rejecting signatures older than the specified time window (default 5 minutes).
6. **Nonce Usage**: While the nonce is included in the header for uniqueness, it's not used in signature verification but helps with request tracking and debugging.
7. **Error Handling**: Implement proper error handling for invalid header formats, timestamp validation failures, and unsupported algorithms.
8. **Character Encoding**: Ensure consistent UTF-8 encoding across all implementations.
9. **Algorithm Support**: The examples support dynamic algorithm detection from the signature header, allowing for future algorithm changes.
10. **Security**: The combination of HMAC signature (including full URL), timestamp validation, and nonce provides strong protection against replay attacks and cross-endpoint attacks while ensuring request authenticity.
11. **Testing**: Test with the same payload, API token, and webhook URL to ensure all implementations produce identical results.
# v4 to CORE API Migration
Source: https://docs.name.com/guides/migration-guide
Complete guide for migrating from the v4 API to the name.com Core API
# v4 To name.com API (Core) Migration Guide
## Why Upgrade?
CORE version uses OpenAPI 3.1-based documentation for better tooling and interactive exploration
Cleaner, consistent error messages and HTTP status codes
Streamlined, consolidated endpoints (e.g. UpdateDomain)
Enforced standards for content types and default response formatting
## Upgrading from the legacy v4 API to the new name.com API (CORE)
Welcome to the name.com API! This new API offers a modern, RESTful interface for managing your domains, DNS records, and related services, succeeding our legacy v4 API. We've rebuilt the name.com API from the ground up to provide faster iteration, improved stability, more consistent behavior, and a better overall developer experience.
**IMPORTANT: Breaking Changes**
Migrating from the v4 API to the name.com API (CORE) is a breaking change. You will need to review and update your existing integrations to align with the new API structure, endpoints, and behaviors outlined below. The v4 API remains accessible for a transition period, but we strongly encourage all new integrations and existing integrations to migrate to the name.com API (CORE)
## Key Changes Requiring Your Attention & Migration Steps
### 1. New API Documentation (OpenAPI 3.1)
The Core API documentation is now provided in OpenAPI 3.1 format
This offers significantly better tooling support, interactive documentation capabilities (e.g., "Try it out" features), and clearer schema definitions
Familiarize yourself with the new documentation structure. You can leverage a wide range of OpenAPI 3.1 compatible tools to generate client libraries, explore endpoints, and understand request/response models
### 2. Improved Error Handling & Messaging
We've overhauled error responses for clarity and accuracy:
Generic 500 Internal Server Error responses for many client-side or predictable error conditions
More specific and appropriate HTTP status codes (e.g., 401, 402, 422)
**Example:** If an action fails due to insufficient account credit, the API will now return `402 Payment Required` instead of the previous `500 Internal Server Error`.
Update your error handling logic to expect and correctly process more specific HTTP status codes
Adjust authentication failure checks to look for `401 Unauthorized`. Treat `403 Forbidden` as a permissions issue for an authenticated user
### 3. Consistent Default Values in API Responses
API responses will now consistently include fields with their default values (e.g., `false` for booleans, `0` for numbers, `""` for empty strings) instead of omitting them
The Search API previously omitted `"purchasable": false;` it is now explicitly returned as `"purchasable": false`
Update your response parsing logic to expect these default values. You should no longer assume that an omitted field implies a specific default (like false or null)
### 4. Correct Content-Type Headers in API Responses
`Content-Type: text/html` was often incorrectly returned for JSON responses
`Content-Type: application/json` is now accurately set for JSON responses
Ensure your client correctly interprets the `Content-Type: application/json` header for JSON responses. If your client was previously ignoring or misinterpreting this header, updates may be needed.
### 5. Enforced Content-Type Header Requirements for Requests
The `Content-Type: application/json` header is now strictly enforced for all `PUT`, `POST`, and `PATCH` requests.
**Important Note for Body-less POSTs:** Due to server implementations, this enforcement means that even `POST` requests that do not require an actual request body (e.g., certain RPC-style actions like the now-deprecated LockDomain) **will still require the `Content-Type: application/json header`**.
For **all** `PUT`, `POST`, and `PATCH` requests made to the name.com Core API, you must include the header: `Content-Type: application/json`
Verify this for requests that previously worked without it, including those that don't send a JSON body
### 6. Consolidated Domain Update Functionality & Endpoint Deprecations
Several individual API endpoints for modifying domain settings have been deprecated. A new, consolidated endpoint, [UpdateDomain](/api/v1/reference/domains/update-a-domain), has been introduced to handle these actions.
* [LockDomain](/api/v1/reference/domains/lock-domain)
* [UnlockDomain](/api/v1/reference/domains/unlock-domain)
* [EnableAutorenew](/api/v1/reference/domains/enable-autorenew)
* [DisableAutorenew](/api/v1/reference/domains/disable-autorenew)
* [EnableWhoisPrivacy](/api/v1/reference/domains/enable-whois-privacy)
* [DisableWhoisPrivacy](/api/v1/reference/domains/disable-whois-privacy)
`PATCH /v1/domains/{domainName}` (See [DomainUpdate Documentation](/api/v1/reference/domains/update-a-domain))
Migrate your domain modification logic from the deprecated endpoints to the new UpdateDomain endpoint. This endpoint allows for updating domain lock status, autorenew settings, and WHOIS Privacy settings in a single call
## Removed Features
### SearchStream Endpoint
This endpoint has been removed in the name.com Core API. We are evaluating a revised implementation for a future release.
**Action Required:** If your application uses the SearchStream endpoint, you will need to remove this integration.
## New Features
### UpdateDomain Endpoint
* **Endpoint:** `PATCH /v1/domains/{domainName}`
* **Purpose:** Provides a consolidated and more efficient way to modify multiple domain settings such as autorenew status, WHOIS Privacy, and domain lock status
* **Recommendation:** Utilize this new endpoint for all domain setting modifications
## Overall Benefits & Next Steps
The name.com Core API is designed for improved usability, consistency, and future extensibility. The underlying codebase rewrite allows us to iterate faster, provide better error handling, and ensure more consistent behavior across all endpoints.
Thoroughly review this guide and the new name.com Core API documentation
Plan your migration from the legacy v4 API, prioritizing the changes outlined above
Test your updated integration extensively in a development or staging environment if available
While the legacy v4 API remains accessible during a transition period, all new development should use the name.com Core API (latest version recommended).
We appreciate your partnership and are excited to provide you with a more robust and modern API experience. Please refer to our official documentation for complete details and contact our support channels if you have any questions during your upgrade process.
# Reseller Quickstart
Source: https://docs.name.com/guides/quickstart
A minimal, production-ready flow to sell domains with the name.com Core API from discovery, purchase, management, and renewals.
# Reseller Quickstart MVP Flow (Search → Register → Manage)
This guide is for new domain resellers who want to **sell domains on their own site** with a complete, clean MVP from domain discovery through domain management.
This is a **recommended** MVP flow to get up and running quickly — not a requirement. The goal of the name.com Core API is to provide **flexibility** so you can build the domain purchase and management UX that fits your product. We encourage you to get creative, and we’d love your feedback on what would make your UX and developer experience better: [name.com API feedback](https://www.name.com/api-feedback).
## What you’ll implement (MVP)
* **Domain purchase**: search → pre-registration checks → registration
* **Domain dashboard**: list domains + basic status
* **Domain management**: DNS records, nameservers, domain contacts, contact verification, renewals, WHOIS privacy
Flow stages:
Discovery Registration Management
## Before you start
Download our latest [OpenAPI spec](https://namedotcom-cdn.name.tools/api-info/namecom.api.yaml) before you build, especially if you plan to use code generation.
You’ll move faster if you skim these first:
* [Getting Started](/guides/getting-started)
* [API v1 Overview](/api/v1/overview)
We recommend **not** using Google/SSO when creating a reseller account. SSO-based signup often sets your **account username to your email address**, which is not ideal for reseller/API usage.
Pick a **generic, company-wide** username you can share across the team (e.g., `resellercompanyname`, `company-eng`, `company-dev`). This is the username you’ll use for HTTP Basic Auth, and your sandbox username will be this value with `-test` appended.
## Step 1: Build the search UX
Discovery
**Use Search to show purchasable options + pricing**: `POST /core/v1/domains:search` → [Search](/api/v1/reference/domains/search)
Use the optional **`purchaseType` = `"registration"`** to limit Search to registration inventory and match the simple checkout path below.
**UX recommendations**
* Show **purchase price** and **renewal price** from the API result.
* Mark premium domains clearly (pricing confirmation is required at purchase time for premium domains).
* For a fast MVP, start with a curated set of TLDs: [Recommended TLDs](/guides/quickstart-recommended-tlds)
## Step 2: Pre-checks at checkout (prevents failed purchases)
Registration
At checkout time (right before you call [Create Domain](/api/v1/reference/domains/create-domain), which is the **billable** registration action), do these checks:
**Recommended check**
* **Use Check Availability to confirm the domain is still purchasable + capture `purchasePrice` & `purchaseType`**:
* `POST /core/v1/domains:checkAvailability` → [Check Availability](/api/v1/reference/domains/check-availability)
* Use the optional **`purchaseType` = `"registration"`**, same as Search, so the pre-check stays scoped to registration inventory.
* Search results are a great UX starting point, but availability can change. This is a good safeguard if a user adds a domain to cart and waits, or it gets registered elsewhere between search and purchase. It also gives you the definitive `purchasePrice` & `purchaseType` to pass into create (required for premium domains).
Not required for Quickstart, but good to add when you’re ready:
* **TLD-specific registration requirements (often ccTLDs)**: [TLD Requirements](/api/v1/reference/domain-info/get-specific-tld-requirements)
* **Claims-period domains**: [Claims Flow](/guides/claims-flow)
**Quickstart constraint:** only support `purchaseType = registration` at first (avoid complex cases like aftermarket/pre-order flows). If `Check Availability` returns a different `purchaseType`, treat it as “not supported yet” in your UI.
## Step 3: Register the domain (idempotent checkout)
Registration
**Use Create Domain to register (billable)**: `POST /core/v1/domains` → [Create Domain](/api/v1/reference/domains/create-domain)
Always send an `X-Idempotency-Key` on create so retrying a timed-out request doesn’t double-purchase.
**Recommended create defaults for a good MVP UX**
* `autorenewEnabled: true` (reduces churn/support)
* `locked: true` (safer default; can be toggled later). Note: new registrations are **transfer-locked for 60 days** by default, regardless.
* `privacyEnabled: true` (the system will only add privacy for TLDs that support it, even if you always pass `true`)
* `years`: most domains support purchasing **up to 10 years** at registration time (great for customers who want to lock in pricing and reduce renewal overhead). For per‑TLD limits/requirements, see [TLD Requirements](/api/v1/reference/domain-info/get-specific-tld-requirements).
* **Contacts (recommended for Quickstart)**: set the **reseller (you)** as the domain contacts to move fast. Our system defaults to your account level contacts on a domain create call if contact data is not passed. Using end-customer contacts is possible, but typically requires additional setup (e.g., whitelabeled contact emails) and creates more verification/support work. Contacts can be updated later using [Set Contacts](/api/v1/reference/domains/set-contacts).
## Step 4: Domain dashboard & management
Management
**Use Domains + settings endpoints to power your dashboard**:
* **List domains**: `GET /core/v1/domains` → [List Domains](/api/v1/reference/domains/list-domains)
* **Domain details**: `GET /core/v1/domains/{domainName}` → [Get Domain](/api/v1/reference/domains/get-domain)
* **Autorenew / lock / WHOIS privacy toggles**: `PATCH /core/v1/domains/{domainName}` → [Update a domain](/api/v1/reference/domains/update-a-domain)
* **Update contacts**: `POST /core/v1/domains/{domainName}:setContacts` → [Set Contacts](/api/v1/reference/domains/set-contacts)
* **Renew domain anytime**: `POST /core/v1/domains/{domainName}:renew` → [Renew Domain](/api/v1/reference/domains/renew-domain)
* **Purchase/extend WHOIS privacy**: `POST /core/v1/domains/{domainName}:purchasePrivacy` → [Purchase Privacy](/api/v1/reference/domains/purchase-privacy)
Show these fields prominently:
* domain name, expiration date, autorenew on/off, privacy on/off, lock state
* DNS Settings (see Step 5)
* contact verification status (below)
### Contact verification status
**Use Unverified Contacts to surface verification requirements**:
* `GET /core/v1/contacts/unverified` → [List Unverified Contacts](/api/v1/reference/contact-verification/list-unverified-contacts)
After a new domain registration or contact change, unverified contacts may take up to \~10 minutes to appear in the API. Build your UI accordingly.
If contacts aren’t verified within 15 days, verification locks can apply and the domain may stop resolving. See [Understanding Domain Locks](/guides/domain-locks).
Optional: some reseller accounts are approved to verify contacts via API; most are not. If you need this, contact [API Support](https://www.name.com/support/api) and see: [Verify Contact](/api/v1/reference/contact-verification/verify-contact)
If you send your own verification emails (or need resend/webhook details), see the [Contact Verification Compliance Guide](/guides/contact-verification).
## Step 5: DNS & nameservers
Management
**Use DNS records (and optionally nameservers) to connect the domain**:
* **List records**: `GET /core/v1/domains/{domainName}/records` → [List Records](/api/v1/reference/dns/list-records)
* **Create record**: `POST /core/v1/domains/{domainName}/records` → [Create Record](/api/v1/reference/dns/create-record)
* **Get record**: `GET /core/v1/domains/{domainName}/records/{id}` → [Get Record](/api/v1/reference/dns/get-record)
* **Update record**: `PUT /core/v1/domains/{domainName}/records/{id}` → [Update Record](/api/v1/reference/dns/update-record)
* **Delete record**: `DELETE /core/v1/domains/{domainName}/records/{id}` → [Delete Record](/api/v1/reference/dns/delete-record)
Many resellers request default nameservers up front. If you want customers to use external DNS (or switch away from the default DNS), also include:
* **Set nameservers**: `POST /core/v1/domains/{domainName}:setNameservers` → [Set Nameservers](/api/v1/reference/domains/set-nameservers)
## MVP “no holes” checklist
If you ship this MVP, your customers can:
* **Search** for a domain and see a real price ([Search](/api/v1/reference/domains/search))
* **Checkout** without failed purchases due to proper handling of extra requirements, premiums, and claims gaps ([Check Availability](/api/v1/reference/domains/check-availability), [TLD Requirements](/api/v1/reference/domain-info/get-specific-tld-requirements), [Claims Flow](/guides/claims-flow))
* **Register** safely with retries ([Create Domain](/api/v1/reference/domains/create-domain))
* **Manage domain settings** (DNS records + nameservers, lock status, autorenew, WHOIS privacy)
* **Manage domain contacts** and see verification status (prevents domain outages)
* **Renew** domains and WHOIS privacy
## Recommended next steps (post-MVP)
Keep these out of MVP unless you need them, but they’re high-impact upgrades:
Push status changes into your app instead of polling; verify webhook authenticity.
Add inbound transfers for users migrating domains to you.
Add DNSSEC and/or branded nameservers for advanced customers.
Build admin tooling for reporting, reconciliation, and customer support workflows.
## Need help?
Share your request/response details with our team to troubleshoot your integration.
## Common pitfalls
**Do not URL-encode the `:`** in endpoints like `POST /core/v1/domains:search` and `POST /core/v1/domains:checkAvailability`. Some clients encode `:` → `%3A` which will fail. See [API v1 Overview](/api/v1/overview).
# Quickstart TLD List
Source: https://docs.name.com/guides/quickstart-recommended-tlds
An alphabetized list of TLDs we recommend for a fast MVP domain storefront implementation.
# Recommended TLDs for Quickstart
These TLDs are a **recommended starting point** for building a fast MVP. They are generally a good fit when you want to avoid special registration requirements in your first iteration.
This list is **not exhaustive** and may evolve. If you want to support TLDs with extra required fields (often ccTLDs), use [TLD Requirements](/api/v1/reference/domain-info/get-specific-tld-requirements).
Download the recommended TLD list as a CSV file.
* `.ac`
* `.academy`
* `.accountant`
* `.accountants`
* `.actor`
* `.adult`
* `.agency`
* `.airforce`
* `.apartments`
* `.app`
* `.archi`
* `.army`
* `.art`
* `.asia`
* `.associates`
* `.attorney`
* `.auction`
* `.audio`
* `.auto`
* `.autos`
* `.baby`
* `.band`
* `.bar`
* `.bargains`
* `.bayern`
* `.beauty`
* `.beer`
* `.berlin`
* `.best`
* `.bet`
* `.bid`
* `.bike`
* `.bingo`
* `.bio`
* `.biz`
* `.black`
* `.blackfriday`
* `.blog`
* `.blue`
* `.boats`
* `.bond`
* `.boo`
* `.boston`
* `.bot`
* `.boutique`
* `.broker`
* `.build`
* `.builders`
* `.business`
* `.buzz`
* `.cab`
* `.cafe`
* `.cam`
* `.camera`
* `.camp`
* `.capital`
* `.car`
* `.cards`
* `.care`
* `.careers`
* `.cars`
* `.casa`
* `.cash`
* `.casino`
* `.catering`
* `.center`
* `.ceo`
* `.cfd`
* `.charity`
* `.chat`
* `.cheap`
* `.christmas`
* `.church`
* `.city`
* `.claims`
* `.cleaning`
* `.click`
* `.clinic`
* `.clothing`
* `.cloud`
* `.club`
* `.co`
* `.coach`
* `.codes`
* `.coffee`
* `.college`
* `.com`
* `.community`
* `.company`
* `.computer`
* `.condos`
* `.construction`
* `.consulting`
* `.contact`
* `.contractors`
* `.cooking`
* `.cool`
* `.country`
* `.coupons`
* `.courses`
* `.credit`
* `.creditcard`
* `.cricket`
* `.cruises`
* `.dad`
* `.dance`
* `.date`
* `.dating`
* `.day`
* `.deal`
* `.dealer`
* `.deals`
* `.degree`
* `.delivery`
* `.democrat`
* `.dental`
* `.dentist`
* `.desi`
* `.design`
* `.dev`
* `.diamonds`
* `.diet`
* `.digital`
* `.direct`
* `.directory`
* `.discount`
* `.diy`
* `.doctor`
* `.dog`
* `.domains`
* `.download`
* `.earth`
* `.education`
* `.email`
* `.energy`
* `.engineer`
* `.engineering`
* `.enterprises`
* `.equipment`
* `.esq`
* `.estate`
* `.events`
* `.exchange`
* `.expert`
* `.exposed`
* `.express`
* `.fail`
* `.faith`
* `.family`
* `.fan`
* `.fans`
* `.farm`
* `.fashion`
* `.fast`
* `.feedback`
* `.film`
* `.finance`
* `.financial`
* `.fish`
* `.fishing`
* `.fit`
* `.fitness`
* `.flights`
* `.florist`
* `.flowers`
* `.foo`
* `.food`
* `.football`
* `.forex`
* `.forsale`
* `.forum`
* `.foundation`
* `.free`
* `.fun`
* `.fund`
* `.furniture`
* `.futbol`
* `.fyi`
* `.gal`
* `.gallery`
* `.game`
* `.games`
* `.garden`
* `.gent`
* `.gift`
* `.gifts`
* `.gives`
* `.giving`
* `.glass`
* `.global`
* `.gmbh`
* `.gold`
* `.golf`
* `.graphics`
* `.gratis`
* `.green`
* `.gripe`
* `.group`
* `.guide`
* `.guitars`
* `.guru`
* `.hair`
* `.hamburg`
* `.haus`
* `.healthcare`
* `.help`
* `.hiphop`
* `.hiv`
* `.hockey`
* `.holdings`
* `.holiday`
* `.homes`
* `.horse`
* `.hospital`
* `.host`
* `.hosting`
* `.hot`
* `.house`
* `.how`
* `.icu`
* `.immo`
* `.immobilien`
* `.inc`
* `.industries`
* `.info`
* `.ing`
* `.ink`
* `.institute`
* `.insure`
* `.international`
* `.investments`
* `.io`
* `.irish`
* `.jetzt`
* `.jewelry`
* `.jobs`
* `.juegos`
* `.kaufen`
* `.kids`
* `.kim`
* `.kitchen`
* `.kiwi`
* `.land`
* `.lat`
* `.lawyer`
* `.lease`
* `.legal`
* `.lgbt`
* `.life`
* `.lifestyle`
* `.lighting`
* `.limited`
* `.limo`
* `.link`
* `.live`
* `.living`
* `.llc`
* `.loan`
* `.loans`
* `.lol`
* `.london`
* `.lotto`
* `.love`
* `.ltd`
* `.ltda`
* `.luxe`
* `.luxury`
* `.maison`
* `.makeup`
* `.management`
* `.market`
* `.marketing`
* `.markets`
* `.mba`
* `.me`
* `.med`
* `.media`
* `.melbourne`
* `.meme`
* `.memorial`
* `.men`
* `.menu`
* `.miami`
* `.mobi`
* `.moda`
* `.moe`
* `.moi`
* `.mom`
* `.money`
* `.monster`
* `.mortgage`
* `.motorcycles`
* `.mov`
* `.movie`
* `.nagoya`
* `.name`
* `.navy`
* `.net`
* `.network`
* `.news`
* `.nexus`
* `.ninja`
* `.now`
* `.observer`
* `.okinawa`
* `.one`
* `.onl`
* `.online`
* `.ooo`
* `.org`
* `.organic`
* `.osaka`
* `.page`
* `.paris`
* `.partners`
* `.parts`
* `.party`
* `.pet`
* `.phd`
* `.photo`
* `.photography`
* `.photos`
* `.pics`
* `.pictures`
* `.pink`
* `.pizza`
* `.place`
* `.plumbing`
* `.plus`
* `.poker`
* `.porn`
* `.press`
* `.pro`
* `.productions`
* `.prof`
* `.promo`
* `.properties`
* `.property`
* `.pub`
* `.qpon`
* `.quest`
* `.racing`
* `.realty`
* `.recipes`
* `.red`
* `.rehab`
* `.reise`
* `.reisen`
* `.rent`
* `.rentals`
* `.repair`
* `.report`
* `.republican`
* `.rest`
* `.restaurant`
* `.review`
* `.reviews`
* `.rich`
* `.rip`
* `.rocks`
* `.rodeo`
* `.rsvp`
* `.run`
* `.ryukyu`
* `.sale`
* `.salon`
* `.sarl`
* `.sbs`
* `.school`
* `.schule`
* `.science`
* `.services`
* `.sex`
* `.sexy`
* `.sh`
* `.shiksha`
* `.shoes`
* `.shop`
* `.shopping`
* `.show`
* `.singles`
* `.site`
* `.ski`
* `.skin`
* `.soccer`
* `.social`
* `.software`
* `.solar`
* `.solutions`
* `.soy`
* `.space`
* `.spot`
* `.srl`
* `.storage`
* `.store`
* `.stream`
* `.studio`
* `.study`
* `.style`
* `.supplies`
* `.supply`
* `.support`
* `.surf`
* `.surgery`
* `.sydney`
* `.systems`
* `.talk`
* `.tattoo`
* `.tax`
* `.taxi`
* `.team`
* `.tech`
* `.technology`
* `.tel`
* `.tennis`
* `.theater`
* `.theatre`
* `.tickets`
* `.tienda`
* `.tips`
* `.tires`
* `.today`
* `.tokyo`
* `.tools`
* `.top`
* `.tours`
* `.town`
* `.toys`
* `.trade`
* `.trading`
* `.training`
* `.tube`
* `.university`
* `.uno`
* `.vacations`
* `.vana`
* `.vegas`
* `.ventures`
* `.versicherung`
* `.vet`
* `.viajes`
* `.video`
* `.villas`
* `.vin`
* `.vip`
* `.vision`
* `.vodka`
* `.vote`
* `.voting`
* `.voto`
* `.voyage`
* `.watch`
* `.watches`
* `.webcam`
* `.website`
* `.wedding`
* `.wiki`
* `.win`
* `.wine`
* `.work`
* `.works`
* `.world`
* `.wtf`
* `.xxx`
* `.xyz`
* `.yachts`
* `.yoga`
* `.yokohama`
* `.you`
* `.zip`
* `.zone`
# Refunds Flow
Source: https://docs.name.com/guides/refunds-flow
2-step guide with examples on how to delete and refund domains.
## Steps to Refund a Domain
Use this flow to delete eligible domains and security products during the Add Grace Period (AGP) and automatically issue refunds for the associated order items.
This endpoint:
* Enforces ICANN AGP delete limits
* Applies name.com and reseller-specific refund thresholds
* Supports domain registrations and security product add-ons only
Refunds are issued to the original payment method on file, with a fallback to account credit if the payment method is unavailable or fails. You can check your order history in account settings at [name.com](http://name.com) for this information.
***
## Supported Products
Refunds are supported for the below purchase types:
* `registration`
* `whois_privacy`
All other product types are not eligible. Please note: if a registration refund is requested, associated privacy product will also be deleted/refunded
***
## High-Level Flow
1. Use the [List Orders](/api-reference/orders/list-orders) or [Get Order](/api-reference/orders/get-order) endpoints to verify refund eligibility and retrieve the order ID and order item ID(s) that can be refunded.
2. Request the refund using the [Refunds](/api-reference/refunds/process-refund) endpoint
After submitting a refund request, retrieve the order using the Get Order endpoint to review the updated order details. Once an order item has been officially refunded, its status will be returned as:
```
"status": "refunded"
```
***
## Step 1: Check Refund Eligibility (List Orders)
Use the [List Orders](/api-reference/orders/list-orders) or [Get Order](/api-reference/orders/get-order) endpoints immediately before attempting a refund to validate eligibility and reduce failed refund attempts. If `isRefundable`is true, you can retrieve the `orderID`and associated `orderItemIds`required for the Refunds request.
### How to use
* You can filter `listOrders` results by:
* `domainName`
* `createDate`
* `type`(e.g. `registration`,`whois_privacy`)
* `orderStatus`
* Check the `isRefundable`field on each order item. If true, you can initiate a refund via the Refunds endpoint. This field already accounts for ICANN AGP limits, reseller-level thresholds, and Name.com refund policies.
**Important: Refund eligibility is time-sensitive:**
Even if `isRefundable` is true, eligibility may change between this check and the Refund request (for example, if AGP timing expires or refund thresholds are exceeded).
The Refunds endpoint is the source of truth and may still reject the request.
***
## Step 2: Request a Refund (Refunds Endpoint)
Use the [Refunds](/api-reference/refunds/process-refund) endpoint to delete the domain(s) and issue refunds for eligible order items.
Send an `X-Idempotency-Key` with your refund request. Retrying the same request with the same key will not trigger duplicate deletions or refunds.
### Request Requirements
* Accepts a JSON body with:
* `orderId` (required)
* `orderItemIds` (required array, one or more items)
* Only one `orderId`may be provided per request
* Multiple `orderItemIds`are allowed as long as they belong to the same order
* Supported product types only:
* `registration`
* `whois_privacy`
* If WHOIS privacy was purchased on a domain and the domain is refunded, both will be refunded. It can be an explicit or non-explicit request. (you can submit one item id or two item ids)
Example response: Order with a refunded domain and its associated WHOIS privacy add-on
```
{
"results": [
{
"orderId": 123456,
"orderItemId": 7891011,
"orderItemStatus": "refunded",
"refundAmount": 2.99
},
{
"orderId": 121314,
"orderItemId": 1516171,
"orderItemStatus": "refunded",
"refundAmount": 0
}
],
"totalRefundAmount": 2.99
}
```
### Full endpoint reference
For the full request/response schema (including errors), see [Refunds: Process Refund](/api-reference/refunds/process-refund).
# Registrant Communications
Source: https://docs.name.com/guides/registrant-communications
Registrant email obligations (verification, renewals, transfers) plus recommended contact approaches and communication options for resellers.
## Contacts approach
**Reseller-as-Contact** optimizes for speed and reliability, while **End-User-as-Contact** optimizes for clear ownership at the cost of verification and email complexity.
Name.com offers three routes you can take with comms:
* **Reseller as contact** (you set yourself as the registrant contact): end users will not receive emails from name.com; your contact will
* **Name.com sends required emails on your behalf** (whitelabeling available upon request; see [Reseller Whitelabeled Email Examples](https://docs.google.com/presentation/d/158CMhH2HcHzg9RzqgCQDk0iFlYijY4vDqtkDkjVDTfw/edit?usp=sharing))
* **You send your own emails** (requires logging evidence)
Please reach out to [reseller@name.com](mailto:reseller@name.com) for more information.
To learn more about verification flows and logging requirements for sending your own emails, see the [Contact Verification Compliance Guide](/guides/contact-verification).
## Reseller as contact
### Pros
* Simplified onboarding
* High contact verification success (no domains disabled due to verification)
* Full control over domain management
### Key risk: reseller as registrant of record
When the reseller is set as the registrant/admin contact, the reseller is the legal owner of the domain in ICANN and registry systems. While this reduces friction at registration time, it shifts ongoing responsibility to the reseller, including:
* Mediating ownership and transfer requests if a customer wants to move or reclaim a domain
* Receiving and responding to ICANN compliance, abuse, and policy notices
* Managing all domain issues, recovery requests, and edge cases on behalf of customers
Because the reseller is the registrant of record, legal notices (e.g., cease-and-desist letters, takedown requests, and potential lawsuits) are served to the reseller, not the end customer.
As domain volume grows, this model can increase support load, compliance responsibility, and operational risk. Resellers using this approach should clearly document domain ownership and customer rights in their terms of service.
## End user as contact
### Pros
* Clear end-customer ownership of domains
* Avoids reseller legal ownership and liability described above
### Cons
* Lower contact verification success rates
* Requires reliable end-user email delivery
* Verification, renewal, and compliance emails must either be white-labeled or fully owned by the reseller. If you’d like to fully take over emails and the verification process, please reach out to our team.
* Higher onboarding and operational complexity
## ICANN-required registrant emails
### Verification
| Email | Trigger | Content |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Registrant verification (expires in 15 days)** | Domain registration or incoming transfer with an unverified registrant contact, **or** changes to the registrant’s contact | A clear statement that ICANN requires verification of the registrant contact. A unique verification link or token the user must click or use. A warning that failure to verify within 15 days will result in domain suspension. |
| **Verification reminder** | Before the 15‑day window expires | A clear statement that ICANN requires verification of the registrant contact. A unique verification link or token the user must click or use. A warning that failure to verify within 15 days will result in domain suspension and note how many days registrant has left to verify. |
| **Verification expired / suspension notice** | Day 16+ (when domain is disabled) | Notification that the domain is suspended. The reason: failure to verify registrant contact (usually email). Mention that this is an ICANN-required process. A path to resolve (e.g., verification link). |
The below also must be shared with new registrants:
The Organization field in your domain’s contact details relates to legal ownership. If this field contains information, the listed organization is considered the legal “Registered Name Holder” (domain owner).
### Renewal
| Email | Trigger | Content |
| ----------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Renewal notices (pre-expiry)** | At least 2 notices before expiration: (1) \~30 days before, (2) \~5 days before expiration | Remind registrant of upcoming expiration. Must clearly state domain name, expiration date, and renewal instructions. |
| **Renewal failure / expiry notice** | Within 5 days after expiration (if domain not renewed) | Notice that the domain has expired but may still be renewed/redeemed. Must include info on how to recover the domain and the deadline. |
### Transfers, change of registrant, and contact review
| Email | Trigger | Content |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Transfer out (FOA – losing registrar)** | When a transfer is requested away from the current registrar (the “losing” registrar) | Confirmation email to both old and new registrant addresses (if applicable). Must explain that a change has been requested and provide means to cancel. |
| **Change of registrant confirmation** | Registrant contact information changed | Confirmation email to both old and new registrant addresses. Must explain that a change has been made. |
| **Whois Data Reminder Policy (WDRP)** | Annually for each domain (usually 120–30 days before expiration). Must be sent once per year per domain regardless of renewal cycle | Reminder to review and update WHOIS contact information. Provide a path to update if needed. Must state that providing false contact info can lead to suspension or cancellation. Contact information includes: Registrant Name, Organization (if provided), Email Address, Phone Number, Address. |
# Testing Environment
Source: https://docs.name.com/guides/testing-environment
How to use the sandbox environment for safe integration testing, plus known constraints and differences from production.
The name.com Core API provides a **sandbox (testing) environment** that mirrors production request/response shapes, so you can build and run automated integration tests without affecting real domains or incurring real charges.
This page focuses on **what’s different in sandbox** and the **common issues** teams run into when testing.
## When to use sandbox vs production
* **Sandbox** (`https://api.dev.name.com`): safe development, integration tests, trying purchase flows, and experimenting with API behavior.
* **Production** (`https://api.name.com`): real domains, real billing, and live DNS/registry behavior.
If you’re brand new to the API, start with [Getting Started](/guides/getting-started) and the [API Overview](/api/v1/overview).
## Authentication
Authentication is the same mechanism in both environments (**HTTP Basic Auth**). For full details and examples (curl `-u` vs explicit header, Base64 generation, etc.), see [Authentication](/guides/authentication).
Sandbox-specific requirements:
* Use your username with `-test` appended (example: `reseller123-test`)
* Use the API token labeled **Development/Test Environment** from account settings (`https://www.name.com/account/settings/api`)
In rare cases, newly generated sandbox credentials can take **up to 15 minutes** to become active. If it’s been longer than that, reach out to support at [reseller@name.com](mailto:reseller@name.com).
## Endpoints
* **Sandbox**: `https://api.dev.name.com`
* **Production**: `https://api.name.com`
## Quick verification
Use `GET /core/v1/hello` to verify connectivity and credentials:
```bash theme={null}
curl -u your-username-test:your-sandbox-token https://api.dev.name.com/core/v1/hello
```
## What is production-like in sandbox
* **Same endpoints and JSON shapes**: request/response formats are intended to match production.
* **Same validation rules**: invalid payloads should fail the same way they would in production.
* **Same rate limits**: see [Rate Limits](/api/v1/overview#rate-limits) for current thresholds.
* **Preloaded test credit**: sandbox accounts include credit so you can exercise purchase/registration flows without real funds (see details below).
## Key constraints and differences (read before writing tests)
### 1) Domain availability and TLD behavior will differ
Sandbox uses **test data** for registry/TLD behavior. You may see differences compared to production, including:
* Availability results that don’t match production
* Claims-related responses that don’t match production (see [Claims Flow](/guides/claims-flow) and [Check Domain Claims](/api/v1/reference/domain-info/check-domain-claims))
* Pricing that differs from production (including **premium domains** and **account-level pricing**)
* Some TLDs not being available in sandbox
If your integration depends on a specific TLD or policy, design tests so they don’t assume production availability/requirements.
**Premium domains & pricing:** Premium classification and pricing can behave differently in sandbox. Sandbox pricing (especially premium pricing and account-specific pricing) should be treated as **non-authoritative** — validate production pricing as part of your launch readiness process.
### 2) Sandbox and production are fully separate
Data does **not** sync between environments. A domain created in sandbox only exists in sandbox.
If a request returns 404 in sandbox, confirm you created that resource in sandbox first. This is a common gotcha when switching between environments.
### 3) DNS records and nameservers can be set, but won’t resolve publicly
In sandbox, DNS-related API calls can succeed (and you can retrieve what you set), but the changes **will not become publicly queryable via DNS**.
This affects flows like:
* Managing DNS records (example: `POST /core/v1/domains/{domainName}/records`)
* Setting nameservers (example: `POST /core/v1/domains/{domainName}:setNameservers`)
What to test in sandbox:
* Your request building and validation handling
* Your persistence of returned IDs and record objects
* Your read/modify/delete flows against the API
What you should not expect in sandbox:
* Public DNS resolution reflecting your changes (e.g., `dig`, `nslookup`, browser resolution)
### 4) Webhooks work the same as production
You can create and manage webhook subscriptions via the API (for example: `POST /core/v1/notifications`). In sandbox/OT\&E webhooks are supported and intended to behave the same as production.
Recommended approach:
* Test your subscription management logic in sandbox
* Test your webhook handler with real sandbox events, and also keep a test harness (replay a captured payload, or send a synthetic payload to your endpoint) so you can validate signature checks, retries, and idempotency
### 5) Sandbox behavior can change over time
Sandbox is intended for testing and may receive updates and configuration changes that are not synchronized with your integration timeline.
Do not hardcode assumptions from sandbox into production logic (for example, specific TLD requirements or edge-case behaviors). Always validate production behavior during your launch readiness process.
### 6) Domains cannot be deleted or reset
Domains that are **created or transferred** in sandbox **cannot be deleted** and there isn’t a “reset” mechanism for returning your sandbox account to a blank slate.
Sandbox is also designed to simulate real-world scenarios where possible. In practice, you should expect domain state to follow the standard domain lifecycle (including expiration-related flows), but registry OT\&E behavior can vary and may change over time.
Recommendations:
* Use unique test domains per test run (timestamp/UUID prefix)
* Design tests to be idempotent (safe to re-run without cleanup)
### 7) Transfers are not deterministic in sandbox
Sandbox does not support deterministic “force success/failure/auth error” transfer outcomes. If your integration includes transfers:
* Validate request/response handling and state polling in sandbox
* Perform final end-to-end verification in production as part of your launch checklist
### 8) Sandbox errors are driven by registry OT\&E behavior
In sandbox, many behaviors (and errors) are determined by the **operational test & evaluation (OT\&E)** environment of the related registry. Typically, an error you see during registration, contact updates, etc. will resemble the kinds of errors you may see in production.
However, **name.com cannot guarantee** that a registry’s sandbox/OT\&E behavior will exactly match its production behavior, and sandbox errors may not explicitly indicate when something is unsupported or simulated.
If you see an error you can’t interpret, capture the request/response and contact support at [reseller@name.com](mailto:reseller@name.com).
## Sandbox account credit behavior
Sandbox accounts are provisioned with **\$100,000 of account credit** so you can run paid workflows (registrations, renewals, privacy, etc.) without real billing.
* **Auto-refresh/reset**: The balance is regularly reset back to **\$100,000** if it has been spent down.
* **Test-only**: This credit is sandbox-only and has no real-world monetary value.
* **Running out is unlikely**: Credit is replenished regularly, so most integrations won’t need to worry about depletion.
## Suggested testing workflow
Create a **Development/Test Environment** API token and use your `-test` username. See [Authentication](/guides/authentication).
Call `GET /core/v1/hello` in sandbox to confirm credentials.
Many domain endpoints require the domain to exist in the current environment. Register it in sandbox before calling domain/DNS endpoints.
Respect rate limits and implement retry/backoff for `429 Too Many Requests`.
## Troubleshooting checklist (common issues)
Confirm you are using:
* `https://api.dev.name.com`
* your `-test` username
* the **Development/Test Environment** token (not your production token)
The resource must exist in the environment you’re querying. In sandbox, register/create the domain first, then retry.
Expected: sandbox stores DNS configuration for API testing, but it does not publish DNS in a way that becomes publicly resolvable.
Webhooks are supported in sandbox. If you’re not seeing events:
* Verify the subscription exists and matches the event type(s) you expect
* Confirm the action you performed actually emits the event you subscribed to
* Check your endpoint is reachable and returns a 2xx response
* Review your logs for signature validation or parsing failures
## Where to go next
Create tokens, choose sandbox vs production, and make your first call
Full Basic Auth guide (curl and header examples)
Rate limits, error formats, and core API conventions
If you notice inconsistencies between this documentation and what you’re seeing in the sandbox/OT\&E environment, email us at [reseller@name.com](mailto:reseller@name.com). If possible, include the endpoint, timestamp, and a sanitized request/response sample.
# name.com Core API Documentation
Source: https://docs.name.com/index
Modern domain management API for developers, SaaS platforms, and businesses
You're viewing the ***name.com CORE API*** documentation — our latest version, built for developers, SaaS platforms, and businesses that need modern domain integration.
Here you'll find everything you need to integrate with the name.com API to build domain storefronts, automate domain management, and run domain operations programmatically.
## Download the OpenAPI Spec
Download our latest OpenAPI specification to start generating clients instantly.
Get the latest version of the name.com CORE API in YAML format
## Quick Start
Learn how to authenticate and make your first API call
Understand the API structure, environments, and key features
Search → Register → Manage
Migrate from v4 to Core API
## What's New in CORE API
* **OpenAPI 3.1** specification for better tooling support
* **Improved error handling** with specific HTTP status codes
* **Consistent response format** with explicit default values
* **Enhanced security** with proper Content-Type enforcement
* **Modern RESTful design** for better developer experience
## Get Help
Find answers to common questions
Track API updates and changes
# API Docs MCP
Source: https://docs.name.com/integrations/mcp/api-docs-mcp
Read‑only MCP server that lets agents search and cite the name.com Core API documentation in chat. It does not execute API calls; use the name.com Core API MCP for live operations.
## What it can do
* Search across the complete name.com CORE API documentation content
* Answer “how do I…” questions with links back to related pages
* Surface endpoint details and examples for implementation and debugging
## Setup
Add the name.com CORE API Docs MCP server configuration to your desired MCP client (e.g., Cursor).
In Cursor:
Settings → MCP → Add Server
Paste the client configuration below
Save the server, enable it, and start asking questions!
Client configuration:
```json theme={null}
{
"mcpServers": {
"namecom-docs": {
"type": "http",
"url": "https://docs.name.com/mcp"
}
}
}
```
## Example prompts
* “Search the docs for sandbox authentication requirements.”
* “Show the steps to generate an API token and link the page.”
* “Find the section that explains webhook retries.”
* “What parameters are required for the transfer endpoint in the docs?”
# name.com MCP
Source: https://docs.name.com/integrations/mcp/namecom-mcp
The name.com Model Context Protocol (MCP) server lets AI agents (e.g., Cursor, Claude Desktop) safely call name.com Core API operations on your behalf. This enables assistants to look up account info, manage domains, and perform other tasks programmatically with your authorization.
## What it can do
* Make authenticated calls to name.com CORE API endpoints
* Retrieve and summarize API responses in chat
* Automate common workflows (e.g., check account credit balance, purchase & manage domains, configure DNS)
## Setup
Add the server to your MCP client (e.g., Cursor) configuration and provide your API credentials.
In Cursor:
Settings → MCP → Add Server (may differ by MCP client)
The example config is complete aside from filling in environment variables
Provide your API username, token, and base URL (production or sandbox). If base URL is not provided, the sandbox URL will be used by default.
Save the server and test with a simple request: "How many domains are expiring soon in my account?"
Example client configuration:
```json theme={null}
{
"mcpServers": {
"namecom-mcp": {
"command": "npx",
"args": ["-y", "namecom-mcp@latest"],
"env": {
"NAME_USERNAME": "",
"NAME_TOKEN": "",
"NAME_API_URL": "https://mcp.name.com" # only required if using the production environment
}
}
}
}
```
Sandbox URL: [https://mcp.dev.name.com](https://mcp.dev.name.com)
Production URL: [https://mcp.name.com](https://mcp.name.com)
## Example prompts
* “What is my account credit balance?”
* “I need help finding a domain for my new business idea: a coffee shop for people and their pets!”
* “Please tell me what domains of mine are expiring in the next 3 months”
* “Renew myawesomedomain.rocks for 3 more years”
## Reference
For more details about the name.com CORE API MCP Server, please refer to the published NPM package:
* npm package: `https://www.npmjs.com/package/namecom-mcp`
# FAQ & Troubleshooting
Source: https://docs.name.com/resources/faq
Frequently asked questions and troubleshooting guide for name.com Core API
# name.com CORE API – FAQ
Use HTTP Basic Authentication with your name.com username and API token. You can use curl's `-u username:token` shorthand or send an explicit `Authorization: Basic ` header. See the full [Authentication](/guides/authentication) guide for Linux/macOS and Windows PowerShell commands to generate the Base64 value.
✅ Yes. You can keep 2FA enabled on your account, but it will block API access until you allow API access as well. Enable the 2FA API Access option in your account settings -> two-step verification to use the API while 2FA remains active.
❌ No. The API is for server-side use only. Browser requests are blocked due to CORS restrictions.
✅ Yes. Any tool that can send HTTPS requests — including PowerShell, curl, Python, or Node.js — is supported. For a PowerShell example to generate the Basic Auth header, see [Authentication](/guides/authentication).
All API requests must use HTTPS on port 443.
❌ No. Domains, DNS records, and user data are completely separate between environments.
❌ No. The sandbox uses registry test data, so domain availability and behavior may differ.
Use the sandbox environment (`https://api.dev.name.com`) with your -test username and sandbox API token. Sandbox domains are not live or publicly registered. See [Testing environment](/guides/testing-environment) for sandbox constraints and differences from production.
The API uses standard RESTful HTTP codes like 200 OK, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, and 429 Too Many Requests.
The domain must exist in the environment you're querying. Check whether you're using sandbox or production.
You can check up to 50 domains per checkAvailability call.
You'll receive a 429 Too Many Requests error. Use backoff logic and retry after a delay.
✅ Yes. You can use saved credit card profiles and account credit for domain purchases via the API. Ensure your preferred payment method is set as the default payment method within your account.
🔔 Check the Changelog for the latest version releases, features, and any upcoming deprecations.
## Next Steps
Set up authentication, environments, and make your first API call
View endpoints for domains, DNS, transfers, and more
Track new features, breaking changes, and deprecations
Reach out for help with advanced issues or account-specific questions