# Registrar

## Search for available domains

`client.registrar.search(RegistrarSearchParamsparams, RequestOptionsoptions?): RegistrarSearchResponse`

**get** `/accounts/{account_id}/registrar/domain-search`

Searches for domain name suggestions based on a keyword, phrase, or partial domain name.
Returns a list of potentially available domains with pricing information.

**Important:** Results are non-authoritative and based on cached data. Always use the
`/domain-check` endpoint to verify real-time availability before attempting registration.

Suggestions are scoped to extensions supported for programmatic registration
via this API (`POST /registrations`). Domains on unsupported extensions will
not appear in results, even if they are available at the registry level.

### Use cases

- Brand name discovery (e.g., "acme corp" → acmecorp.com, acmecorp.dev)
- Keyword-based suggestions (e.g., "coffee shop" → coffeeshop.com, mycoffeeshop.net)
- Alternative extension discovery (e.g., "example.com" → example.com, example.app, example.xyz)

### Workflow

1. Call this endpoint with a keyword or domain name.
1. Present suggestions to the user.
1. Call `/domain-check` with the user's chosen domains to confirm real-time availability and pricing.
1. Proceed to `POST /registrations` only for supported non-premium domains
   where the Check response returns `registrable: true`.

**Note:** Searching with just a domain extension (e.g., "com" or ".app") is not supported. Provide a keyword or domain name.

### Parameters

- `params: RegistrarSearchParams`

  - `account_id: string`

    Path param: Identifier

  - `q: string`

    Query param: The search term to find domain suggestions. Accepts keywords, phrases, or full domain names.

    - Phrases: "coffee shop" returns coffeeshop.com, mycoffeeshop.net, etc.
    - Domain names: "example.com" returns example.com and variations across extensions

  - `extensions?: Array<string>`

    Query param: Limits results to specific domain extensions from the supported set. If not specified,
    returns results across all supported extensions. Extensions not in the supported
    set are silently ignored.

  - `limit?: number`

    Query param: Maximum number of domain suggestions to return. Defaults to 20 if not specified.

### Returns

- `RegistrarSearchResponse`

  Contains the search results.

  - `domains: Array<Domain>`

    Array of domain suggestions sorted by relevance. May be empty if no domains match the search criteria.

    - `name: string`

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

    - `registrable: boolean`

      Indicates whether this domain appears available based on search data. Search results are non-authoritative and may be stale. - `true`: The domain appears available. Use POST /domain-check to confirm before registration.

      - `false`: The domain does not appear available in search results.

    - `pricing?: Pricing`

      Annual pricing information for a registrable domain. This object is only
      present when `registrable` is `true`. All prices are per year and returned
      as strings to preserve decimal precision.

      `registration_cost` and `renewal_cost` are frequently the same value, but
      may differ — especially for premium domains where registries set different
      rates for initial registration vs. renewal. For a multi-year registration
      (e.g., 4 years), the first year is charged at `registration_cost` and each
      subsequent year at `renewal_cost`. Registry pricing may change over time;
      the values returned here reflect the current registry rate. Premium pricing
      may be surfaced by Search and Check, but premium registration is not currently
      supported by this API.

      - `currency: string`

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

      - `registration_cost: string`

        The first-year cost to register this domain. For premium domains
        (`tier: premium`), this price is set by the registry and may be
        significantly higher than standard pricing. For multi-year
        registrations, this cost applies to the first year only; subsequent
        years are charged at `renewal_cost`.

      - `renewal_cost: string`

        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?: "extension_not_supported_via_api" | "extension_not_supported" | "extension_disallows_registration" | 2 more`

      Present only when `registrable` is `false` on search results. Explains why the domain does not appear registrable through this API. These values are advisory; use POST /domain-check for authoritative status.

      - `extension_not_supported_via_api`: Cloudflare Registrar supports this extension in the dashboard but it is not yet available for programmatic registration via this API.
      - `extension_not_supported`: This extension is not supported by Cloudflare Registrar at all.
      - `extension_disallows_registration`: The extension's registry has temporarily or permanently frozen new registrations.
      - `domain_premium`: The domain is premium priced. Premium registration is not currently supported by this API.
      - `domain_unavailable`: The domain appears unavailable.

      - `"extension_not_supported_via_api"`

      - `"extension_not_supported"`

      - `"extension_disallows_registration"`

      - `"domain_premium"`

      - `"domain_unavailable"`

    - `tier?: "standard" | "premium"`

      The pricing tier for this domain. Always present when `registrable` is `true`;
      defaults to `standard` for most domains. May be absent when `registrable`
      is `false`.

      - `standard`: Standard registry pricing
      - `premium`: Premium domain with higher pricing set by the registry

      - `"standard"`

      - `"premium"`

### Example

```node
import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

