curl --request POST \
  --url https://api.dev.name.com/core/v1/domains \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "domain": {
    "domainName": "example.com"
  }
}
'

{
  "domain": {
    "domainName": "example.com",
    "createDate": "2023-01-15T14:30:00Z",
    "expireDate": "2025-01-15T14:30:00Z",
    "autorenewEnabled": true,
    "locked": true,
    "privacyEnabled": true,
    "contacts": {
      "admin": {
        "firstName": "John",
        "lastName": "Doe",
        "companyName": "Example Inc.",
        "address1": "123 Main Street",
        "address2": "Suite 400",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "+15551234567",
        "fax": "+15557654321",
        "isVerified": true,
        "verificationId": 12345
      },
      "billing": {
        "firstName": "John",
        "lastName": "Doe",
        "companyName": "Example Inc.",
        "address1": "123 Main Street",
        "address2": "Suite 400",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "+15551234567",
        "fax": "+15557654321",
        "isVerified": true,
        "verificationId": 12345
      },
      "registrant": {
        "firstName": "John",
        "lastName": "Doe",
        "companyName": "Example Inc.",
        "address1": "123 Main Street",
        "address2": "Suite 400",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "+15551234567",
        "fax": "+15557654321",
        "isVerified": true,
        "verificationId": 12345
      },
      "tech": {
        "firstName": "John",
        "lastName": "Doe",
        "companyName": "Example Inc.",
        "address1": "123 Main Street",
        "address2": "Suite 400",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "+15551234567",
        "fax": "+15557654321",
        "isVerified": true,
        "verificationId": 12345
      }
    },
    "nameservers": [
      "ns1.example.com",
      "ns2.example.com"
    ],
    "locks": [
      "clientTransferProhibited",
      "clientHold"
    ],
    "transferLockExpiresAt": "2023-03-16T14:30:00Z",
    "renewalPrice": 12.99
  },
  "order": 123,
  "totalPaid": 123
}

Domains

Create Domain

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 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 or Check Availability, not Get Pricing alone. Both return the same SearchResult fields (purchaseType, purchasePrice, premium, purchasable). Zone Check is designed for rapid availability checks only; it is not sufficient to complete a purchase.

Getting the price for Create Domain

Search or Check Availability → copy purchaseType, premium, note purchasePrice.
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.
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 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 endpoint, or the 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.

POST

core

domains

curl --request POST \
  --url https://api.dev.name.com/core/v1/domains \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "domain": {
    "domainName": "example.com"
  }
}
'

{
  "domain": {
    "domainName": "example.com",
    "createDate": "2023-01-15T14:30:00Z",
    "expireDate": "2025-01-15T14:30:00Z",
    "autorenewEnabled": true,
    "locked": true,
    "privacyEnabled": true,
    "contacts": {
      "admin": {
        "firstName": "John",
        "lastName": "Doe",
        "companyName": "Example Inc.",
        "address1": "123 Main Street",
        "address2": "Suite 400",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "+15551234567",
        "fax": "+15557654321",
        "isVerified": true,
        "verificationId": 12345
      },
      "billing": {
        "firstName": "John",
        "lastName": "Doe",
        "companyName": "Example Inc.",
        "address1": "123 Main Street",
        "address2": "Suite 400",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "+15551234567",
        "fax": "+15557654321",
        "isVerified": true,
        "verificationId": 12345
      },
      "registrant": {
        "firstName": "John",
        "lastName": "Doe",
        "companyName": "Example Inc.",
        "address1": "123 Main Street",
        "address2": "Suite 400",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "+15551234567",
        "fax": "+15557654321",
        "isVerified": true,
        "verificationId": 12345
      },
      "tech": {
        "firstName": "John",
        "lastName": "Doe",
        "companyName": "Example Inc.",
        "address1": "123 Main Street",
        "address2": "Suite 400",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "+15551234567",
        "fax": "+15557654321",
        "isVerified": true,
        "verificationId": 12345
      }
    },
    "nameservers": [
      "ns1.example.com",
      "ns2.example.com"
    ],
    "locks": [
      "clientTransferProhibited",
      "clientHold"
    ],
    "transferLockExpiresAt": "2023-03-16T14:30:00Z",
    "renewalPrice": 12.99
  },
  "order": 123,
  "totalPaid": 123
}

