## Create Registration `client.registrar.registrations.create(RegistrationCreateParamsparams, RequestOptionsoptions?): WorkflowStatus` **post** `/accounts/{account_id}/registrar/registrations` Starts a domain registration workflow. This is a billable operation — successful registration charges the account's default payment method. All successful domain registrations are non-refundable — once the workflow completes with `state: succeeded`, the charge cannot be reversed. ### Prerequisites - The account must have a billing profile with a valid default payment method. Set this up at `https://dash.cloudflare.com/{account_id}/billing/payment-info`. - The account must not already be at the maximum supported domain limit. A single account may own up to 100 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. ### Express mode The only required field is `domain_name`. If `contacts` is omitted, the system uses the account's default address book entry as the registrant. If no default exists and no contact is provided, the request fails. Set up a default address book entry and accept the required agreement at `https://dash.cloudflare.com/{account_id}/domains/registrations`. ### 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`. ### Parameters - `params: RegistrationCreateParams` - `account_id: string` Path param: Identifier - `domain_name: string` Body param: 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. - `acknowledgements?: Record` Body param: User acknowledgements required by a specific extension or premium registration flow. The expected keys are described by the extension registration schema returned by the extension discovery endpoint. - `auto_renew?: boolean` Body param: 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?: Record` Body param: Registry-specific contact extension values for the registrant. The required keys and allowed values vary by extension and are described by `GET /accounts/{account_id}/registrar/extensions/{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 for extensions whose registration schema does not include `contact_extensions`. - `contacts?: Contacts` Body param: Contact data for the registration request. The per-extension schema returned by `GET /accounts/{account_id}/registrar/extensions/{extension}` is the authoritative contract for which contact roles are accepted. Every currently supported extension requires only `contacts.registrant` from API callers. Additional roles such as `technical`, `administrator`, and `billing` may be provided when the extension schema includes them. If a registry requires one of those roles and the caller omits it, Cloudflare may derive that contact from `contacts.registrant`. If the `contacts` object is omitted entirely from the request, or if `contacts.registrant` is not provided, the system will use the account's default address book entry as the registrant contact. This default must be pre-configured by the account owner at `https://dash.cloudflare.com/{account_id}/domains/registrations`, where they can create or update the address book entry and accept the required agreement. No API exists for managing address book entries at this time. If no default address book entry exists and no registrant contact is provided, the registration request will fail with a validation error. - `administrator?: Administrator` Contact data for the domain registration. This information is submitted to the domain registry and, depending on extension and privacy settings, may appear in public WHOIS records. - `email: string` Email address for the registrant. Used for domain-related communications from the registry, including ownership verification and renewal notices. - `phone: string` Phone number in E.164 format: `+{country_code}.{number}` with no spaces or dashes. Examples: `+1.5555555555` (US), `+44.2071234567` (UK), `+81.312345678` (Japan). - `postal_info: PostalInfo` 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: Address` Physical mailing address for the registrant contact. - `city: string` City or locality name. - `country_code: string` Two-letter country code per ISO 3166-1 alpha-2 (e.g., `US`, `GB`, `CA`, `DE`). - `postal_code: string` Postal or ZIP code. - `state: string` State, province, or region. Use the standard abbreviation where applicable (e.g., `TX` for Texas, `ON` for Ontario). - `street: string` Street address including building/suite number. - `name: string` 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?: string` Organization or company name. Optional for individual registrants. - `fax?: string` Fax number in E.164 format (e.g., `+1.5555555555`). Optional. Most registrations do not require a fax number. - `billing?: Billing` Contact data for the domain registration. This information is submitted to the domain registry and, depending on extension and privacy settings, may appear in public WHOIS records. - `email: string` Email address for the registrant. Used for domain-related communications from the registry, including ownership verification and renewal notices. - `phone: string` Phone number in E.164 format: `+{country_code}.{number}` with no spaces or dashes. Examples: `+1.5555555555` (US), `+44.2071234567` (UK), `+81.312345678` (Japan). - `postal_info: PostalInfo` 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: Address` Physical mailing address for the registrant contact. - `city: string` City or locality name. - `country_code: string` Two-letter country code per ISO 3166-1 alpha-2 (e.g., `US`, `GB`, `CA`, `DE`). - `postal_code: string` Postal or ZIP code. - `state: string` State, province, or region. Use the standard abbreviation where applicable (e.g., `TX` for Texas, `ON` for Ontario). - `street: string` Street address including building/suite number. - `name: string` 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?: string` Organization or company name. Optional for individual registrants. - `fax?: string` Fax number in E.164 format (e.g., `+1.5555555555`). Optional. Most registrations do not require a fax number. - `registrant?: Registrant` Contact data for the domain registration. This information is submitted to the domain registry and, depending on extension and privacy settings, may appear in public WHOIS records. - `email: string` Email address for the registrant. Used for domain-related communications from the registry, including ownership verification and renewal notices. - `phone: string` Phone number in E.164 format: `+{country_code}.{number}` with no spaces or dashes. Examples: `+1.5555555555` (US), `+44.2071234567` (UK), `+81.312345678` (Japan). - `postal_info: PostalInfo` 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: Address` Physical mailing address for the registrant contact. - `city: string` City or locality name. - `country_code: string` Two-letter country code per ISO 3166-1 alpha-2 (e.g., `US`, `GB`, `CA`, `DE`). - `postal_code: string` Postal or ZIP code. - `state: string` State, province, or region. Use the standard abbreviation where applicable (e.g., `TX` for Texas, `ON` for Ontario). - `street: string` Street address including building/suite number. - `name: string` 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?: string` Organization or company name. Optional for individual registrants. - `fax?: string` Fax number in E.164 format (e.g., `+1.5555555555`). Optional. Most registrations do not require a fax number. - `technical?: Technical` Contact data for the domain registration. This information is submitted to the domain registry and, depending on extension and privacy settings, may appear in public WHOIS records. - `email: string` Email address for the registrant. Used for domain-related communications from the registry, including ownership verification and renewal notices. - `phone: string` Phone number in E.164 format: `+{country_code}.{number}` with no spaces or dashes. Examples: `+1.5555555555` (US), `+44.2071234567` (UK), `+81.312345678` (Japan). - `postal_info: PostalInfo` 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: Address` Physical mailing address for the registrant contact. - `city: string` City or locality name. - `country_code: string` Two-letter country code per ISO 3166-1 alpha-2 (e.g., `US`, `GB`, `CA`, `DE`). - `postal_code: string` Postal or ZIP code. - `state: string` State, province, or region. Use the standard abbreviation where applicable (e.g., `TX` for Texas, `ON` for Ontario). - `street: string` Street address including building/suite number. - `name: string` 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?: string` Organization or company name. Optional for individual registrants. - `fax?: string` Fax number in E.164 format (e.g., `+1.5555555555`). Optional. Most registrations do not require a fax number. - `privacy_mode?: "redaction"` Body param: WHOIS privacy mode for the registration. Defaults to `redaction`. - `off`: Do not request WHOIS privacy. - `redaction`: Request WHOIS redaction where supported by the extension. Some extensions do not support privacy/redaction. - `"redaction"` - `years?: number` Body param: Number of years to register (1–10). If omitted, defaults to the minimum registration period required by the registry for this extension. For most extensions this is 1 year, but some extensions require longer minimum terms (e.g., `.ai` requires a minimum of 2 years). The registry for each extension may also enforce its own maximum registration term. If the requested value exceeds the registry's maximum, the registration will be rejected. When in doubt, use the default by omitting this field. - `Prefer?: string` Header param: Set to `respond-async` to receive an immediate `202 Accepted` without waiting for the operation to complete (RFC 7240). The header may be combined with other preferences using standard comma-separated syntax. ### Returns - `WorkflowStatus` 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` - `links: Links` - `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. - `"pending"` - `"in_progress"` - `"action_required"` - `"blocked"` - `"succeeded"` - `"failed"` - `updated_at: string` - `context?: Record` 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. ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const workflowStatus = await client.registrar.registrations.create({ account_id: '023e105f4ecef8ad9ca31a8372d0c353', domain_name: 'my-brand-example.io', 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, }); console.log(workflowStatus.completed); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "completed": false, "created_at": "2019-12-27T18:11:19.117Z", "links": { "self": "/accounts/{account_id}/registrar/registrations/example.com/registration-status", "resource": "/accounts/{account_id}/registrar/registrations/example.com" }, "state": "in_progress", "updated_at": "2019-12-27T18:11:19.117Z", "context": { "foo": "bar" }, "error": { "code": "registry_rejected", "message": "Registry rejected the request." } }, "success": true } ```