const response = await client.registrar.search({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  q: 'x',
});

console.log(response.domains);
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "acmecorp.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "acmecorp.dev",
        "pricing": {
          "currency": "USD",
          "registration_cost": "10.11",
          "renewal_cost": "10.11"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "acmecorp.app",
        "pricing": {
          "currency": "USD",
          "registration_cost": "11.00",
          "renewal_cost": "11.00"
        },
        "registrable": true,
        "tier": "standard"
      }
    ]
  },
  "success": true
}
```

## Check domain availability

`client.registrar.check(RegistrarCheckParamsparams, RequestOptionsoptions?): RegistrarCheckResponse`

**post** `/accounts/{account_id}/registrar/domain-check`

Performs real-time, authoritative availability checks directly against domain
registries. Use this endpoint to verify a domain is available before attempting
registration via `POST /registrations`.

**Important:** Unlike the Search endpoint, these results are authoritative and
reflect current registry status. Always check availability immediately before
registration as domain status can change rapidly.

**Note:** This endpoint uses POST to accept a list of domains in the request
body. It is a read-only operation — it does not create, modify, or reserve
any domains.

### Extension support

Only domains on extensions supported for programmatic registration by this API
can be registered. If you check a domain on an unsupported extension, the response
will include `registrable: false` with a `reason` field explaining why:

- `extension_not_supported_via_api` — Cloudflare Registrar supports this extension
  in the dashboard, but it is not yet available for programmatic registration via
  this API. Register via `https://dash.cloudflare.com/{account_id}/domains/registrations` instead.
- `extension_not_supported` — This extension is not supported by Cloudflare
  Registrar.
- `extension_disallows_registration` — The extension's registry has temporarily
  or permanently frozen new registrations. No registrar can register domains on
  this extension at this time.
- `domain_premium` — The domain is premium priced. Premium registration is not
  currently supported by this API.
- `domain_unavailable` — The domain is already registered, reserved, or otherwise
  not available for registration on a supported extension.

The `reason` field is only present when `registrable` is `false`.

### Behavior

- Maximum 20 domains per request
- Pricing is only returned for domains where `registrable: true`
- Results are not cached; each request queries the registry

### Workflow

1. Call this endpoint with domains the user wants to register.
1. For each domain where `registrable: true`, present pricing to the user.
1. If `tier: premium`, note that premium registration is not currently
   supported by this API and do not proceed to `POST /registrations`.
1. Proceed to `POST /registrations` only for supported non-premium domains.

### Parameters

- `params: RegistrarCheckParams`

  - `account_id: string`

    Path param: Identifier

  - `domains: Array<string>`

    Body param: List of fully qualified domain names (FQDNs) to check for availability. Each domain must include the extension.

    - Minimum: 1 domain
    - Maximum: 20 domains per request
    - Domains on unsupported extensions are returned with `registrable: false` and a `reason` field
    - Malformed domain names (e.g., missing extension) may be omitted from the response

### Returns

