Skip to content
Cloudflare API
Start here
API Reference

Registrar

Registrar API for searching, checking, registering, and managing domains through Cloudflare Registrar.

Prerequisites

Before using this API, ensure:

  1. Cloudflare account — the caller must have a valid Cloudflare account.
  2. Billing profile — the account must have a billing profile with a valid, current default payment method (credit card or other accepted method). This cannot be set up via API — the account owner must configure billing at https://dash.cloudflare.com/{account_id}/billing/payment-info before calling POST /registrations.
  3. API authentication — use an API token or API key with the appropriate Registrar permissions for the operations you are calling.

Terminology: domain extension

Throughout this API, “extension” refers to the domain extension part of a fully qualified domain name — the portion after the registrable label. For example, in example.co.uk, the extension is co.uk (not just uk). This covers both top-level domains like com and multi-level extensions like co.uk. This is distinct from other uses of the word “extension” (e.g., EPP extensions).

Supported extensions

This API supports programmatic registration for all extensions supported by the dashboard experience, with the following exceptions:

giving, mom, inc, lol, sh, link, cc, new

Cloudflare Registrar supports 400+ extensions in the dashboard. Extensions listed above can be registered at https://dash.cloudflare.com/{account_id}/domains/registrations.

Typical workflow

  1. Search — call GET /domain-search?q={keyword} to discover available domains.
  2. Check — call POST /domain-check with candidate domains to verify real-time availability and pricing.
  3. Review the response — if registrable: false, inspect reason to understand whether the domain is unavailable, the extension is not supported by this API, the extension is not supported by Cloudflare Registrar at all, or the extension’s registry has frozen new registrations.
  4. Handle premium domains — if tier: premium, premium registration is not currently supported by this API. Surface the premium pricing to the user, but do not proceed to POST /registrations for that domain.
  5. Observe the registration schema — call GET /extensions/:extension_name to discover the required values for registering this extension.
  6. Register — call POST /registrations with the chosen domain name for supported non-premium registrations.
  7. Confirm completion — if the response is 201 Created, registration completed within the default timeout and no polling is needed.
  8. Poll when needed — if the response is 202 Accepted, poll links.self from the workflow response.
  9. Stop for user action — if state: action_required, stop polling and surface context.action to the user. The workflow will not resolve on its own.
  10. Continue when blocked — if state: blocked, continue polling and inform the user that a third party, such as the extension registry or losing registrar, is delaying progress.
  11. Review failures before retrying — if state: failed, review error.code and error.message, then decide whether user action or a new Check call is needed.

All successful domain registrations are non-refundable. Once the registration workflow completes with state: succeeded, the charge cannot be reversed. Confirm pricing and domain choice with the user before calling POST /registrations.

Default behavior for mutating operations

By default, mutating operations such as create and update hold the connection for a bounded, server-defined amount of time while the operation completes. In most cases, the response contains a completed workflow status and no polling is required.

  • Completed within the synchronous wait window: Returns 201 (create) or 200 (update) with a workflow_status where state: succeeded and completed: true.
  • Still processing after the synchronous wait window: Returns 202 Accepted with a workflow_status where completed: false. Use the links.self URL to poll for completion.

Non-blocking mode

To receive an immediate 202 Accepted response without waiting, send the Prefer: respond-async request header (RFC 7240). The server will acknowledge it with a Preference-Applied: respond-async response header.

Polling

When the response is 202, poll the workflow status endpoint indicated by links.self in the response body until the workflow reaches a terminal state or requires user action.

Search for available domains
registrar.search(RegistrarSearchParams**kwargs) -> RegistrarSearchResponse
GET/accounts/{account_id}/registrar/domain-search
Check domain availability
registrar.check(RegistrarCheckParams**kwargs) -> RegistrarCheckResponse
POST/accounts/{account_id}/registrar/domain-check
ModelsExpand Collapse
class Registration: …

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

auto_renew: bool

Whether automatic renewal occurs before expiration.

created_at: datetime

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

formatdate-time
domain_name: str

Provides a fully qualified domain name (FQDN), including the extension (e.g., example.com, mybrand.app). The domain name uniquely identifies a registration. Cloudflare permits only one registration per domain, making the domain name a natural idempotency key for registration requests.

