# Register or transfer in a domain

Register a new domain or transfer an existing domain into your account. The request body specifies the domain name and optional DNS configuration including registration period, contacts, and nameserver settings.

To register a new domain, submit the request without an authorization code. To transfer in an existing domain from another registrar, include the dns.authorizationCode field — the presence of this field determines that this is a transfer-in rather than a new registration.

Use $preview=true to validate the request and get a price quote without executing the operation.

Endpoint: POST /domains
Version: 1.0.0
Security: bearer

## Query parameters:

  - `$preview` (boolean, required)

## Request fields (application/json):

  - `name` (string, required)
    Fully qualified domain name to register (e.g., "example.com"). Automatically lowercased and trimmed.

  - `owner` (object)
    Owner (registrant) for the domain. Includes ownership type and registrant contact information.

  - `owner.type` (string, required)
    Enum: "MANAGED"

  - `owner.contact` (object)
    Provide EITHER an existing contact id (format: ct-) OR the full set of inline contact fields to create a new contact. When id is provided, all other fields are ignored. When id is absent, the following fields are required: firstName, lastName, countryCode, street, city, postalCode, stateProvince, phone, email. For the owner (registrant) contact, an optional tldData field can provide TLD-specific data (e.g., CIRA requirements for .ca domains) when creating a new contact.

  - `owner.contact.tldData` (object)
    TLD-specific data required for certain TLDs (e.g., CIRA requirements for .ca). Only applicable when creating a new contact (id is absent).

  - `owner.contact.tldData.ca` (object)
    CIRA-specific data required for .ca domain registration. All fields are required.

  - `owner.contact.tldData.ca.registrantAgreementAcknowledged` (boolean, required)
    Must be true to acknowledge the CIRA registrant agreement. Submitting false will fail validation.
    Enum: true

  - `owner.contact.tldData.ca.preferredLanguageCode` (string, required)
    Enum: "en_US", "fr_CA", "en", "fr"

  - `owner.contact.tldData.ca.canadianPresenceRequirement` (string, required)
    Enum: "CCT", "LGR", "RES", "ABO", "CCO", "ASS", "PRT", "TDM", "TRD", "PLT", "TRS", "LAM", "EDU", "HOP", "GOV", "INB", "OMK", "MAJ"

  - `owner.contact.id` (string)
    Existing contact ID. When provided, all other fields are ignored.
    Example: "ct-a1b2c3d4-e5f6-7890-abcd-ef1234567890"

  - `owner.contact.firstName` (string)

  - `owner.contact.lastName` (string)

  - `owner.contact.organization` (string)

  - `owner.contact.countryCode` (string)
    ISO 3166-1 alpha-2 country code (e.g., "US", "CA", "GB"). Required when creating a new contact.

  - `owner.contact.street` (string)

  - `owner.contact.city` (string)

  - `owner.contact.postalCode` (string)
    Postal/ZIP code. Validated against the provided countryCode. Required when creating a new contact.

  - `owner.contact.stateProvince` (string)
    State or province. Validated against the provided countryCode. Required when creating a new contact.

  - `owner.contact.phone` (object)
    Phone number with international dialing prefix.

  - `owner.contact.phone.number` (string, required)
    Phone number digits (numeric string, 6-14 characters).

  - `owner.contact.phone.dialingPrefix` (string, required)
    International dialing prefix (e.g., "+1" for US/CA, "+44" for UK).
    Example: "+1"

  - `owner.contact.email` (string)

  - `dns` (object)
    DNS configuration for the domain including registration period and contact role assignments.

  - `dns.authorizationCode` (string)
    EPP authorization code for domain transfer. Only applicable for transfer-in operations.

  - `dns.period` (number)
    Registration period in years (1-10). If omitted, defaults to the minimum period for the TLD.

  - `dns.contacts` (object)
    Non-registrant contact role assignments (admin, tech, billing). Each role accepts an existing contact ID or inline fields.

  - `dns.contacts.admin` (object)
    Provide EITHER an existing contact id (format: ct-) OR the full set of inline contact fields to create a new contact. When id is provided, all other fields are ignored. When id is absent, the following fields are required: firstName, lastName, countryCode, street, city, postalCode, stateProvince, phone, email.

  - `dns.contacts.tech` (object)
    Provide EITHER an existing contact id (format: ct-) OR the full set of inline contact fields to create a new contact. When id is provided, all other fields are ignored. When id is absent, the following fields are required: firstName, lastName, countryCode, street, city, postalCode, stateProvince, phone, email.

  - `dns.contacts.billing` (object)
    Provide EITHER an existing contact id (format: ct-) OR the full set of inline contact fields to create a new contact. When id is provided, all other fields are ignored. When id is absent, the following fields are required: firstName, lastName, countryCode, street, city, postalCode, stateProvince, phone, email.

  - `dns.$useExistingNameservers` (boolean)
    When true, retains the existing nameserver configuration instead of resetting to defaults.

  - `dns.nameservers` (array)
    Custom nameserver hostnames to set during registration. If omitted, UD-managed nameservers are used.
    Example: ["ns1.example.com","ns2.example.com"]

  - `dns.records` (array)
    DNS records to create during registration.

  - `dns.records.subName` (string)
    Subdomain name (e.g., "www", "mail"). Omit or leave empty for the apex domain.

  - `dns.records.type` (string, required)
    DNS record type. Case-insensitive — values are uppercased automatically.
    Enum: "A", "AAAA", "ALIAS", "CAA", "CNAME", "DNSKEY", "DS", "HTTPS", "IPSECKEY", "MX", "NAPTR", "NS", "PTR", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TLSA", "TXT"

  - `dns.records.values` (array, required)

  - `dns.records.ttl` (number, required)

  - `dns.records.$upsert` (string)
    Upsert mode for handling conflicts with existing records. Case-insensitive. REPLACE: overwrite existing record values. APPEND: add values to existing record. DISALLOWED: fail if record exists.
    Enum: "REPLACE", "APPEND", "DISALLOWED"

  - `dns.records.$forceCompatibility` (boolean, required)

  - `dns.dnssec` (object)

  - `dns.dnssec.items` (array, required)

  - `dns.dnssec.items.keyTag` (number, required)

  - `dns.dnssec.items.algorithm` (number, required)
    Enum: 1, 2, 3, 4, 5, 6, 7, 8, 10, 12, 13, 14, 15, 16, 17, 23, 252, 253, 254

  - `dns.dnssec.items.digestType` (number, required)
    Enum: 1, 2, 3, 4, 5, 6

  - `dns.dnssec.items.digest` (string, required)

  - `flags` (object)
    Initial domain flag settings (e.g., transfer lock, auto-renew).

  - `flags.DNS_RESOLUTION` (object)

  - `flags.DNS_RESOLUTION.status` (string, required)
    Enum: "ENABLED", "DISABLED"

  - `flags.DNS_TRANSFER_OUT` (object)

  - `flags.DNS_DELETE` (object)

  - `flags.DNS_UPDATE` (object)

  - `flags.DNS_RENEW` (object)

  - `flags.DNS_WHOIS_PROXY` (object)