- `RegistrarCheckResponse`

  Contains the availability check results.

  - `domains: Array<Domain>`

    Array of domain availability results. Domains on unsupported
    extensions are included with `registrable: false` and a `reason`
    field. Malformed domain names may be omitted.

    - `name: string`

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

    - `registrable: boolean`

      Indicates whether this domain can be registered programmatically through this API based on a real-time registry check.

      - `true`: Domain is available for registration. The `pricing` object will be included.
      - `false`: Domain is not available. See the `reason` field for why. `tier` may still be present on some non-registrable results, such as premium domains.

    - `pricing?: Pricing`

      Annual pricing information for a registrable domain. This object is only
      present when `registrable` is `true`. All prices are per year and returned
      as strings to preserve decimal precision.

      `registration_cost` and `renewal_cost` are frequently the same value, but
      may differ — especially for premium domains where registries set different
      rates for initial registration vs. renewal. For a multi-year registration
      (e.g., 4 years), the first year is charged at `registration_cost` and each
      subsequent year at `renewal_cost`. Registry pricing may change over time;
      the values returned here reflect the current registry rate. Premium pricing
      may be surfaced by Search and Check, but premium registration is not currently
      supported by this API.

      - `currency: string`

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

      - `registration_cost: string`

        The first-year cost to register this domain. For premium domains
        (`tier: premium`), this price is set by the registry and may be
        significantly higher than standard pricing. For multi-year
        registrations, this cost applies to the first year only; subsequent
        years are charged at `renewal_cost`.

      - `renewal_cost: string`

        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?: "extension_not_supported_via_api" | "extension_not_supported" | "extension_disallows_registration" | 2 more`

      Present only when `registrable` is `false`. Explains why the domain cannot be registered via this API.

      - `extension_not_supported_via_api`: Cloudflare Registrar supports this extension in the dashboard but it is not yet available for programmatic registration via this API. The user can register via `https://dash.cloudflare.com/{account_id}/domains/registrations`.
      - `extension_not_supported`: This extension is not supported by Cloudflare Registrar at all.
      - `extension_disallows_registration`: The extension's registry has temporarily or permanently frozen new registrations. No registrar can register domains on this extension at this time.
      - `domain_premium`: The domain is premium priced. Premium registration is not currently supported by this API.
      - `domain_unavailable`: The domain is already registered, reserved, or otherwise not available on a supported extension.

      - `"extension_not_supported_via_api"`

      - `"extension_not_supported"`

      - `"extension_disallows_registration"`

      - `"domain_premium"`

      - `"domain_unavailable"`

    - `tier?: "standard" | "premium"`

      The pricing tier for this domain. Always present when `registrable` is `true`; defaults to `standard` for most domains. May be absent when `registrable` is `false`.

      - `standard`: Standard registry pricing
      - `premium`: Premium domain with higher pricing set by the registry

      - `"standard"`

      - `"premium"`

### Example

```node
import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

const response = await client.registrar.check({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  domains: [
    'myawesomebrand.com',
    'myawesomebrand.net',
    'myawesomebrand.org',
    'myawesomebrand.app',
    'myawesomebrand.dev',
  ],
});

console.log(response.domains);
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "xq7mz9brand.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "xq7mz9brand.net",
        "pricing": {
          "currency": "USD",
          "registration_cost": "9.95",
          "renewal_cost": "9.95"
        },
        "registrable": true,
        "tier": "standard"
      }
    ]
  },
  "success": true
}
```

## Domain Types

### Registration

- `Registration`

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

  - `auto_renew: boolean`

    Whether the domain will be automatically renewed before expiration.

  - `created_at: string`

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

  - `domain_name: string`

    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.

  - `expires_at: string | null`

    When the domain registration expires. Present when the registration is ready; may be null only while `status` is `registration_pending`.

  - `locked: boolean`

    Whether the domain is locked for transfer.

  - `privacy_mode: "redaction"`

    Current WHOIS privacy mode for the registration.

    - `"redaction"`

  - `status: "active" | "registration_pending" | "expired" | 3 more`

    Current registration status.

    - `active`: Domain is registered and operational
    - `registration_pending`: Registration is in progress
    - `expired`: Domain has expired
    - `suspended`: Domain is suspended by the registry
    - `redemption_period`: Domain is in the redemption grace period
    - `pending_delete`: Domain is pending deletion by the registry

    - `"active"`

    - `"registration_pending"`

    - `"expired"`

    - `"suspended"`

    - `"redemption_period"`

    - `"pending_delete"`

### Workflow Status

- `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<string, unknown>`

    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.

### Registrar Search Response