expires_at: Optional[datetime]

When the domain registration expires. Ready registrations include this value; only registration_pending may return null.

formatdate-time
locked: bool

Whether the domain is locked for transfer.

privacy_mode: Literal["off", "redaction"]

Current WHOIS privacy mode for the registration.

One of the following:
"off"
"redaction"
status: Literal["active", "registration_pending", "expired", 3 more]

Current registration status.

  • active: The domain operates with an active registration.
  • registration_pending: Registration remains in progress.
  • expired: The domain registration expired.
  • suspended: The registry suspended the domain.
  • redemption_period: The domain entered the redemption grace period.
  • pending_delete: The registry scheduled the domain for deletion.
One of the following:
"active"
"registration_pending"
"expired"
"suspended"
"redemption_period"
"pending_delete"
class WorkflowStatus: …

Status of an async registration workflow.

completed: bool

Indicates whether the workflow reached a terminal state. A succeeded or failed state returns true; pending, in_progress, action_required, and blocked return false.

created_at: datetime
formatdate-time
state: Literal["pending", "in_progress", "action_required", 3 more]

Describes the workflow lifecycle state.

  • pending: The workflow awaits processing.
  • in_progress: Processing started. Continue polling links.self. An internal deadline limits the duration of this state.
  • action_required: The workflow pauses for user action. See context.action for details. Stop automated polling until the user completes the required action.
  • blocked: A third party, such as the domain extension’s registry or a losing registrar, prevents progress. Continue polling because the block may resolve when the third party responds.
  • succeeded: Terminal state. The operation completed successfully. completed equals true. For registrations, context.registration contains the resulting registration resource.
  • failed: Terminal state. The operation failed. completed equals true. See error.code and error.message for the reason. Require user review before retrying.
One of the following:
"pending"
"in_progress"
"action_required"
"blocked"
"succeeded"
"failed"
updated_at: datetime
formatdate-time
context: Optional[Dict[str, object]]

Provides workflow-specific data.

For domain-centric workflows, context.domain_name identifies the workflow subject.

error: Optional[Error]

Provides error details when a workflow reaches the failed state. The workflow type (registration, update, etc.) and underlying registry response determine the specific codes and messages. Workflow error codes differ from immediate HTTP error errors[].code values in non-2xx responses. Surface error.message to the user for context.

code: str

Machine-readable error code identifying the failure reason.

message: str

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

class RegistrarSearchResponse: …

Contains the search results.

domains: List[Domain]

Lists domain suggestions in relevance order. An empty array indicates that the search criteria matched zero domains.

name: str

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

registrable: bool

Indicates domain availability according to potentially stale, non-authoritative search data.

  • true: The domain appears available. Use POST /domain-check to confirm before registration.
  • false: Search results mark the domain ineligible for registration through this API. See reason for details.
pricing: Optional[DomainPricing]

Provides annual pricing information for a registrable domain. This object appears only when registrable is true. The API returns all per-year prices as strings to preserve decimal precision.

registration_cost and renewal_cost frequently have the same value, but may differ, especially when registries set different premium rates for initial registration and renewal. For a multi-year registration (e.g., 4 years), registration_cost applies to the first year and renewal_cost applies to each subsequent year. The values reflect the current registry rate, which may change over time. Search and Check may surface premium pricing, but this API currently supports standard registrations only.

currency: str

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

registration_cost: str

The first-year cost to register this domain. For premium domains (tier: premium), the registry sets this price, which may significantly exceed standard pricing. For multi-year registrations, this cost applies to the first year only; renewal_cost applies to subsequent years.

renewal_cost: str

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: Optional[Literal["extension_not_supported_via_api", "extension_not_supported", "extension_disallows_registration", 2 more]]

Appears only when registrable is false and explains the advisory search result. Use POST /domain-check for authoritative status.

  • extension_not_supported_via_api: Cloudflare Registrar supports this extension in the dashboard but currently excludes it from programmatic registration through this API.
  • extension_not_supported: Cloudflare Registrar excludes this extension entirely.
  • extension_disallows_registration: The extension’s registry temporarily or permanently freezes new registrations.
  • domain_premium: The domain carries premium pricing. This API currently supports standard registrations only.
  • 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: Optional[Literal["standard", "premium"]]

