Skip to content
Cloudflare API
Start here
API Reference

Registrar Sandbox

Use the Registrar Sandbox API to test domain search, availability checks, registration, and domain management flows without buying real domains.

This API is a test environment for the production Registrar API.

Prerequisites

Before using this API, make sure you have:

  1. Cloudflare account — the caller must have a valid Cloudflare account.
  2. API authentication — create an API token with Registrar Sandbox permissions.

How the Sandbox API differs from the production Registrar API

Because the Sandbox API is intended for testing, it behaves differently from the production Registrar API in a few important ways:

  1. No billing — you will not be charged real money for purchasing a domain.
  2. No real domains — purchased domains are test records and will not be reachable on the Internet.
  3. No DNS zones — purchasing a domain does not create a zone resource.
  4. No Registration Express Mode — you must provide full contact data.

Sandbox purchases are still persisted. If you purchase a domain in the sandbox, that domain will not be available for others to purchase in the sandbox.

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

The Sandbox API currently supports programmatic registration for these extensions:

com, net

The production Registrar API supports 40+ extensions.

Cloudflare Registrar supports 400+ extensions in the dashboard. Extensions not 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. The Sandbox API currently supports only com and net, which do not have premium registrations, but clients should still handle this response for consistency with the production Registrar 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.

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
client.RegistrarSandbox.Search(ctx, params) (*RegistrarSandboxSearchResponse, error)
GET/accounts/{account_id}/registrar-sandbox/domain-search
Check domain availability
client.RegistrarSandbox.Check(ctx, params) (*RegistrarSandboxCheckResponse, error)
POST/accounts/{account_id}/registrar-sandbox/domain-check
ModelsExpand Collapse
type Registration struct{…}

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

AutoRenew bool

Whether automatic renewal occurs before expiration.

CreatedAt Time

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

formatdate-time
DomainName string

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.

ExpiresAt Time

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.

PrivacyMode RegistrationPrivacyMode

Current WHOIS privacy mode for the registration.

One of the following:
const RegistrationPrivacyModeOff RegistrationPrivacyMode = "off"
const RegistrationPrivacyModeRedaction RegistrationPrivacyMode = "redaction"
Status RegistrationStatus

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:
const RegistrationStatusActive RegistrationStatus = "active"
const RegistrationStatusRegistrationPending RegistrationStatus = "registration_pending"
const RegistrationStatusExpired RegistrationStatus = "expired"
const RegistrationStatusSuspended RegistrationStatus = "suspended"
const RegistrationStatusRedemptionPeriod RegistrationStatus = "redemption_period"
const RegistrationStatusPendingDelete RegistrationStatus = "pending_delete"
type WorkflowStatus struct{…}

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.

CreatedAt Time
formatdate-time
State WorkflowStatusState

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:
const WorkflowStatusStatePending WorkflowStatusState = "pending"
const WorkflowStatusStateInProgress WorkflowStatusState = "in_progress"
const WorkflowStatusStateActionRequired WorkflowStatusState = "action_required"
const WorkflowStatusStateBlocked WorkflowStatusState = "blocked"
const WorkflowStatusStateSucceeded WorkflowStatusState = "succeeded"
const WorkflowStatusStateFailed WorkflowStatusState = "failed"
UpdatedAt Time
formatdate-time
Context map[string, unknown]Optional

Provides workflow-specific data.

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

Error WorkflowStatusErrorOptional

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 string

Machine-readable error code identifying the failure reason.

Message string

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

Registrar SandboxRegistrations

Create Registration
client.RegistrarSandbox.Registrations.New(ctx, params) (*RegistrationNewResponse, error)
POST/accounts/{account_id}/registrar-sandbox/registrations
List Registrations
client.RegistrarSandbox.Registrations.List(ctx, params) (*CursorPagination[RegistrationListResponse], error)
GET/accounts/{account_id}/registrar-sandbox/registrations
Get Registration
client.RegistrarSandbox.Registrations.Get(ctx, domainName, query) (*RegistrationGetResponse, error)
GET/accounts/{account_id}/registrar-sandbox/registrations/{domain_name}
Update Registration
client.RegistrarSandbox.Registrations.Edit(ctx, domainName, params) (*RegistrationEditResponse, error)
PATCH/accounts/{account_id}/registrar-sandbox/registrations/{domain_name}

Registrar SandboxRegistration Status

Get Registration Status
client.RegistrarSandbox.RegistrationStatus.Get(ctx, domainName, query) (*RegistrationStatusGetResponse, error)
GET/accounts/{account_id}/registrar-sandbox/registrations/{domain_name}/registration-status

Registrar SandboxUpdate Status

Get Update Status
client.RegistrarSandbox.UpdateStatus.Get(ctx, domainName, query) (*UpdateStatusGetResponse, error)
GET/accounts/{account_id}/registrar-sandbox/registrations/{domain_name}/update-status

Registrar SandboxExtensions

List extensions
client.RegistrarSandbox.Extensions.List(ctx, params) (*CursorPagination[ExtensionListResponse], error)
GET/accounts/{account_id}/registrar-sandbox/extensions
Get extension
client.RegistrarSandbox.Extensions.Get(ctx, extension, query) (*ExtensionGetResponse, error)
GET/accounts/{account_id}/registrar-sandbox/extensions/{extension}