- `RegistrarSearchResponse`

  Contains the search results.

  - `domains: Array<Domain>`

    Array of domain suggestions sorted by relevance. May be empty if no domains match the search criteria.

    - `name: string`

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

    - `registrable: boolean`

      Indicates whether this domain appears available based on search data. Search results are non-authoritative and may be stale. - `true`: The domain appears available. Use POST /domain-check to confirm before registration.

      - `false`: The domain does not appear available in search results.

    - `pricing?: Pricing`

      Annual pricing information for a registrable domain. This object is only
      present when `registrable` is `true`. All prices are per year and returned
      as strings to preserve decimal precision.

      `registration_cost` and `renewal_cost` are frequently the same value, but
      may differ — especially for premium domains where registries set different
      rates for initial registration vs. renewal. For a multi-year registration
      (e.g., 4 years), the first year is charged at `registration_cost` and each
      subsequent year at `renewal_cost`. Registry pricing may change over time;
      the values returned here reflect the current registry rate. Premium pricing
      may be surfaced by Search and Check, but premium registration is not currently
      supported by this API.

      - `currency: string`

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

      - `registration_cost: string`

        The first-year cost to register this domain. For premium domains
        (`tier: premium`), this price is set by the registry and may be
        significantly higher than standard pricing. For multi-year
        registrations, this cost applies to the first year only; subsequent
        years are charged at `renewal_cost`.

      - `renewal_cost: string`

        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?: "extension_not_supported_via_api" | "extension_not_supported" | "extension_disallows_registration" | 2 more`

      Present only when `registrable` is `false` on search results. Explains why the domain does not appear registrable through this API. These values are advisory; use POST /domain-check for authoritative status.

      - `extension_not_supported_via_api`: Cloudflare Registrar supports this extension in the dashboard but it is not yet available for programmatic registration via this API.
      - `extension_not_supported`: This extension is not supported by Cloudflare Registrar at all.
      - `extension_disallows_registration`: The extension's registry has temporarily or permanently frozen new registrations.
      - `domain_premium`: The domain is premium priced. Premium registration is not currently supported by this API.
      - `domain_unavailable`: The domain appears unavailable.

      - `"extension_not_supported_via_api"`

      - `"extension_not_supported"`

      - `"extension_disallows_registration"`

      - `"domain_premium"`

      - `"domain_unavailable"`

    - `tier?: "standard" | "premium"`

      The pricing tier for this domain. Always present when `registrable` is `true`;
      defaults to `standard` for most domains. May be absent when `registrable`
      is `false`.

      - `standard`: Standard registry pricing
      - `premium`: Premium domain with higher pricing set by the registry

      - `"standard"`

      - `"premium"`

### Registrar Check Response

- `RegistrarCheckResponse`

  Contains the availability check results.

  - `domains: Array<Domain>`

    Array of domain availability results. Domains on unsupported
    extensions are included with `registrable: false` and a `reason`
    field. Malformed domain names may be omitted.

    - `name: string`

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

    - `registrable: boolean`

      Indicates whether this domain can be registered programmatically through this API based on a real-time registry check.

      - `true`: Domain is available for registration. The `pricing` object will be included.
      - `false`: Domain is not available. See the `reason` field for why. `tier` may still be present on some non-registrable results, such as premium domains.

    - `pricing?: Pricing`

      Annual pricing information for a registrable domain. This object is only
      present when `registrable` is `true`. All prices are per year and returned
      as strings to preserve decimal precision.

      `registration_cost` and `renewal_cost` are frequently the same value, but
      may differ — especially for premium domains where registries set different
      rates for initial registration vs. renewal. For a multi-year registration
      (e.g., 4 years), the first year is charged at `registration_cost` and each
      subsequent year at `renewal_cost`. Registry pricing may change over time;
      the values returned here reflect the current registry rate. Premium pricing
      may be surfaced by Search and Check, but premium registration is not currently
      supported by this API.

      - `currency: string`

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

      - `registration_cost: string`

        The first-year cost to register this domain. For premium domains
        (`tier: premium`), this price is set by the registry and may be
        significantly higher than standard pricing. For multi-year
        registrations, this cost applies to the first year only; subsequent
        years are charged at `renewal_cost`.

      - `renewal_cost: string`

        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?: "extension_not_supported_via_api" | "extension_not_supported" | "extension_disallows_registration" | 2 more`

      Present only when `registrable` is `false`. Explains why the domain cannot be registered via this API.

      - `extension_not_supported_via_api`: Cloudflare Registrar supports this extension in the dashboard but it is not yet available for programmatic registration via this API. The user can register via `https://dash.cloudflare.com/{account_id}/domains/registrations`.
      - `extension_not_supported`: This extension is not supported by Cloudflare Registrar at all.
      - `extension_disallows_registration`: The extension's registry has temporarily or permanently frozen new registrations. No registrar can register domains on this extension at this time.
      - `domain_premium`: The domain is premium priced. Premium registration is not currently supported by this API.
      - `domain_unavailable`: The domain is already registered, reserved, or otherwise not available on a supported extension.

      - `"extension_not_supported_via_api"`

      - `"extension_not_supported"`

      - `"extension_disallows_registration"`

      - `"domain_premium"`

      - `"domain_unavailable"`

    - `tier?: "standard" | "premium"`

      The pricing tier for this domain. Always present when `registrable` is `true`; defaults to `standard` for most domains. May be absent when `registrable` is `false`.

      - `standard`: Standard registry pricing
      - `premium`: Premium domain with higher pricing set by the registry

      - `"standard"`

      - `"premium"`

