Registrar

Search for available domains

client.registrar.search(, ?): RegistrarSearchResponse { domains }

GET/accounts/{account_id}/registrar/domain-search

Check domain availability

client.registrar.check(, ?): RegistrarCheckResponse { domains }

POST/accounts/{account_id}/registrar/domain-check

ModelsExpand Collapse

Registration { auto_renew, created_at, domain_name, 4 more }

A domain registration resource representing the current state of a registered domain.

auto_renew: boolean

Whether the domain will be automatically renewed before expiration.

created_at: string

When the domain was registered. Present when the registration resource exists.

formatdate-time

domain_name: string

Fully qualified domain name (FQDN) including the extension (e.g., example.com, mybrand.app). The domain name uniquely identifies a registration — the same domain cannot be registered twice, making it a natural idempotency key for registration requests.

expires_at: string | null

When the domain registration expires. Present when the registration is ready; may be null only while status is registration_pending.

formatdate-time

locked: boolean

Whether the domain is locked for transfer.

privacy_mode: "redaction"

Current WHOIS privacy mode for the registration.

status: "active" | "registration_pending" | "expired" | 3 more

Current registration status.

active: Domain is registered and operational
registration_pending: Registration is in progress
expired: Domain has expired
suspended: Domain is suspended by the registry
redemption_period: Domain is in the redemption grace period
pending_delete: Domain is pending deletion by the registry

One of the following:

"active"

"registration_pending"

"expired"

"suspended"

"redemption_period"

"pending_delete"

WorkflowStatus { completed, created_at, links, 4 more }

Status of an async registration workflow.

completed: boolean

Whether the workflow has reached a terminal state. true when state is succeeded or failed. false for pending, in_progress, action_required, and blocked.

created_at: string

formatdate-time

links: Links { self, resource }

self: string

URL to this status resource.

resource?: string

URL to the domain resource.

state: "pending" | "in_progress" | "action_required" | 3 more

Workflow lifecycle state.

pending: Workflow has been created but not yet started processing.
in_progress: Actively processing. Continue polling links.self. The workflow has an internal deadline and will not remain in this state indefinitely.
action_required: Paused — requires action by the user (not the system). See context.action for what is needed. An automated polling loop must break on this state; it will not resolve on its own without user intervention.
blocked: The workflow cannot make progress due to a third party such as the domain extension’s registry or a losing registrar. No user action will help. Continue polling — the block may resolve when the third party responds.
succeeded: Terminal. The operation completed successfully. completed will be true. For registrations, context.registration contains the resulting registration resource.
failed: Terminal. The operation failed. completed will be true. See error.code and error.message for the reason. Do not auto-retry without user review.

One of the following:

"pending"

"in_progress"

"action_required"

"blocked"

"succeeded"

"failed"

updated_at: string

formatdate-time

context?: Record<string, unknown>

Workflow-specific data for this workflow.

The workflow subject is identified by context.domain_name for domain-centric workflows.

error?: Error | null

Error details when a workflow reaches the failed state. The specific error codes and messages depend on the workflow type (registration, update, etc.) and the underlying registry response. These workflow error codes are separate from immediate HTTP error errors[].code values returned by non-2xx responses. Surface error.message to the user for context.

code: string

Machine-readable error code identifying the failure reason.

message: string

Human-readable explanation of the failure. May include registry-specific details.

RegistrarSearchResponse { domains }

Contains the search results.

domains: Array<Domain>

Array of domain suggestions sorted by relevance. May be empty if no domains match the search criteria.

name: string

The fully qualified domain name (FQDN) in punycode format for internationalized domain names (IDNs).

registrable: boolean

Indicates whether this domain appears available based on search data. Search results are non-authoritative and may be stale. - true: The domain appears available. Use POST /domain-check to confirm before registration.

false: The domain does not appear available in search results.

pricing?: Pricing { currency, registration_cost, renewal_cost }

Annual pricing information for a registrable domain. This object is only present when registrable is true. All prices are per year and returned as strings to preserve decimal precision.

registration_cost and renewal_cost are frequently the same value, but may differ — especially for premium domains where registries set different rates for initial registration vs. renewal. For a multi-year registration (e.g., 4 years), the first year is charged at registration_cost and each subsequent year at renewal_cost. Registry pricing may change over time; the values returned here reflect the current registry rate. Premium pricing may be surfaced by Search and Check, but premium registration is not currently supported by this API.

