Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

# About the Domain Search API

The Domain Search API allows you to retrieve suggestions for domains that are
spot-on for your customers' sites and check the availability of a specific
domain.

With the Domain Search API you can:

- Check whether a specific domain is available for purchase.
- Generate suggestions for available domains.

You can use the
[Registered Domains API](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::8c2a0eda-61a0-45d5-aa74-cd791eae0857*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/registered-domains/introduction)
to purchase domains through Wix. Learn more about managing DNS zones with the
[Domain DNS API](fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/domain-dns/introduction).
If you've bought a domain externally, you can connect it to the relevant Wix
site with the
[Connected Domains API](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::98fcf075-2739-4ef7-b0b3-4d2b69e8b2f8*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/connected-domains/introduction).

## Before you begin

+ Not all TLDs can be registered through Wix. Contact the
  Wix B2B team at [bizdev@wix.com](fallback::mailto:bizdev@wix.com) for more information.
+ If you want to register a domain to a Wix site, the site must have an active
  [Premium plan](fallback::https://support.wix.com/en/article/upgrading-your-site-to-premium-3066683).
  Learn more about
  [registering domains through Wix](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::8c2a0eda-61a0-45d5-aa74-cd791eae0857*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/registered-domains/introduction).

## Use cases

+ [Discover and register a domain](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::033721bb-25a4-4aab-96f7-43eba8d53928#discover-and-register-a-domain*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/domain-search/sample-flows#discover-and-register-a-domain)
+ [Check a domain's availability and register it](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::033721bb-25a4-4aab-96f7-43eba8d53928#check-a-domains-availability-and-register-it*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/domain-search/sample-flows#check-a-domains-availability-and-register-it)

## Terminology

+ __Domain__: Domain name including [Top-level domain](fallback::https://en.wikipedia.org/wiki/Top-level_domain) (TLD).
+ __Suggestion__: A suggested domain that's available for purchase.
+ __Registered domain__: Domain that's purchased, registered, and billed
  through Wix.
+ __External domain__: Domain that has been purchased through an external
  provider, not Wix. You can use the Connected Domains API to connect external domains to Wix sites.
+ __Account__: Wix account that includes access to associated sites.
  + __Team account__: Account type that supports collaborative work by having
    multiple sets of login credentials. This is especially helpful for agencies
    and resellers when managing a large number of customer sites. In Wix Studio
    team accounts are called workspaces. An agency may have multiple workspaces
    in Wix Studio, while in Wix Editor they're limited to a single team account.
  + __Sub-account__: Account that's contained within another account, forming a
    hierarchical structure. The owners of the sub-account are only able to
    interact with sites that belong to the sub-account. This setup is
    particularly useful for agencies and resellers since it limits client access
    to relevant sites only.

# Sample Use Cases & Flows: Domain Search

This article shares possible use cases your app could support, as well as example flows.
You're certainly not limited to these use cases, but they can be a helpful jumping off point
as you plan your app's implementation.

## Discover and register a domain

Your app could help site owners identify an available, spot-on domain.
Then, you could purchase the domain for them and assign it to their site.

To discover and register a domain:

1. Call [Suggest Domains](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::9b111ca5-559f-4cf7-892d-d33fc8e2080fslug::suggestion-object*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/domain-search/suggestion-v2/suggestion-object)
    to retrieve a list of relevant available domains.
1. Display the suggestions to the site owners and let them select their preferred choice.
1. Optional: In case the relevant site is a free Wix site, use the
   [Resellers API](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::fa07fab0-5daa-471e-ba80-727e944bb2dbslug::create-package-v2*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/resellers/packages-and-product-instances/create-package-v2)
   to assign a Premium plan to it. Make sure to save the `productInstanceId`.
1. Use the [Resellers API](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::fa07fab0-5daa-471e-ba80-727e944bb2dbslug::create-package-v2*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/resellers/packages-and-product-instances/create-package-v2)
   to create a product instance for the relevant domain TLD and privacy.
1. Register the domain through Wix by calling
    [Create Registered Domain](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::3bcedc58-9190-4d70-b785-538b975d1b6eslug::create-registered-domain*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/registered-domains/registered-domain-v1/create-registered-domain).
    Make sure to pass a site ID to assign it to the relevant Wix site.
1. Call [Get Registered Domain](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::3bcedc58-9190-4d70-b785-538b975d1b6eslug::get-registered-domain*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/registered-domains/registered-domain-v1/get-registered-domain)
    in regular intervals to confirm that the registered domain's `status` has changed to `"ACTIVE"`.

## Check a domain's availability and register it

Your app could help the site owner check the availability of their favorite
domain. Then, you could purchase the domain for them and assign it to their
site.

To check a domain's availability and register it:

1. Ask the site owners what their favorite domain is.
1. Call [Check Domain Availability](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::70cf9a1f-2099-4419-916d-a3c2f192f595slug::check-domain-availability*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/domain-search/availability-v2/check-domain-availability)
    to verify that the domain is still available. If its isn't available, start
    over or follow the
    [flow above](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::033721bb-25a4-4aab-96f7-43eba8d53928#discover-and-register-a-domain*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/domain-search/sample-flows#discover-and-register-a-domain).
1. Optional: In case the relevant site is a free Wix site, use the
   [Resellers API](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::fa07fab0-5daa-471e-ba80-727e944bb2dbslug::create-package-v2*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/resellers/packages-and-product-instances/create-package-v2)
   to assign a Premium plan to it. Make sure to save the `productInstanceId`.
1. Use the [Resellers API](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::fa07fab0-5daa-471e-ba80-727e944bb2dbslug::create-package-v2*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/resellers/packages-and-product-instances/create-package-v2)
   to create a product instance for the relevant domain TLD and privacy.
1. Register the domain through Wix by calling
    [Create Registered Domain](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::3bcedc58-9190-4d70-b785-538b975d1b6eslug::create-registered-domain*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/registered-domains/registered-domain-v1/create-registered-domain).
    Make sure to pass a site ID to assign it to the relevant Wix site.
1. Call [Get Registered Domain](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::3bcedc58-9190-4d70-b785-538b975d1b6eslug::get-registered-domain*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/registered-domains/registered-domain-v1/get-registered-domain)
    in regular intervals to confirm that the registered domain's `status` has changed to `"ACTIVE"`.

# Domain Search Errors

This article outlines error messages that might be issued when calling endpoints of the Domain Search API.

## Check Domain Availability Errors

The [Check Domain Availability](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::70cf9a1f-2099-4419-916d-a3c2f192f595slug::check-domain-availability*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/domain-search/availability-v2/check-domain-availability)
endpoint might issue the following error message:

| <div style="width:200px">HTTP status</div> | <div style="width:250px">Error code</div> | <div style="width:280px">Error message </div> | <div style="width:300px">Troubleshooting </div> |
| --------------------------- | ----------------------------------- | ------------------------------------------------------------ | ------------------------------ |
| `INVALID_ARGUMENT (400)` | `INVALID_DOMAIN` | Failed to extract root domain from `<domain>`, or TLD is missing or invalid. | Start a new query including a domain name and supported TLD. Domain name and TLD must be separated by a dot. For example, `my-new-domain.com`. |

## Suggest Domains Errors

The [Suggest Domains](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::9b111ca5-559f-4cf7-892d-d33fc8e2080fslug::suggest-domains*fallback::https://dev.wix.com/docs/rest/api-reference/account-level-apis/domain-search/suggestion-v2/suggest-domains)
endpoint might issue the following error messages:

| <div style="width:200px">HTTP status</div> | <div style="width:250px">Error code</div> | <div style="width:280px">Error message </div> | <div style="width:300px">Troubleshooting </div> |
| --------------------------- | ----------------------------------- | ------------------------------------------------------------ | ------------------------------ |
| `INVALID_ARGUMENT (400)` | `INVALID_QUERY` | Query `<query>` has invalid characters. Only alphanumeric values, hyphens, dots, and spaces are supported. | Start a new query using only alphanumeric values, hyphens, dots, and spaces. |
| `INVALID_ARGUMENT (400)` | `INVALID_TLD_FORMAT` | At least one element of the `tlds` array has an invalid format. | Start a new query using the correct TLD format. TLDs must not include the dot. For example, `com`, not `.com`. |
| `INVALID_ARGUMENT (400)` | `TLD_NOT_SUPPORTED` | Unsupported TLDs `<tlds>` found. | Start a new query with supported TLDs such as `com`, `net`, and `org`. Contact the [Wix B2B sales team](fallback::mailto:bizdev@wix.com) for more information. |


Number of domains returned in the response.

count

Cursors to navigate through the result pages using `next` and `prev`. Returned if cursor paging is used.

Indicates if there are more results after the current page.
If `true`, another page of results can be retrieved.
If `false`, this is the last page.

hasNext

CursorPagingMetadata

Cursor pointing to next page in the list of results.

Cursors

Pointer to the next or previous page in the list of results.

You can get the relevant cursor token
from the `pagingMetadata` object in the previous call's response.
Not relevant for the first request.

cursor

Number of domains to load.

Min: `0`
Max: `20`

limit

CursorPaging

domain

DomainSuggestion

Number of domain suggestions to return.

Min: `1`
Max: `20`
Default: `10`
Note: limit field is deprecated from Aug 1, 2024, use `paging.limit` instead.

Input to base your domain suggestions on. May include
letters, numbers, spaces, dots, and hyphens. Must not include the TLD.

Min: 3 characters
Max: 100 characters

query

[Top-level domains](https://en.wikipedia.org/wiki/Top-level_domain). Must
not include the dot. For example, `com`, not `.com`. Not all TLDs can be
connected to Wix sites. Supported TLDS include `com`, `net`, and `org`.
Contact the [Wix B2B sales team](mailto:bizdev@wix.com) for more
information.

Max: 10 TLDs

tlds

SuggestDomainsRequest

Metadata about the returned list of suggested domains.

suggestions

SuggestDomainsResponse

value

BoolValue

Int32Value

StringValue

Suggests domains that are available for purchase, based on the provided
`query` input.


You may use this endpoint to get inspired and then call
[Check Domain Availability](https://dev.wix.com/api/rest/account-level-apis/domain-search/check-domain-availability)
to check whether a specific variation of the suggestions is also available
for purchsase.

The `tlds` must not include the dot. For example, `com` and not `.com`.

> __Important:__ This call requires an account level API key and cannot be authenticated with the standard authorization header.

Suggestion Object