# Domains

## List domains

`client.registrar.domains.list(DomainListParamsparams, RequestOptionsoptions?): SinglePage<Domain>`

**get** `/accounts/{account_id}/registrar/domains`

List domains handled by Registrar.

### Parameters

- `params: DomainListParams`

  - `account_id: string`

    Identifier

### Returns

- `Domain`

  - `id?: string`

    Domain identifier.

  - `available?: boolean`

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

  - `can_register?: boolean`

    Indicates if the domain can be registered as a new domain.

  - `created_at?: string`

    Shows time of creation.

  - `current_registrar?: string`

    Shows name of current registrar.

  - `expires_at?: string`

    Shows when domain name registration expires.

  - `locked?: boolean`

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

  - `registrant_contact?: RegistrantContact`

    Shows contact information for domain registrant.

    - `address: string`

      Address.

    - `city: string`

      City.

    - `country: string | null`

      The country in which the user lives.

    - `first_name: string | null`

      User's first name

    - `last_name: string | null`

      User's last name

    - `organization: string`

      Name of organization.

    - `phone: string | null`

      User's telephone number

    - `state: string`

      State.

    - `zip: string | null`

      The zipcode or postal code where the user lives.

    - `id?: string`

      Contact Identifier.

    - `address2?: string`

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

    - `email?: string`

      The contact email address of the user.

    - `fax?: string`

      Contact fax number.

  - `registry_statuses?: string`

    A comma-separated list of registry status codes. A full list of status codes can be found at [EPP Status Codes](https://www.icann.org/resources/pages/epp-status-codes-2014-06-16-en).

  - `supported_tld?: boolean`

    Whether a particular TLD is currently supported by Cloudflare Registrar. Refer to [TLD Policies](https://www.cloudflare.com/tld-policies/) for a list of supported TLDs.

  - `transfer_in?: TransferIn`

    Statuses for domain transfers into Cloudflare Registrar.

    - `accept_foa?: "needed" | "ok"`

      Form of authorization has been accepted by the registrant.

      - `"needed"`

      - `"ok"`

    - `approve_transfer?: "needed" | "ok" | "pending" | 3 more`

      Shows transfer status with the registry.

      - `"needed"`

      - `"ok"`

      - `"pending"`

      - `"trying"`

      - `"rejected"`

      - `"unknown"`

    - `can_cancel_transfer?: boolean`

      Indicates if cancellation is still possible.

    - `disable_privacy?: "needed" | "ok" | "unknown"`

      Privacy guards are disabled at the foreign registrar.

      - `"needed"`

      - `"ok"`

      - `"unknown"`

    - `enter_auth_code?: "needed" | "ok" | "pending" | 2 more`

      Auth code has been entered and verified.

      - `"needed"`

      - `"ok"`

      - `"pending"`

      - `"trying"`

      - `"rejected"`

    - `unlock_domain?: "needed" | "ok" | "pending" | 2 more`

      Domain is unlocked at the foreign registrar.

      - `"needed"`

      - `"ok"`

      - `"pending"`

      - `"trying"`

      - `"unknown"`

  - `updated_at?: string`

    Last updated.

### Example

```node
import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const domain of client.registrar.domains.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(domain.id);
}
```

#### 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": [
    {
      "id": "ea95132c15732412d22c1476fa83f27a",
      "available": false,
      "can_register": false,
      "created_at": "2018-08-28T17:26:26Z",
      "current_registrar": "Cloudflare",
      "expires_at": "2019-08-28T23:59:59Z",
      "locked": false,
      "registrant_contact": {
        "address": "123 Sesame St.",
        "city": "Austin",
        "country": "US",
        "first_name": "John",
        "last_name": "Appleseed",
        "organization": "Cloudflare, Inc.",
        "phone": "+1 123-123-1234",
        "state": "TX",
        "zip": "12345",
        "id": "ea95132c15732412d22c1476fa83f27a",
        "address2": "Suite 430",
        "email": "user@example.com",
        "fax": "123-867-5309"
      },
      "registry_statuses": "ok,serverTransferProhibited",
      "supported_tld": true,
      "transfer_in": {
        "accept_foa": "needed",
        "approve_transfer": "unknown",
        "can_cancel_transfer": true,
        "disable_privacy": "ok",
        "enter_auth_code": "needed",
        "unlock_domain": "ok"
      },
      "updated_at": "2018-08-28T17:26:26Z"
    }
  ],
  "success": true,
  "result_info": {
    "count": 1,
    "page": 1,
    "per_page": 20,
    "total_count": 2000
  }
}
```

## Get domain

`client.registrar.domains.get(stringdomainName, DomainGetParamsparams, RequestOptionsoptions?): DomainGetResponse | null`

**get** `/accounts/{account_id}/registrar/domains/{domain_name}`

Show individual domain.

### Parameters

- `domainName: string`

  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.

- `params: DomainGetParams`

  - `account_id: string`

    Identifier

### Returns

- `DomainGetResponse = unknown`

### Example

```node
import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