currency: string

ISO-4217 currency code for the prices (e.g., “USD”, “EUR”, “GBP”).

registration_cost: string

The first-year cost to register this domain. For premium domains (tier: premium), this price is set by the registry and may be significantly higher than standard pricing. For multi-year registrations, this cost applies to the first year only; subsequent years are charged at renewal_cost.

renewal_cost: string

Per-year renewal cost for this domain. Applied to each year beyond the first year of a multi-year registration, and to each annual auto-renewal thereafter. May differ from registration_cost, especially for premium domains where initial registration often costs more than renewals.

reason?: "extension_not_supported_via_api" | "extension_not_supported" | "extension_disallows_registration" | 2 more

Present only when registrable is false on search results. Explains why the domain does not appear registrable through this API. These values are advisory; use POST /domain-check for authoritative status.

extension_not_supported_via_api: Cloudflare Registrar supports this extension in the dashboard but it is not yet available for programmatic registration via this API.
extension_not_supported: This extension is not supported by Cloudflare Registrar at all.
extension_disallows_registration: The extension’s registry has temporarily or permanently frozen new registrations.
domain_premium: The domain is premium priced. Premium registration is not currently supported by this API.
domain_unavailable: The domain appears unavailable.

One of the following:

"extension_not_supported_via_api"

"extension_not_supported"

"extension_disallows_registration"

"domain_premium"

"domain_unavailable"

tier?: "standard" | "premium"

The pricing tier for this domain. Always present when registrable is true; defaults to standard for most domains. May be absent when registrable is false.

standard: Standard registry pricing
premium: Premium domain with higher pricing set by the registry

One of the following:

"standard"

"premium"

RegistrarCheckResponse { domains }

Contains the availability check results.

domains: Array<Domain>

Array of domain availability results. Domains on unsupported extensions are included with registrable: false and a reason field. Malformed domain names may be omitted.

name: string

The fully qualified domain name (FQDN) in punycode format for internationalized domain names (IDNs).

registrable: boolean

Indicates whether this domain can be registered programmatically through this API based on a real-time registry check.

true: Domain is available for registration. The pricing object will be included.
false: Domain is not available. See the reason field for why. tier may still be present on some non-registrable results, such as premium domains.

pricing?: Pricing { currency, registration_cost, renewal_cost }

Annual pricing information for a registrable domain. This object is only present when registrable is true. All prices are per year and returned as strings to preserve decimal precision.

registration_cost and renewal_cost are frequently the same value, but may differ — especially for premium domains where registries set different rates for initial registration vs. renewal. For a multi-year registration (e.g., 4 years), the first year is charged at registration_cost and each subsequent year at renewal_cost. Registry pricing may change over time; the values returned here reflect the current registry rate. Premium pricing may be surfaced by Search and Check, but premium registration is not currently supported by this API.

currency: string

ISO-4217 currency code for the prices (e.g., “USD”, “EUR”, “GBP”).

registration_cost: string

The first-year cost to register this domain. For premium domains (tier: premium), this price is set by the registry and may be significantly higher than standard pricing. For multi-year registrations, this cost applies to the first year only; subsequent years are charged at renewal_cost.

renewal_cost: string

Per-year renewal cost for this domain. Applied to each year beyond the first year of a multi-year registration, and to each annual auto-renewal thereafter. May differ from registration_cost, especially for premium domains where initial registration often costs more than renewals.

reason?: "extension_not_supported_via_api" | "extension_not_supported" | "extension_disallows_registration" | 2 more

Present only when registrable is false. Explains why the domain cannot be registered via this API.

extension_not_supported_via_api: Cloudflare Registrar supports this extension in the dashboard but it is not yet available for programmatic registration via this API. The user can register via https://dash.cloudflare.com/{account_id}/domains/registrations.
extension_not_supported: This extension is not supported by Cloudflare Registrar at all.
extension_disallows_registration: The extension’s registry has temporarily or permanently frozen new registrations. No registrar can register domains on this extension at this time.
domain_premium: The domain is premium priced. Premium registration is not currently supported by this API.
domain_unavailable: The domain is already registered, reserved, or otherwise not available on a supported extension.

