---
title: Create Registration
---

[Skip to content](#%5Ftop) 

[API Reference](https://developers.cloudflare.com/api/python)

[Registrar Sandbox](https://developers.cloudflare.com/api/python/resources/registrar%5Fsandbox)

[Registrations](https://developers.cloudflare.com/api/python/resources/registrar%5Fsandbox/subresources/registrations)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

---

**Copy Markdown**

**View as Markdown**

# Create Registration

registrar\_sandbox.registrations.create(RegistrationCreateParams\*\*kwargs)  \-> [RegistrationCreateResponse](https://developers.cloudflare.com/api/python/resources/registrar%5Fsandbox#%28resource%29%20registrar%5Fsandbox.registrations%20%3E%20%28model%29%20registration%5Fcreate%5Fresponse%20%3E%20%28schema%29)

POST/accounts/{account\_id}/registrar-sandbox/registrations

Starts a domain registration workflow.

### Prerequisites

* The account must not already be at the maximum supported domain limit. A single account may own up to 500 domains in total across registrations created through either the dashboard or this API.
* The domain must be on a supported extension for programmatic registration.
* Use `POST /domain-check` immediately before calling this endpoint to confirm real-time availability and pricing.

### Defaults

* `years`: defaults to the extension’s minimum registration period (1 year for most extensions, but varies — for example, `.ai` (if supported) requires a minimum of 2 years).
* `auto_renew`: defaults to `false`. Setting it to `true` is an explicit opt-in authorizing Cloudflare to charge the account’s default payment method up to 30 days before domain expiry to renew the registration. Renewal pricing may change over time based on registry pricing.
* `privacy_mode`: defaults to `redaction`.

### Premium domains

Premium domain registration is not currently supported by this API. If `POST /domain-check` returns `tier: premium`, do not call this endpoint for that domain.

### Response behavior

By default, the server holds the connection for a bounded, server-defined amount of time while the registration completes. Most registrations finish within this window and return `201 Created` with a completed workflow status.

If the registration is still processing after this synchronous wait window, the server returns `202 Accepted`. Poll the URL in `links.self` to track progress.

To skip the wait and receive an immediate `202`, send `Prefer: respond-async`.

##### Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. [Create a token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/).

**Example:**`Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY`

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

**Example:**`X-Auth-Email: user@example.com`

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

**Example:**`X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194`

##### ParametersExpand Collapse 

account\_id: str

Identifier.

maxLength32

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.

acknowledgements: Optional\[Dict\[str, object\]\]

Provides user acknowledgements for a specific extension or premium registration flow. The extension registration schema from the extension discovery endpoint identifies the required keys.

auto\_renew: Optional\[[bool](https://developers.cloudflare.com/api/python/resources/registrar%5Fsandbox/subresources/registrations/methods/create#%28resource%29%20registrar%5Fsandbox.registrations%20%3E%20%28method%29%20create%20%3E%20%28params%29%20default%20%3E%20%28param%29%20auto%5Frenew%20%3E%20%28schema%29)\]

Enable or disable automatic renewal. Defaults to `false` if omitted. Setting this field to `true` is an explicit opt-in authorizing Cloudflare to charge the account’s default payment method up to 30 days before domain expiry to renew the domain automatically. Renewal pricing may change over time based on registry pricing.

contact\_extensions: Optional\[Dict\[str, object\]\]

Provides registry-specific contact extension values for the registrant. `GET /accounts/{account_id}/registrar/extensions/{extension}` identifies the required keys and allowed values for each extension in the `registration_schema.properties.contact_extensions` object.

Examples include `.us` nexus fields, `.uk` registrant type fields, and `.ca` legal type fields. Omit this object when the extension’s registration schema excludes `contact_extensions`.

contacts: Optional\[[Contacts](https://developers.cloudflare.com/api/python/resources/registrar%5Fsandbox/subresources/registrations/methods/create#%28resource%29%20registrar%5Fsandbox.registrations%20%3E%20%28method%29%20create%20%3E%20%28params%29%20default%20%3E%20%28param%29%20contacts%20%3E%20%28schema%29)\]

Provides contact data for the registration request.

The per-extension schema from `GET /accounts/{account_id}/registrar/extensions/{extension}` defines the accepted contact roles. Every currently supported extension requires only `contacts.registrant` from API callers. Callers may provide additional roles such as `technical`, `administrator`, and `billing` when the extension schema includes them. When a registry requires an omitted role, Cloudflare may derive that contact from `contacts.registrant`.

When the request omits either the entire `contacts` object or `contacts.registrant`, the system uses the account’s default address book entry as the registrant contact. The account owner must configure this default at `https://dash.cloudflare.com/{account_id}/domains/registrations`, where they can create or update the address book entry and accept the required agreement. Dashboard settings currently provide the only way to manage address book entries.

Without either a default address book entry or a registrant contact, the registration request fails validation.

administrator: Optional\[ContactsAdministrator\]

Optional administrator contact. Accepted only when the extension schema includes this role. When the registry requires an omitted contact, Cloudflare may derive it from `contacts.registrant`.

email: str

Email address for the registrant. Used for domain-related communications from the registry, including ownership verification and renewal notices.

formatemail

phone: str

Phone number in E.164 format: `+{country_code}.{number}` without spaces or dashes. Examples: `+1.5555555555` (US), `+44.2071234567` (UK), `+81.312345678` (Japan).

postal\_info: ContactsAdministratorPostalInfo

Postal/mailing information for the contact. The `name` field is the complete contact name in one string. Some registries require a complete personal name, including a family or last name where applicable, but this API does not accept separate first-name and last-name fields for registration contacts.

address: ContactsAdministratorPostalInfoAddress

Physical mailing address for the registrant contact.

city: str

City or locality name.

country\_code: str

Two-letter country code per ISO 3166-1 alpha-2 (e.g., `US`, `GB`, `CA`, `DE`).

postal\_code: str

Postal or ZIP code.

state: str

State, province, or region. Use the standard abbreviation where applicable (e.g., `TX` for Texas, `ON` for Ontario).

street: str

Street address including building/suite number.

name: str

Full legal name of the contact, including all required name components for an individual or authorized representative. Some registries require a complete personal name that includes a family or last name where applicable. Provide the complete name in this single field, for example `Ada Lovelace`; do not send separate first-name or last-name fields.

organization: Optional\[str\]

Organization or company name. Optional for individual registrants.

fax: Optional\[str\]

Fax number in E.164 format (e.g., `+1.5555555555`). Optional. Most registrations do not require a fax number.

billing: Optional\[ContactsBilling\]

Optional billing contact. Accepted only when the extension schema includes this role. When the registry requires an omitted contact, Cloudflare may derive it from `contacts.registrant`.

email: str

Email address for the registrant. Used for domain-related communications from the registry, including ownership verification and renewal notices.

formatemail

phone: str

Phone number in E.164 format: `+{country_code}.{number}` without spaces or dashes. Examples: `+1.5555555555` (US), `+44.2071234567` (UK), `+81.312345678` (Japan).

postal\_info: ContactsBillingPostalInfo

Postal/mailing information for the contact. The `name` field is the complete contact name in one string. Some registries require a complete personal name, including a family or last name where applicable, but this API does not accept separate first-name and last-name fields for registration contacts.

address: ContactsBillingPostalInfoAddress

Physical mailing address for the registrant contact.

city: str

City or locality name.

country\_code: str

Two-letter country code per ISO 3166-1 alpha-2 (e.g., `US`, `GB`, `CA`, `DE`).

postal\_code: str

Postal or ZIP code.

state: str

State, province, or region. Use the standard abbreviation where applicable (e.g., `TX` for Texas, `ON` for Ontario).

street: str

Street address including building/suite number.

name: str

Full legal name of the contact, including all required name components for an individual or authorized representative. Some registries require a complete personal name that includes a family or last name where applicable. Provide the complete name in this single field, for example `Ada Lovelace`; do not send separate first-name or last-name fields.

organization: Optional\[str\]

Organization or company name. Optional for individual registrants.

fax: Optional\[str\]

Fax number in E.164 format (e.g., `+1.5555555555`). Optional. Most registrations do not require a fax number.

registrant: Optional\[ContactsRegistrant\]

Optional registrant contact. If omitted, the account’s default address book entry is used instead.

email: str

Email address for the registrant. Used for domain-related communications from the registry, including ownership verification and renewal notices.

formatemail

phone: str

Phone number in E.164 format: `+{country_code}.{number}` without spaces or dashes. Examples: `+1.5555555555` (US), `+44.2071234567` (UK), `+81.312345678` (Japan).

postal\_info: ContactsRegistrantPostalInfo

Postal/mailing information for the contact. The `name` field is the complete contact name in one string. Some registries require a complete personal name, including a family or last name where applicable, but this API does not accept separate first-name and last-name fields for registration contacts.

address: ContactsRegistrantPostalInfoAddress

Physical mailing address for the registrant contact.

city: str

City or locality name.

country\_code: str

Two-letter country code per ISO 3166-1 alpha-2 (e.g., `US`, `GB`, `CA`, `DE`).

postal\_code: str

Postal or ZIP code.

state: str

State, province, or region. Use the standard abbreviation where applicable (e.g., `TX` for Texas, `ON` for Ontario).

street: str

Street address including building/suite number.

name: str

Full legal name of the contact, including all required name components for an individual or authorized representative. Some registries require a complete personal name that includes a family or last name where applicable. Provide the complete name in this single field, for example `Ada Lovelace`; do not send separate first-name or last-name fields.

organization: Optional\[str\]

Organization or company name. Optional for individual registrants.

fax: Optional\[str\]

Fax number in E.164 format (e.g., `+1.5555555555`). Optional. Most registrations do not require a fax number.

technical: Optional\[ContactsTechnical\]

Optional technical contact. Accepted only when the extension schema includes this role. When the registry requires an omitted contact, Cloudflare may derive it from `contacts.registrant`.

email: str

Email address for the registrant. Used for domain-related communications from the registry, including ownership verification and renewal notices.

formatemail

phone: str

Phone number in E.164 format: `+{country_code}.{number}` without spaces or dashes. Examples: `+1.5555555555` (US), `+44.2071234567` (UK), `+81.312345678` (Japan).

postal\_info: ContactsTechnicalPostalInfo

Postal/mailing information for the contact. The `name` field is the complete contact name in one string. Some registries require a complete personal name, including a family or last name where applicable, but this API does not accept separate first-name and last-name fields for registration contacts.

address: ContactsTechnicalPostalInfoAddress

Physical mailing address for the registrant contact.

city: str

City or locality name.

country\_code: str

Two-letter country code per ISO 3166-1 alpha-2 (e.g., `US`, `GB`, `CA`, `DE`).

postal\_code: str

Postal or ZIP code.

state: str

State, province, or region. Use the standard abbreviation where applicable (e.g., `TX` for Texas, `ON` for Ontario).

street: str

Street address including building/suite number.

name: str

Full legal name of the contact, including all required name components for an individual or authorized representative. Some registries require a complete personal name that includes a family or last name where applicable. Provide the complete name in this single field, for example `Ada Lovelace`; do not send separate first-name or last-name fields.

organization: Optional\[str\]

Organization or company name. Optional for individual registrants.

fax: Optional\[str\]

Fax number in E.164 format (e.g., `+1.5555555555`). Optional. Most registrations do not require a fax number.

privacy\_mode: Optional\[Literal\["off", "redaction"\]\]

Sets the WHOIS privacy mode for the registration. Defaults to `redaction`.

* `off`: Disables WHOIS privacy.
* `redaction`: Requests WHOIS redaction where the extension supports it. Some extensions exclude privacy and redaction.

One of the following:

"off"

"redaction"

years: Optional\[int\]

Sets the registration term from 1 to 10 years. When omitted, this field defaults to the registry’s minimum registration period for the extension. Most extensions require 1 year, while some require longer minimum terms (e.g., `.ai` requires 2 years).

Each registry may also enforce its own maximum registration term. A request above that maximum fails. When uncertain, omit this field to use the default.

maximum10

minimum1

prefer: Optional\[str\]

##### ReturnsExpand Collapse 

class RegistrationCreateResponse: …

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

links: Links

self: str

URL to this status resource.

resource: Optional\[str\]

URL to the domain resource.

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.

### Create Registration

Python

HTTPHTTP

TypeScriptTypeScript

PythonPython

GoGo

TerraformTerraform

```
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
registration = client.registrar_sandbox.registrations.create(
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    domain_name="my-brand-example.io",
    auto_renew=False,
    contacts={
        "administrator": {
            "email": "katherine@example.io",
            "phone": "+1.5555550102",
            "postal_info": {
                "address": {
                    "city": "San Francisco",
                    "country_code": "US",
                    "postal_code": "94103",
                    "state": "CA",
                    "street": "789 Mission St",
                },
                "name": "Katherine Johnson",
                "organization": "Example Admin Inc",
            },
        },
        "billing": {
            "email": "dorothy@example.io",
            "phone": "+1.5555550103",
            "postal_info": {
                "address": {
                    "city": "San Francisco",
                    "country_code": "US",
                    "postal_code": "94105",
                    "state": "CA",
                    "street": "101 Howard St",
                },
                "name": "Dorothy Vaughan",
                "organization": "Example Billing Inc",
            },
        },
        "registrant": {
            "email": "ada@example.io",
            "phone": "+1.5555555555",
            "postal_info": {
                "address": {
                    "city": "Austin",
                    "country_code": "US",
                    "postal_code": "78701",
                    "state": "TX",
                    "street": "123 Main St",
                },
                "name": "Ada Lovelace",
                "organization": "Example Inc",
            },
        },
        "technical": {
            "email": "grace@example.io",
            "phone": "+1.5555550101",
            "postal_info": {
                "address": {
                    "city": "San Francisco",
                    "country_code": "US",
                    "postal_code": "94105",
                    "state": "CA",
                    "street": "456 Market St",
                },
                "name": "Grace Hopper",
                "organization": "Example Technical Inc",
            },
        },
    },
    years=1,
)
print(registration.completed)
```

201 example

202 example

4XX example

4XX example

4XX example

4XX example

4XX example

```
{
  "errors": [],
  "messages": [],
  "result": {
    "completed": true,
    "context": {
      "domain_name": "example.com",
      "registration": {
        "auto_renew": true,
        "created_at": "2025-10-27T10:00:00Z",
        "domain_name": "example.com",
        "expires_at": "2026-10-27T10:00:00Z",
        "locked": true,
        "privacy_mode": "redaction",
        "status": "active"
      }
    },
    "created_at": "2025-10-27T10:00:00Z",
    "links": {
      "resource": "/accounts/abc/registrar/registrations/example.com",
      "self": "/accounts/abc/registrar/registrations/example.com/registration-status"
    },
    "state": "succeeded",
    "updated_at": "2025-10-27T10:00:03Z"
  },
  "success": true
}
```

```
{
  "errors": [],
  "messages": [],
  "result": {
    "completed": false,
    "context": {
      "domain_name": "example.com"
    },
    "created_at": "2025-10-27T10:00:00Z",
    "links": {
      "resource": "/accounts/abc/registrar/registrations/example.com",
      "self": "/accounts/abc/registrar/registrations/example.com/registration-status"
    },
    "state": "in_progress",
    "updated_at": "2025-10-27T10:00:10Z"
  },
  "success": true
}
```

```
{
  "errors": [
    {
      "code": 10000,
      "message": "Domain limit reached: you cannot register more than 500 domains.",
      "source": {
        "pointer": "/domain_name"
      }
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}
```

```
{
  "errors": [
    {
      "code": 10000,
      "message": "domain_name is required",
      "source": {
        "pointer": "/domain_name"
      }
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}
```

```
{
  "errors": [
    {
      "code": 10000,
      "message": "Must be a boolean",
      "source": {
        "pointer": "/auto_renew"
      }
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}
```

```
{
  "errors": [
    {
      "code": 10000,
      "message": "No registrant contact provided and no default address book entry found for this account."
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}
```

```
{
  "errors": [
    {
      "code": 10000,
      "message": "Registration is not supported for this extension"
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}
```

##### Returns Examples

201 example

202 example

4XX example

4XX example

4XX example

4XX example

4XX example

```
{
  "errors": [],
  "messages": [],
  "result": {
    "completed": true,
    "context": {
      "domain_name": "example.com",
      "registration": {
        "auto_renew": true,
        "created_at": "2025-10-27T10:00:00Z",
        "domain_name": "example.com",
        "expires_at": "2026-10-27T10:00:00Z",
        "locked": true,
        "privacy_mode": "redaction",
        "status": "active"
      }
    },
    "created_at": "2025-10-27T10:00:00Z",
    "links": {
      "resource": "/accounts/abc/registrar/registrations/example.com",
      "self": "/accounts/abc/registrar/registrations/example.com/registration-status"
    },
    "state": "succeeded",
    "updated_at": "2025-10-27T10:00:03Z"
  },
  "success": true
}
```

```
{
  "errors": [],
  "messages": [],
  "result": {
    "completed": false,
    "context": {
      "domain_name": "example.com"
    },
    "created_at": "2025-10-27T10:00:00Z",
    "links": {
      "resource": "/accounts/abc/registrar/registrations/example.com",
      "self": "/accounts/abc/registrar/registrations/example.com/registration-status"
    },
    "state": "in_progress",
    "updated_at": "2025-10-27T10:00:10Z"
  },
  "success": true
}
```

```
{
  "errors": [
    {
      "code": 10000,
      "message": "Domain limit reached: you cannot register more than 500 domains.",
      "source": {
        "pointer": "/domain_name"
      }
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}
```

```
{
  "errors": [
    {
      "code": 10000,
      "message": "domain_name is required",
      "source": {
        "pointer": "/domain_name"
      }
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}
```

```
{
  "errors": [
    {
      "code": 10000,
      "message": "Must be a boolean",
      "source": {
        "pointer": "/auto_renew"
      }
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}
```

```
{
  "errors": [
    {
      "code": 10000,
      "message": "No registrant contact provided and no default address book entry found for this account."
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}
```

```
{
  "errors": [
    {
      "code": 10000,
      "message": "Registration is not supported for this extension"
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}
```