The pricing tier for this domain. A registrable value of true always includes this field, which defaults to standard for most domains. A registrable value of false may omit it.

  • standard: Standard registry pricing.
  • premium: Premium domain with higher pricing from the registry.
One of the following:
"standard"
"premium"
class RegistrarCheckResponse: …

Contains the availability check results.

domains: List[Domain]

Array of domain availability results. Results for unsupported extensions contain registrable: false and a reason field. The response may omit malformed domain names.

name: str

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

registrable: bool

Indicates programmatic registration eligibility according to a real-time registry check.

  • true: The domain is available for registration. The response includes the pricing object.
  • false: A restriction prevents registration. See the reason field for details. Some results, such as premium domains, may still include tier.
pricing: Optional[DomainPricing]

Provides annual pricing information for a registrable domain. This object appears only when registrable is true. The API returns all per-year prices as strings to preserve decimal precision.

registration_cost and renewal_cost frequently have the same value, but may differ, especially when registries set different premium rates for initial registration and renewal. For a multi-year registration (e.g., 4 years), registration_cost applies to the first year and renewal_cost applies to each subsequent year. The values reflect the current registry rate, which may change over time. Search and Check may surface premium pricing, but this API currently supports standard registrations only.

currency: str

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

registration_cost: str

The first-year cost to register this domain. For premium domains (tier: premium), the registry sets this price, which may significantly exceed standard pricing. For multi-year registrations, this cost applies to the first year only; renewal_cost applies to subsequent years.

renewal_cost: str

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: Optional[Literal["extension_not_supported_via_api", "extension_not_supported", "extension_disallows_registration", 2 more]]

Appears only when registrable is false and explains the result.

  • extension_not_supported_via_api: Cloudflare Registrar supports this extension in the dashboard but currently excludes it from programmatic registration through this API. The user can register via https://dash.cloudflare.com/{account_id}/domains/registrations.
  • extension_not_supported: Cloudflare Registrar excludes this extension entirely.
  • extension_disallows_registration: The extension’s registry temporarily or permanently freezes new registrations. Registrars currently cannot register domains on this extension.
  • domain_premium: The domain carries premium pricing. This API currently supports standard registrations only.
  • domain_unavailable: An existing registration, reservation, or other registry restriction makes the domain unavailable on a supported extension.
One of the following:
"extension_not_supported_via_api"
"extension_not_supported"
"extension_disallows_registration"
"domain_premium"
"domain_unavailable"
tier: Optional[Literal["standard", "premium"]]

The pricing tier for this domain. A registrable value of true always includes this field, which defaults to standard for most domains. A registrable value of false may omit it.

  • standard: Standard registry pricing.
  • premium: Premium domain with higher pricing from the registry.
One of the following:
"standard"
"premium"

RegistrarDomains

List domains
Deprecated
registrar.domains.list(DomainListParams**kwargs) -> SyncSinglePage[Domain]
GET/accounts/{account_id}/registrar/domains
Get domain
Deprecated
registrar.domains.get(strdomain_name, DomainGetParams**kwargs) -> object
GET/accounts/{account_id}/registrar/domains/{domain_name}
Update domain
Deprecated
registrar.domains.update(strdomain_name, DomainUpdateParams**kwargs) -> object
PUT/accounts/{account_id}/registrar/domains/{domain_name}
ModelsExpand Collapse
class Domain: …
id: Optional[str]

Domain identifier.

maxLength32
available: Optional[bool]

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

can_register: Optional[bool]

Indicates eligibility to register the domain as a new domain.

created_at: Optional[datetime]

Shows time of creation.

formatdate-time
current_registrar: Optional[str]

Shows name of current registrar.

expires_at: Optional[datetime]

Shows when domain name registration expires.

formatdate-time
locked: Optional[bool]

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

registrant_contact: Optional[RegistrantContact]

Shows contact information for domain registrant.

address: str

Address.

city: str

City.

country: Optional[str]

The country in which the user lives.

maxLength30
first_name: Optional[str]

User’s first name.

maxLength60
last_name: Optional[str]

User’s last name.

maxLength60
organization: str

Name of organization.

phone: Optional[str]

User’s telephone number.

maxLength20
state: str

State.

zip: Optional[str]