One of the following:

"extension_not_supported_via_api"

"extension_not_supported"

"extension_disallows_registration"

"domain_premium"

"domain_unavailable"

tier?: "standard" | "premium"

The pricing tier for this domain. Always present when registrable is true; defaults to standard for most domains. May be absent when registrable is false.

standard: Standard registry pricing
premium: Premium domain with higher pricing set by the registry

One of the following:

"standard"

"premium"

RegistrarDomains

List domains

Deprecated

client.registrar.domains.list(?, ?): SinglePage<Domain { id, available, can_register, 9 more } >

GET/accounts/{account_id}/registrar/domains

Get domain

Deprecated

client.registrar.domains.get(, ?, ?): DomainGetResponse | null

GET/accounts/{account_id}/registrar/domains/{domain_name}

Update domain

Deprecated

client.registrar.domains.update(, , ?): DomainUpdateResponse | null

PUT/accounts/{account_id}/registrar/domains/{domain_name}

ModelsExpand Collapse

Domain { id, available, can_register, 9 more }

id?: string

Domain identifier.

maxLength32

available?: boolean

Shows if a domain is available for transferring into Cloudflare Registrar.

can_register?: boolean

Indicates if the domain can be registered as a new domain.

created_at?: string

Shows time of creation.

formatdate-time

current_registrar?: string

Shows name of current registrar.

expires_at?: string

Shows when domain name registration expires.

formatdate-time

locked?: boolean

Shows whether a registrar lock is in place for a domain.

registrant_contact?: RegistrantContact { address, city, country, 10 more }

Shows contact information for domain registrant.

address: string

Address.

city: string

City.

country: string | null

The country in which the user lives.

maxLength30

first_name: string | null

User’s first name

maxLength60

last_name: string | null

User’s last name

maxLength60

organization: string

Name of organization.

phone: string | null

User’s telephone number

maxLength20

state: string

State.

zip: string | null

The zipcode or postal code where the user lives.

maxLength20

id?: string

Contact Identifier.

maxLength32

address2?: string

Optional address line for unit, floor, suite, etc.

email?: string

The contact email address of the user.

maxLength90

fax?: string

Contact fax number.

registry_statuses?: string

A comma-separated list of registry status codes. A full list of status codes can be found at EPP Status Codes.

supported_tld?: boolean

Whether a particular TLD is currently supported by Cloudflare Registrar. Refer to TLD Policies for a list of supported TLDs.

transfer_in?: TransferIn { accept_foa, approve_transfer, can_cancel_transfer, 3 more }

Statuses for domain transfers into Cloudflare Registrar.

accept_foa?: "needed" | "ok"

Form of authorization has been accepted by the registrant.

One of the following:

"needed"

"ok"

approve_transfer?: "needed" | "ok" | "pending" | 3 more

Shows transfer status with the registry.

One of the following:

"needed"

"ok"

"pending"

"trying"

"rejected"

"unknown"

can_cancel_transfer?: boolean

Indicates if cancellation is still possible.

disable_privacy?: "needed" | "ok" | "unknown"

Privacy guards are disabled at the foreign registrar.

One of the following:

"needed"

"ok"

"unknown"

enter_auth_code?: "needed" | "ok" | "pending" | 2 more

Auth code has been entered and verified.

One of the following:

"needed"

"ok"

"pending"

"trying"

"rejected"

unlock_domain?: "needed" | "ok" | "pending" | 2 more

Domain is unlocked at the foreign registrar.

One of the following:

"needed"

"ok"

"pending"

"trying"

"unknown"

updated_at?: string

Last updated.

formatdate-time

DomainGetResponse = unknown

DomainUpdateResponse = unknown

RegistrarRegistrations

RegistrarRegistration Status

Get Registration Status

client.registrar.registrationStatus.get(, ?, ?): WorkflowStatus { completed, created_at, links, 4 more }

GET/accounts/{account_id}/registrar/registrations/{domain_name}/registration-status

RegistrarUpdate Status

Get Update Status

client.registrar.updateStatus.get(, ?, ?): WorkflowStatus { completed, created_at, links, 4 more }

GET/accounts/{account_id}/registrar/registrations/{domain_name}/update-status