About the Domain DNS API

With the Domain DNS API you can manage DNS zones in Google's Cloud DNS. This allows you to connect domains that you've registered through Wix to non-Wix websites. You can also use the Domain DNS API to manage DNS records for external domains that are connected by nameservers to Wix sites.

Using the Domain DNS API you can:

  • Preview DNS zones
  • Manage DNS zones in Google's Cloud DNS

Learn more about:

Before you begin

It’s important to note the following points before starting to code:

  • The Domain DNS API is accessible via API keys. You can't access this API with a standard Auth header. We recommend authenticating calls with an API key for your main account instead of using a key for the relevant sub-account. But the responses to calls remain consistent across API keys, provided you have the necessary permissions.
  • Wix limits DNS records to 50 values per type. External providers may support a different maximum number of DNS records for a specific type, Wix doesn't validate that you don't exceed these external limits.
  • You can only update DNS zones for external domains that are connected by nameservers to a Wix site. You can't use the Domain DNS API for external domains that are connected by pointing to a Wix site because the DNS isn't saved in Wix for this connection type.

Use cases

Terminology

  • Registered domain: Domain that's purchased, registered, and billed through Wix.
  • External domain: Domain that has been purchased through an external provider, not Wix.
  • Domain name: The domain name includes the top-level domain (TLD). Examples for TLDs are com, net, or org.
  • DNS record: Database record in the Domain Name System that's used to map a human-readable URL to an IP address.
  • DNS zone: A DNS zone is an administrative subdivision of the DNS namespace. When you Create a DNS zone the values are uploaded to Google's Cloud DNS.
  • 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.
Was this helpful?
Yes
No

Sample Use Cases & Flows: Domain DNS

This article shares a possible use case your implementation could support, as well as a sample flow. You're not limited to this use case, but it can be a helpful jumping off point for your planning.

Update DNS records for a registered domain

You could purchase a domain through Wix and then update the MX and TXT records. This allows you to connect the domain to a website that isn't build on Wix.

To update the DNS records for a registered domain:

  1. Optional: In case the relevant site is a free Wix site, use the Resellers API to assign a Premium plan to it. Make sure to save the productInstanceId.
  2. Use the Resellers API to create a product instance for the relevant domain TLD and privacy. Don't assign the product instance to a site, but keep it floating in the relevant account.
  3. Call Create Registered Domain to start the domain registration process through Wix.
  4. Use Get Registered Domain to confirm that the status has changed to "PENDING_REGISTRATION".
  5. Call Update Dns Zone to change the MX and TXT records in Google's Cloud DNS.
  6. Connect the domain to the external site.

Connect an external domain by nameservers to a Wix site

You could help Wix site owners connect an external domain by nameservers to their site. Note that you can't use Update DNS Zone for external domains that are connected by pointing.

To connect an external domain by nameservers to a Wix site:

  1. Optional: In case the relevant site is a free Wix site, use the Resellers API to assign a Premium plan to it.
  2. Register the domain through an external provider.
  3. Call Create Connected Domain to start the connection process. Make sure to use {"connectionType": "NAMESERVERS"}.
  4. Use Get Connected Domain Setup Info to retrieve the new DNS record values. You find them in connectedDomainSetupInfo.pointingRecords.aRecord.values and connectedDomainSetupInfo.pointingRecords.cnameRecord.value.
  5. Use Update Dns Zone to change the A and CNAME records in Google's Cloud DNS.
  6. Call Get Connected Domain to monitor the connected domain's dnsPropagationStatus and confirm that it changes to "COMPLETED".
Was this helpful?
Yes
No

Domain DNS Errors

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

Create DNS Zone Errors

Create DNS Zone might issue the following error messages:

HTTP status
Error code
Error message
Troubleshooting
NOT_FOUND (404)USER_ID_NOT_FOUNDUser id not found in request context.Make sure to pass the correct authorization header.
NOT_FOUND (404)TARGET_ACCOUNT_NOT_FOUNDTarget account id not found in request context.Make sure to pass the correct account ID in the header of the call.
NOT_FOUND (404)DNS_ZONE_NOT_FOUNDNo dns zone found for domain name <domainName>.You must pass a dnsZone object when setting up a DNS zone in Google's Cloud DNS.
FAILED_PRECONDITION (428)DOMAIN_NOT_PERMITTEDDomain <domain> is not permitted to target account.Make sure to pass the correct account ID in the header of the call. The target account must also have a Premium subscription that allows connecting a domain with the chosen TLD. See the Resellers API for more information.
FAILED_PRECONDITION (428)DOMAIN_ALREADY_EXISTSDomain <domain> already exists.You can create a DNS zone in Google's Cloud DNS that already exists.
FAILED_PRECONDITION (428)DOMAIN_DNS_EMPTY_RECORD_VALUEValue of record <recordType> is empty.You must pass values for each DNS record that you want to specify in Google's Cloud DNS.
FAILED_PRECONDITION (428)DOMAIN_MX_RECORD_VALUE_INVALIDValue of MX record <value> is invalid, it should start with a priority and then the mail server, for example "5 aspmx.l.google.com".Make sure to use this format "5 aspmx.l.google.com" when specifying the value of an MX record in Google's Cloud DNS.
FAILED_PRECONDITION (428)DOMAIN_CNAME_RECORD_HOSTNAME_INVALIDHost name of the CNAME record $value is invalid, it should end with the domain name but not equal to it, for example "en.domain.com".Make sure to use this format "en.domain.com" when specifying the value of a CNAME record in Google's Cloud DNS.
FAILED_PRECONDITION (428)DOMAIN_MX_RECORD_VALUE_INVALIDMultiple <recordType> records with the same hostName <hostName> not supported, the multiple values belong to the same hostName should be combined under one <recordType>.Make sure that you pass all DNS record values that belong to the same type in a single values array of the relevant records.type object. You can't pass multiple record objects with the same record type.