## Response 201 fields (application/json):

  - `@type` (string, required)
    Enum: "unstoppabledomains.com/partner.v3.DomainOperationResult"

  - `operation` (object, required)

  - `operation.id` (string, required)
    Operation ID
    Example: "op-a1b2c3d4-e5f6-7890-abcd-ef1234567890"

  - `operation.status` (string, required)
    Enum: "PREVIEW", "QUEUED", "PROCESSING", "FAILED", "COMPLETED", "CANCELLED", "AWAITING_UPDATES"

  - `operation.type` (string, required)
    Enum: "ADMIN_GENERIC", "DOMAIN_ADMIN_UPDATE", "DOMAIN_RENEW", "ACCOUNT_UPDATE", "DOMAIN_DNS_RECORD_CREATE", "DOMAIN_DNS_RECORD_UPDATE", "DOMAIN_DNS_RECORD_DELETE", "DOMAIN_DNS_RECORD_BATCH", "DOMAIN_DNS_SECURITY_ENABLE", "DOMAIN_DNS_SECURITY_DELETE", "DOMAIN_DNS_NAME_SERVER_UPDATE", "DOMAIN_HOSTING_UPDATE", "DOMAIN_HOSTING_DISABLE", "DOMAIN_TRANSFER_OUT", "DOMAIN_TRANSFER_OUT_TOGGLE", "DOMAIN_FLAGS_UPDATE", "DOMAIN_CONTACTS_UPDATE", "CONTACT_CREATE", "DOMAIN_SUGGESTION_CREATE", "DOMAIN_SUGGESTION_REFRESH"

  - `operation.domain` (string)

  - `operation.createdAtTimestamp` (number, required)

  - `operation.lastUpdatedTimestamp` (number, required)

  - `operation.validUntilTimestamp` (number)

  - `operation.dependencies` (array, required)
    List of platform operation dependencies that make up this operation