Authorizations

Authorization

string

header

required

Authenticate via HTTP Basic with your account username and API token. Examples use an explicit 'Authorization: Basic <base64(username:token)>' header; 'curl -u username:token' is equivalent. For sandbox, append "-test" to your username and use your sandbox token on api.dev.name.com.

Headers

X-Idempotency-Key

string

A unique string (e.g., a UUID v4) to make the request idempotent. This key ensures that if the request is retried, the operation will not be performed multiple times. Subsequent requests with the same key will return the original result.

Example:

"083910ef-04e4-4bd1-a0bf-3737fe005ca8"

Body

application/json

CreateDomainRequest has the information that is needed to create a domain with the CreateDomain function. See the Domain pricing guide for which endpoints supply create pricing (Search/Check Availability vs Get Pricing) for each purchaseType.

domain

object

required

The payload to be sent for when making a request to purchase a domain.

Show child attributes

purchasePrice

number<double>

PurchasePrice is the price in USD for purchasing this domain for the minimum time period (typically 1 year). PurchasePrice is required if purchaseType is not "registration" or if it is a premium domain. Whois Privacy is free and does not affect purchasePrice. If privacyEnabled is omitted, the account default from account settings is used. If VAT tax applies, it will also be added automatically.

purchaseType

string

PurchaseType indicates what kind of purchase this domain create is for. Defaults to registration if omitted. Recommended: Use registration unless you support acquisition types (aftermarket, expiring, backorder) — see the Domain purchase pricing guide. This value should be copied from the Search or Check Availability result. The value registration covers both standard and registry premium domains — use the premium flag from the discovery result to tell them apart. Aftermarket, expiring, and backorder types use flat acquisition fees from Search or Check Availability; see the Domain pricing guide.

tldRequirements

object

TLDRequirements is a way to pass additional data that is required by some registries. You can check before registration by using the Domain Info API. As these requirements vary wildly between registries and TLDs, we are not attempting to document them here.

IDN Domains

This parameter is required for registering domains that contain non-ASCII characters. The value should be the specific code for the character set, such as ES for Spanish, or CYRL for Cyrillic. These abbreviations can vary between TLDs, and it is highly recommended that you use Domain Info API to ensure that the TLD allows for the specific IDN table, as well as the correct abbreviation.

Show child attributes

claims

object

Claims acknowledgement data is required if trademark claims exist for requested domain. This data is obtained from a Domain Claims Check response and includes the claim identifier and validity dates.

Show child attributes

years

integer<int32>

Years specifies the registration term in years. Only affects price and registration length for purchaseType: registration. Defaults to each TLD's minimum if omitted (usually 1; 2 for .ai). Must be a supported registration term for the TLD when purchaseType is registration (commonly 1–10 years). For purchaseType: registration when purchasePrice is required, call Get Pricing with the same years value. For aftermarket, expiring, and backorder types: pass the TLD default — it does not multiply purchasePrice and does not guarantee a multi-year registration. Check domain.expireDate in the create response for actual expiry. To add registration time after acquisition, use Renew Domain.

Example:

1

PromoCode is an optional promotional code to apply to the domain purchase. Only one promo code can be applied per request. Promo codes specify eligibility criteria, including duration. If the supplied promo applies no discount, the request fails with 400 and "Promo code does not apply a discount to this purchase". The order is not created.

Minimum string length: 1

Response

A successful response.

CreateDomainResponse contains the domain info as well as the order info for the created domain.

domain

object

required

The response format for a domain.

Show child attributes

order

integer<int32>

required

Order is an identifier for this purchase.

totalPaid

number<double>

required

TotalPaid is the total amount paid, including VAT when applicable. Whois Privacy is free and is not included in this amount.

API Home

Guides & Flows

Official SDKs

Core API Reference

Resources

Create Domain

Create Domain pricing

Getting the price for Create Domain

Best Practices For Domain Creates

Important Note on Dropcatching and Abuse Prevention

Contact Verification

Authorizations

Headers

Body

IDN Domains

Response