const domain = await client.registrar.domains.get('example.com', {
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

console.log(domain);
```

#### 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": {},
  "success": true
}
```

## Update domain

`client.registrar.domains.update(stringdomainName, DomainUpdateParamsparams, RequestOptionsoptions?): DomainUpdateResponse | null`

**put** `/accounts/{account_id}/registrar/domains/{domain_name}`

Update individual domain.

### Parameters

- `domainName: string`

  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.

- `params: DomainUpdateParams`

  - `account_id: string`

    Path param: Identifier

  - `auto_renew?: boolean`

    Body param: Auto-renew controls whether subscription is automatically renewed upon domain expiration.

  - `locked?: boolean`

    Body param: Shows whether a registrar lock is in place for a domain.

  - `privacy?: boolean`

    Body param: Privacy option controls redacting WHOIS information.

### Returns

- `DomainUpdateResponse = unknown`

### Example

```node
import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

const domain = await client.registrar.domains.update('example.com', {
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

console.log(domain);
```

#### 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": {},
  "success": true
}
```

## Domain Types

### Domain

- `Domain`

  - `id?: string`

    Domain identifier.

  - `available?: boolean`

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

  - `can_register?: boolean`

    Indicates if the domain can be registered as a new domain.

  - `created_at?: string`

    Shows time of creation.

  - `current_registrar?: string`

    Shows name of current registrar.

  - `expires_at?: string`

    Shows when domain name registration expires.

  - `locked?: boolean`

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

  - `registrant_contact?: RegistrantContact`

    Shows contact information for domain registrant.

    - `address: string`

      Address.

    - `city: string`

      City.

    - `country: string | null`

      The country in which the user lives.

    - `first_name: string | null`

      User's first name

    - `last_name: string | null`

      User's last name

    - `organization: string`

      Name of organization.

    - `phone: string | null`

      User's telephone number

    - `state: string`

      State.

    - `zip: string | null`

      The zipcode or postal code where the user lives.

    - `id?: string`

      Contact Identifier.

    - `address2?: string`

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

    - `email?: string`

      The contact email address of the user.

    - `fax?: string`

      Contact fax number.

  - `registry_statuses?: string`

    A comma-separated list of registry status codes. A full list of status codes can be found at [EPP Status Codes](https://www.icann.org/resources/pages/epp-status-codes-2014-06-16-en).

  - `supported_tld?: boolean`

    Whether a particular TLD is currently supported by Cloudflare Registrar. Refer to [TLD Policies](https://www.cloudflare.com/tld-policies/) for a list of supported TLDs.

  - `transfer_in?: TransferIn`

    Statuses for domain transfers into Cloudflare Registrar.

    - `accept_foa?: "needed" | "ok"`

      Form of authorization has been accepted by the registrant.

      - `"needed"`

      - `"ok"`

    - `approve_transfer?: "needed" | "ok" | "pending" | 3 more`

      Shows transfer status with the registry.

      - `"needed"`

      - `"ok"`

      - `"pending"`

      - `"trying"`

      - `"rejected"`

      - `"unknown"`

    - `can_cancel_transfer?: boolean`

      Indicates if cancellation is still possible.

    - `disable_privacy?: "needed" | "ok" | "unknown"`

      Privacy guards are disabled at the foreign registrar.

      - `"needed"`

      - `"ok"`

      - `"unknown"`

    - `enter_auth_code?: "needed" | "ok" | "pending" | 2 more`

      Auth code has been entered and verified.

      - `"needed"`

      - `"ok"`

      - `"pending"`

      - `"trying"`

      - `"rejected"`

    - `unlock_domain?: "needed" | "ok" | "pending" | 2 more`

      Domain is unlocked at the foreign registrar.

      - `"needed"`

      - `"ok"`

      - `"pending"`

      - `"trying"`

      - `"unknown"`

  - `updated_at?: string`

    Last updated.

### Domain Get Response

- `DomainGetResponse = unknown`

### Domain Update Response

- `DomainUpdateResponse = unknown`

# Registrations

# Registration Status

## Get Registration Status

`client.registrar.registrationStatus.get(stringdomainName, RegistrationStatusGetParamsparams, RequestOptionsoptions?): WorkflowStatus`

**get** `/accounts/{account_id}/registrar/registrations/{domain_name}/registration-status`

Returns the current status of a domain registration workflow.

Use this endpoint to poll for completion when the POST response
returned `202 Accepted`. The URL is provided in the `links.self`
field of the workflow status response.

Poll this endpoint until the workflow reaches a terminal state or a
state that requires user attention.

**Terminal states:** `succeeded` and `failed` are terminal and always
have `completed: true`.

**Non-terminal states:**

- `action_required` has `completed: false` and will not resolve on its
  own. The workflow is paused pending user intervention.
- `blocked` has `completed: false` and indicates the workflow is waiting
  on a third party such as the extension registry or losing registrar.
  Continue polling while informing the user of the delay.

Use increasing backoff between polls. When `state: blocked`, use a
longer polling interval and do not poll indefinitely.

A naive polling loop that only checks `completed` can run indefinitely
when `state: action_required`. Break explicitly on `action_required`:

```js
let status;
do {
  await new Promise(r => setTimeout(r, 2000));
  status = await cloudflare.request({
    method: 'GET',
    path: reg.result.links.self,
  });
} while (
  !status.result.completed &&
  status.result.state !== 'action_required'
);

if (status.result.state === 'action_required') {
  // Surface context.action and context.confirmation_sent_to to the user.
  // Do not re-submit the registration request.
}
```

### Parameters

- `domainName: string`

  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.

- `params: RegistrationStatusGetParams`

  - `account_id: string`

    Identifier

### 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<string, unknown>`

    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

```node
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.registrationStatus.get('example.com', {
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

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
}
```

# Update Status

## Get Update Status

`client.registrar.updateStatus.get(stringdomainName, UpdateStatusGetParamsparams, RequestOptionsoptions?): WorkflowStatus`

**get** `/accounts/{account_id}/registrar/registrations/{domain_name}/update-status`

Returns the current status of a domain update workflow.

Use this endpoint to poll for completion when the PATCH response
returned `202 Accepted`. The URL is provided in the `links.self`
field of the workflow status response.

Poll this endpoint until the workflow reaches a terminal state or a
state that requires user attention.

Use increasing backoff between polls. When the workflow remains blocked
on a third party, use a longer polling interval and do not poll indefinitely.

### Parameters

- `domainName: string`

  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.

- `params: UpdateStatusGetParams`

  - `account_id: string`

    Identifier

### 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<string, unknown>`

    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

```node
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.updateStatus.get('example.com', {
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

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
}
```