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

  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 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/v1/domains

Request

  • Base URL: https://api.dev.name.com
  • URL: https://api.dev.name.com/core/v1/domains
  • Auth: HTTP basic

Headers

X-Idempotency-Keystring
Example:083910ef-04e4-4bd1-a0bf-3737fe005ca8

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.

Request body

purchasePricenumber 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. If privacyEnabled is set, the regular price for Whois Privacy protection will be added automatically. If VAT tax applies, it will also be added automatically.

purchaseTypestring

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.

tldRequirementsobject

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.

yearsinteger

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.

promoCodestring

PromoCode is an optional promotional code to apply to the domain purchase. Only one promo code can be applied per request.

Example request

{
  "domain": {
    "domainName": "example.com",
    "createDate": "2023-01-15T14:30:00Z",
    "expireDate": "2025-01-15T14:30:00Z",
    "autorenewEnabled": true,
    "locked": true,
    "locks": [
      "clientTransferProhibited",
      "clientHold"
    ],
    "transferLockExpiresAt": "2023-03-16T14:30:00Z",
    "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"
    ],
    "renewalPrice": 12.99
  },
  "claims": {
    "claimId": "8c3027d30000000000382500785",
    "notBefore": "2024-01-15T10:30:00Z",
    "notAfter": "2024-01-15T10:30:00Z"
  },
  "years": 1
}

Response

A successful response.

orderinteger required

Order is an identifier for this purchase.

totalPaidnumber double required

TotalPaid is the total amount paid, including VAT and Whois privacy protection.

Example response

{
  "domain": {
    "domainName": "example.com",
    "createDate": "2023-01-15T14:30:00Z",
    "expireDate": "2025-01-15T14:30:00Z",
    "autorenewEnabled": true,
    "locked": true,
    "locks": [
      "clientTransferProhibited",
      "clientHold"
    ],
    "transferLockExpiresAt": "2023-03-16T14:30:00Z",
    "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"
    ],
    "renewalPrice": 12.99
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.