--- title: Registrar --- [Skip to content](#_top) [API Reference](https://developers.cloudflare.com/api/go) Copy Markdown Open in **Claude**Open in **ChatGPT**Open in **Cursor** --- **Copy Markdown****View as Markdown** # 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](https://developers.cloudflare.com/api/go/resources/registrar/methods/search) client.Registrar.Search(ctx, params) (\*[RegistrarSearchResponse](), error) GET/accounts/{account\_id}/registrar/domain-search ##### [Check domain availability](https://developers.cloudflare.com/api/go/resources/registrar/methods/check) client.Registrar.Check(ctx, params) (\*[RegistrarCheckResponse](), error) POST/accounts/{account\_id}/registrar/domain-check ##### [Check domain transfer eligibility](https://developers.cloudflare.com/api/go/resources/registrar/methods/transfer_check) client.Registrar.TransferCheck(ctx, params) (\*[RegistrarTransferCheckResponse](), error) POST/accounts/{account\_id}/registrar/domain-transfer-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. Link to this property CreatedAt Time When the domain was registered. Present when the registration resource exists. formatdate-time Link to this property 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. Link to this property ExpiresAt Time When the domain registration expires. Ready registrations include this value; only registration_pending and transfer_pending may return null. formatdate-time Link to this property Locked bool Whether the domain is locked for transfer. Link to this property
PrivacyMode RegistrationPrivacyMode Current WHOIS privacy mode for the registration. One of the following: const RegistrationPrivacyModeOff RegistrationPrivacyMode = "off" Link to this property const RegistrationPrivacyModeRedaction RegistrationPrivacyMode = "redaction" Link to this property
Link to this property
Status RegistrationStatus Current registration status. - active: The domain operates with an active registration. - registration_pending: Registration remains in progress. - transfer_pending: Domain transfer is 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" Link to this property const RegistrationStatusRegistrationPending RegistrationStatus = "registration\_pending" Link to this property const RegistrationStatusTransferPending RegistrationStatus = "transfer\_pending" Link to this property const RegistrationStatusExpired RegistrationStatus = "expired" Link to this property const RegistrationStatusSuspended RegistrationStatus = "suspended" Link to this property const RegistrationStatusRedemptionPeriod RegistrationStatus = "redemption\_period" Link to this property const RegistrationStatusPendingDelete RegistrationStatus = "pending\_delete" Link to this property
Link to this property
[Link to this property](<#(resource)%20registrar%20%3E%20(model)%20registration%20%3E%20(schema)>)
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. Link to this property CreatedAt Time formatdate-time Link to this property
Links WorkflowStatusLinks Self string URL to this status resource. Link to this property Resource stringOptional URL to the domain resource. Link to this property
Link to this property
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" Link to this property const WorkflowStatusStateInProgress WorkflowStatusState = "in\_progress" Link to this property const WorkflowStatusStateActionRequired WorkflowStatusState = "action\_required" Link to this property const WorkflowStatusStateBlocked WorkflowStatusState = "blocked" Link to this property const WorkflowStatusStateSucceeded WorkflowStatusState = "succeeded" Link to this property const WorkflowStatusStateFailed WorkflowStatusState = "failed" Link to this property
Link to this property UpdatedAt Time formatdate-time Link to this property Context map\[string, unknown]Optional Provides workflow-specific data. For domain-centric workflows, context.domain_name identifies the workflow subject. Link to this property
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. Link to this property Message string Human-readable explanation of the failure. May include registry-specific details. Link to this property
Link to this property
[Link to this property](<#(resource)%20registrar%20%3E%20(model)%20workflow_status%20%3E%20(schema)>) #### RegistrarDomains ##### [List domains](https://developers.cloudflare.com/api/go/resources/registrar/subresources/domains/methods/list) Deprecated client.Registrar.Domains.List(ctx, query) (\*SinglePage\[[Domain]()], error) GET/accounts/{account\_id}/registrar/domains ##### [Get domain](https://developers.cloudflare.com/api/go/resources/registrar/subresources/domains/methods/get) Deprecated client.Registrar.Domains.Get(ctx, domainName, query) (\*[DomainGetResponse](), error) GET/accounts/{account\_id}/registrar/domains/{domain\_name} ##### [Update domain](https://developers.cloudflare.com/api/go/resources/registrar/subresources/domains/methods/update) Deprecated client.Registrar.Domains.Update(ctx, domainName, params) (\*[DomainUpdateResponse](), error) PUT/accounts/{account\_id}/registrar/domains/{domain\_name} ##### ModelsExpand Collapse
type Domain struct{…} ID stringOptional Domain identifier. maxLength32 Link to this property Available boolOptional Shows if a domain is available for transferring into Cloudflare Registrar. Link to this property CanRegister boolOptional Indicates eligibility to register the domain as a new domain. Link to this property CreatedAt TimeOptional Shows time of creation. formatdate-time Link to this property CurrentRegistrar stringOptional Shows name of current registrar. Link to this property ExpiresAt TimeOptional Shows when domain name registration expires. formatdate-time Link to this property Locked boolOptional Shows whether a registrar lock is in place for a domain. Link to this property
RegistrantContact DomainRegistrantContactOptional Shows contact information for domain registrant. Address string Address. Link to this property City string City. Link to this property Country string The country in which the user lives. maxLength30 Link to this property FirstName string User’s first name. maxLength60 Link to this property LastName string User’s last name. maxLength60 Link to this property Organization string Name of organization. Link to this property Phone string User’s telephone number. maxLength20 Link to this property State string State. Link to this property Zip string The zipcode or postal code where the user lives. maxLength20 Link to this property ID stringOptional Contact Identifier. maxLength32 Link to this property Address2 stringOptional Optional address line for unit, floor, suite, etc. Link to this property Email stringOptional The contact email address of the user. maxLength90 Link to this property Fax stringOptional Contact fax number. Link to this property
Link to this property RegistryStatuses stringOptional A comma-separated list of registry status codes. Refer to EPP Status Codes for the full list. Link to this property SupportedTLD boolOptional Indicates whether Cloudflare Registrar currently supports a particular TLD. Refer to TLD Policies for a list of supported TLDs. Link to this property
TransferIn DomainTransferInOptional Statuses for domain transfers into Cloudflare Registrar.
AcceptFoa DomainTransferInAcceptFoaOptional Status of the registrant authorization step. One of the following: const DomainTransferInAcceptFoaNeeded DomainTransferInAcceptFoa = "needed" Link to this property const DomainTransferInAcceptFoaOk DomainTransferInAcceptFoa = "ok" Link to this property
Link to this property
ApproveTransfer DomainTransferInApproveTransferOptional Status of the registry transfer-approval step. One of the following: const DomainTransferInApproveTransferNeeded DomainTransferInApproveTransfer = "needed" Link to this property const DomainTransferInApproveTransferOk DomainTransferInApproveTransfer = "ok" Link to this property const DomainTransferInApproveTransferPending DomainTransferInApproveTransfer = "pending" Link to this property const DomainTransferInApproveTransferTrying DomainTransferInApproveTransfer = "trying" Link to this property const DomainTransferInApproveTransferRejected DomainTransferInApproveTransfer = "rejected" Link to this property const DomainTransferInApproveTransferUnknown DomainTransferInApproveTransfer = "unknown" Link to this property
Link to this property CanCancelTransfer boolOptional Indicates if cancellation is still possible. Link to this property
DisablePrivacy DomainTransferInDisablePrivacyOptional Status of the privacy-guard disabling step at the foreign registrar. One of the following: const DomainTransferInDisablePrivacyNeeded DomainTransferInDisablePrivacy = "needed" Link to this property const DomainTransferInDisablePrivacyOk DomainTransferInDisablePrivacy = "ok" Link to this property const DomainTransferInDisablePrivacyUnknown DomainTransferInDisablePrivacy = "unknown" Link to this property
Link to this property
EnterAuthCode DomainTransferInEnterAuthCodeOptional Status of the auth-code entry and verification step. One of the following: const DomainTransferInEnterAuthCodeNeeded DomainTransferInEnterAuthCode = "needed" Link to this property const DomainTransferInEnterAuthCodeOk DomainTransferInEnterAuthCode = "ok" Link to this property const DomainTransferInEnterAuthCodePending DomainTransferInEnterAuthCode = "pending" Link to this property const DomainTransferInEnterAuthCodeTrying DomainTransferInEnterAuthCode = "trying" Link to this property const DomainTransferInEnterAuthCodeRejected DomainTransferInEnterAuthCode = "rejected" Link to this property
Link to this property
UnlockDomain DomainTransferInUnlockDomainOptional Status of the domain-unlock step at the foreign registrar. One of the following: const DomainTransferInUnlockDomainNeeded DomainTransferInUnlockDomain = "needed" Link to this property const DomainTransferInUnlockDomainOk DomainTransferInUnlockDomain = "ok" Link to this property const DomainTransferInUnlockDomainPending DomainTransferInUnlockDomain = "pending" Link to this property const DomainTransferInUnlockDomainTrying DomainTransferInUnlockDomain = "trying" Link to this property const DomainTransferInUnlockDomainUnknown DomainTransferInUnlockDomain = "unknown" Link to this property
Link to this property
Link to this property UpdatedAt TimeOptional Last updated. formatdate-time Link to this property
[Link to this property](<#(resource)%20registrar.domains%20%3E%20(model)%20domain%20%3E%20(schema)>) #### RegistrarRegistrations ##### [Create Registration](https://developers.cloudflare.com/api/go/resources/registrar/subresources/registrations/methods/create) client.Registrar.Registrations.New(ctx, params) (\*[WorkflowStatus](), error) POST/accounts/{account\_id}/registrar/registrations ##### [List Registrations](https://developers.cloudflare.com/api/go/resources/registrar/subresources/registrations/methods/list) client.Registrar.Registrations.List(ctx, params) (\*CursorPagination\[[Registration]()], error) GET/accounts/{account\_id}/registrar/registrations ##### [Get Registration](https://developers.cloudflare.com/api/go/resources/registrar/subresources/registrations/methods/get) client.Registrar.Registrations.Get(ctx, domainName, query) (\*[Registration](), error) GET/accounts/{account\_id}/registrar/registrations/{domain\_name} ##### [Update Registration](https://developers.cloudflare.com/api/go/resources/registrar/subresources/registrations/methods/edit) client.Registrar.Registrations.Edit(ctx, domainName, params) (\*[WorkflowStatus](), error) PATCH/accounts/{account\_id}/registrar/registrations/{domain\_name} #### RegistrarRegistration Status ##### [Get Registration Status](https://developers.cloudflare.com/api/go/resources/registrar/subresources/registration_status/methods/get) client.Registrar.RegistrationStatus.Get(ctx, domainName, query) (\*[WorkflowStatus](), error) GET/accounts/{account\_id}/registrar/registrations/{domain\_name}/registration-status #### RegistrarUpdate Status ##### [Get Update Status](https://developers.cloudflare.com/api/go/resources/registrar/subresources/update_status/methods/get) client.Registrar.UpdateStatus.Get(ctx, domainName, query) (\*[WorkflowStatus](), error) GET/accounts/{account\_id}/registrar/registrations/{domain\_name}/update-status #### RegistrarExtensions ##### [List extensions](https://developers.cloudflare.com/api/go/resources/registrar/subresources/extensions/methods/list) client.Registrar.Extensions.List(ctx, params) (\*CursorPagination\[[ExtensionListResponse]()], error) GET/accounts/{account\_id}/registrar/extensions ##### [Get extension](https://developers.cloudflare.com/api/go/resources/registrar/subresources/extensions/methods/get) client.Registrar.Extensions.Get(ctx, extension, query) (\*[ExtensionGetResponse](), error) GET/accounts/{account\_id}/registrar/extensions/{extension} #### RegistrarTransfer In ##### [Initiate Transfer](https://developers.cloudflare.com/api/go/resources/registrar/subresources/transfer_in/methods/create) client.Registrar.TransferIn.New(ctx, domainName, params) (\*[WorkflowStatus](), error) POST/accounts/{account\_id}/registrar/registrations/{domain\_name}/transfer-in #### RegistrarTransfer In Status ##### [Get Transfer Status](https://developers.cloudflare.com/api/go/resources/registrar/subresources/transfer_in_status/methods/get) client.Registrar.TransferInStatus.Get(ctx, domainName, query) (\*[WorkflowStatus](), error) GET/accounts/{account\_id}/registrar/registrations/{domain\_name}/transfer-in-status