Update DNS Zone Errors

Update DNS Zone might issue the following error messages:

HTTP status
Error code
Error message
Troubleshooting
NOT_FOUND (404)USER_ID_NOT_FOUNDUser id not found in request context.Make sure to pass the correct authorization header.
NOT_FOUND (404)TARGET_ACCOUNT_NOT_FOUNDTarget account id not found in request context.Make sure to pass the correct account ID in the header of the call.
FAILED_PRECONDITION (428)DOMAIN_NOT_PERMITTEDDomain <domain> is not permitted to target account.Make sure to pass the correct account ID in the header of the call. The target account must also have a Premium subscription that allows connecting a domain with the chosen TLD. See the Resellers API for more information.
FAILED_PRECONDITION (428)DOMAIN_DNS_EMPTY_RECORD_VALUEValue of record <recordType> is empty.You must pass at least one value for each DNS record type that you want to specify in Google's Cloud DNS.
FAILED_PRECONDITION (428)DOMAIN_MX_RECORD_VALUE_INVALIDValue of MX record <value> is invalid, it should start with a priority and then the mail server, for example "5 aspmx.l.google.com".Make sure to use this format: "5 aspmx.l.google.com", when specifying the value of an MX record in Google's Cloud DNS.
FAILED_PRECONDITION (428)DOMAIN_CNAME_RECORD_HOSTNAME_INVALIDHost name of the CNAME record $value is invalid, it should end with the domain name but not equal to it, for example "en.domain.com".Make sure to use this format: "en.domain.com", when specifying the value of a CNAME record in Google's Cloud DNS.
FAILED_PRECONDITION (428)DOMAIN_MX_RECORD_VALUE_INVALIDMultiple <recordType> records with the same hostName <hostName> not supported, the multiple values belong to the same hostName should be combined under one <recordType>.Make sure that you pass all DNS record values that belong to the same DNS record type in the values array of the relevant record object. You can't pass multiple record objects that have the same record type.
Was this helpful?
Yes
No

Dns Zone Object

DNS zones hold information about the records that map a domain's URL to an IP address.

Attributes
domainNamestringformat HOSTNAME
Domain name including the TLD. Both root domains and subdomains are supported.

recordsArray <DnsRecord>maxItems 10
DNS records. You can only set up a single record object per DNS record type. If you want to specify multiple values for the same record type, you must save them in the values for the relevant type. Max: 10 DNS records
Was this helpful?
Yes
No

PostCreate Dns Zone

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates a DNS zone in Google's Cloud DNS.

If there is an existing DNS zone for the domain, it's deleted before the new zone is created.

The call is synchronous, that means it fails in case of an error on Google's side.

You can only set up a single record object per DNS record type. If you want to specify multiple values for the same record type, you must save them in the values for the relevant type.

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

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Domains
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
POST
https://www.wixapis.com/domains/v1/dns-zones

Was this helpful?
Yes
No

GetGet Dns Zone

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves the DNS zone belonging to the domain from Google's Cloud DNS.

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

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Domains
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
GET
https://www.wixapis.com/domains/v1/dns-zones/{domainName}

Was this helpful?
Yes
No

DeleteDelete Dns Zone

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Deletes a DNS zone in Google's Cloud DNS.

The call is synchronous, that means it fails in case of an error on Google's side.

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

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Domains
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
DELETE
https://www.wixapis.com/domains/v1/dns-zones/{domainName}

Was this helpful?
Yes
No

PatchUpdate Dns Zone

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Adds DNS records to and removes DNS records from a DNS zone in Google's Cloud DNS.

The call is synchronous, that means it fails in case of an error on Google's side.

You can only set up a single record object per DNS record type. If you want to specify multiple values for the same record type, you must save them in the values for the relevant type. This means, you must delete the relevant record and add a new addition object for this type to the request, in case you want to add values for an existing DNS record type.

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

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Domains
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
PATCH
https://www.wixapis.com/domains/v1/dns-zones/{domainName}

Was this helpful?
Yes
No

GetPreview Dns Zone

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Generates a preview for a DNS zone based on Google's Cloud DNS.

This includes calculating the A, CNAME, NS and SOA records. You can use this information to configure a domain from an external provider, before connecting it to a Wix site.

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

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Domains
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
GET
https://www.wixapis.com/domains/v1/dns-zones/{domainName}/preview

Was this helpful?
Yes
No