The zipcode or postal code where the user lives.

maxLength20
id: Optional[str]

Contact Identifier.

maxLength32
address2: Optional[str]

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

email: Optional[str]

The contact email address of the user.

maxLength90
fax: Optional[str]

Contact fax number.

registry_statuses: Optional[str]

A comma-separated list of registry status codes. Refer to EPP Status Codes for the full list.

supported_tld: Optional[bool]

Indicates whether Cloudflare Registrar currently supports a particular TLD. Refer to TLD Policies for a list of supported TLDs.

transfer_in: Optional[TransferIn]

Statuses for domain transfers into Cloudflare Registrar.

accept_foa: Optional[Literal["needed", "ok"]]

Status of the registrant authorization step.

One of the following:
"needed"
"ok"
approve_transfer: Optional[Literal["needed", "ok", "pending", 3 more]]

Status of the registry transfer-approval step.

One of the following:
"needed"
"ok"
"pending"
"trying"
"rejected"
"unknown"
can_cancel_transfer: Optional[bool]

Indicates if cancellation is still possible.

disable_privacy: Optional[Literal["needed", "ok", "unknown"]]

Status of the privacy-guard disabling step at the foreign registrar.

One of the following:
"needed"
"ok"
"unknown"
enter_auth_code: Optional[Literal["needed", "ok", "pending", 2 more]]

Status of the auth-code entry and verification step.

One of the following:
"needed"
"ok"
"pending"
"trying"
"rejected"
unlock_domain: Optional[Literal["needed", "ok", "pending", 2 more]]

Status of the domain-unlock step at the foreign registrar.

One of the following:
"needed"
"ok"
"pending"
"trying"
"unknown"
updated_at: Optional[datetime]

Last updated.

formatdate-time

RegistrarRegistrations

Create Registration
registrar.registrations.create(RegistrationCreateParams**kwargs) -> WorkflowStatus
POST/accounts/{account_id}/registrar/registrations
List Registrations
registrar.registrations.list(RegistrationListParams**kwargs) -> SyncCursorPagination[Registration]
GET/accounts/{account_id}/registrar/registrations
Get Registration
registrar.registrations.get(strdomain_name, RegistrationGetParams**kwargs) -> Registration
GET/accounts/{account_id}/registrar/registrations/{domain_name}
Update Registration
registrar.registrations.edit(strdomain_name, RegistrationEditParams**kwargs) -> WorkflowStatus
PATCH/accounts/{account_id}/registrar/registrations/{domain_name}

RegistrarRegistration Status

Get Registration Status
registrar.registration_status.get(strdomain_name, RegistrationStatusGetParams**kwargs) -> WorkflowStatus
GET/accounts/{account_id}/registrar/registrations/{domain_name}/registration-status

RegistrarUpdate Status

Get Update Status
registrar.update_status.get(strdomain_name, UpdateStatusGetParams**kwargs) -> WorkflowStatus
GET/accounts/{account_id}/registrar/registrations/{domain_name}/update-status

RegistrarExtensions

List extensions
registrar.extensions.list(ExtensionListParams**kwargs) -> SyncCursorPagination[ExtensionListResponse]
GET/accounts/{account_id}/registrar/extensions
Get extension
registrar.extensions.get(strextension, ExtensionGetParams**kwargs) -> ExtensionGetResponse
GET/accounts/{account_id}/registrar/extensions/{extension}
ModelsExpand Collapse
class ExtensionListResponse: …

Extension entry with metadata and JSON Schema documents for the registration operation.

metadata: Metadata

Extension metadata.

name: str

The full name of the extension. For example, “co.uk”, or “uk”.

tld: str

The TLD of the extension. For example, for “co.uk”, it is “uk”. For “uk”, it is “uk”.

registration_schema: object

JSON Schema describing the expected input structure for registration operations on this extension.

class ExtensionGetResponse: …

Extension entry with metadata and JSON Schema documents for the registration operation.

metadata: Metadata

Extension metadata.

name: str

The full name of the extension. For example, “co.uk”, or “uk”.

tld: str

The TLD of the extension. For example, for “co.uk”, it is “uk”. For “uk”, it is “uk”.

registration_schema: object

JSON Schema describing the expected input structure for registration operations on this extension.