Use the Domains API to manage the relationship between your domains and Pages sites programmatically. The API supports creating, listing, and getting details for domains and domain associations.

Glossary

This glossary of terms can be applied to domains across your account, no matter what product you're using them with and whether you manage domains in the UI or API.

Integrating Domains with Pages

This section walks through connecting domains to your Pages sites and other additional domain settings.

Prior to deployment, your domain must be configured for use.

Each domain you have configured in your account will be visible in the domains table.

Domain Assignment

Once you have added a domain to Yext, you can "assign" it to your desired site via Site Configuration. Each domain configured in your account will be available in the Domain dropdown.

To select a domain, simply click on one of the options. This step is necessary before updating your DNS configuration. A successful deployment must be published to production in order to assign a domain.

Placeholder Domain Configuration

When you deploy a website using Yext, by default, we provision you with a "placeholder" production domain. This is a Yext-provisioned URL at [example].pgsdemo.com. This convenience allows you to immediately view your deployed content and share it with your team and stakeholders.

You can customize your placeholder domain at any time directly in the Site Configuration screen of your site as necessary to tailor it to your organization's requirements. This customization is particularly useful for denoting if a website is purely for QA or testing purposes.

Requirements for the placeholder domain configuration:

1. The maximum character length limit is 62 characters.
2. It needs to live off of the .pgsdemo.com wildcard.

Additionally, each branch staging URL is derived from a combination of the production placeholder URL and the name of the branch itself. Due to this combination, it's possible to encounter a staging URL that exceeds the allowed length, resulting in a "This site can't be reached" error. If you encounter this issue, try shortening the length of your placeholder domain.

Domain Aliases

If you want your website to be served at multiple domains, you can configure domain aliases directly within Site Configuration as well. To alias your content, add each alias through the same domain setup options as your primary domain, whether via the UI or API.

As needed on the frontend, you can programmatically determine whether you are being served content at a primary vs. alias domain by accessing the PRODUCTION_DOMAINS window object.

console.log(window.PRODUCTION_DOMAINS)

// result
{
  "primary": "test.yext.com",
  "aliases": [
    "alias1.yext.com",
    "alias2.yext.com"
  ]
}

Domain Reassignment

If necessary, you can also update your site to deploy your content to a different domain at any time. This is useful in two scenarios:

1. Domain Changes — If you need to update the domain at which your content is served, you can simply assign a different domain to your site. For example, a domain rebrand (brand.com → rebrand.com) or domain extension update (brand.com → brand.co.uk).
2. Domain Migrations — Domains that are already in use by another site can be "migrated" to your current site. This is particularly useful if you are rebuilding a Classic Pages site on the new Pages architecture (see the Types of Pages reference document), and need to point the domain to your new site.

To reassign the domain from a Classic Site:

1. First ensure that your desired deployment is already published to production!

2. Navigate to the Site Configuration page for your site. Select the desired domain from the domains dropdown; it should be visible under the "In Use Domains" section. Then click "Save".

   

3. You will be prompted to confirm you wish to reassign this domain to your site. Confirm by entering the name of the domain into the text input field, and click "Continue".
4. Once you initiate the cutover, Yext will initiate the domain reassignment process on the backend. It may take up to a few minutes before you see content from the new site serving at the domain. While the reassignment is taking place, the content from the Classic site will continue to be served (guaranteeing zero downtime).

5. Once the cutover is complete, the Classic site will no longer be connected to the domain. If you need to revert this operation, you have the ability to select the same domain from the Classic site. Simply select the in-use domain to reassign the domain back to the Classic site. Similar to before, the reassignment process can take up to a few minutes before the Classic content is serving again.

   

API Example Usage

I have a single domain I want to attach to the site I've built

1. Find the site to which you wish to attach the domain and derive the resource identifier. It will be of the format accounts/<business-id>/sites/<site-id>, where both the business ID and the site ID can be found in the URL for the page: https://www.yext.com/s/<business-id>/yextsites/<site-id>/overview
2. Send a POST API call to https://api.yextapis.com/v2/accounts/<business-id>/domains with the domain setup. For reference, see the expected request information in the Domain: Create endpoint. For simplicity, use the HTTP validation type with managed SSL.
3. Use the GET API calls to https://api.yextapis.com/v2/accounts/<business-id>/domains/<domain-id> to get the status of the domain and the ownership verification steps. You can proceed to the next step when the domain is in an ACTIVE state.
   • During the PENDING_VERIFICATION state, you will need to verify the ownership of the domain through a CNAME record, TXT record, or HTTP validation.
   • During the PENDING_CREATION state or CREATION state, you will need to verify the ownership of the domain to the certificate authority. If the CNAME record was used for ownership verification, no additional steps are needed; you'll just need to wait for verification.
4. Send a POST API call to https://api.yextapis.com/v2/accounts/<business-id>/domains/<domain-id>/associations using the site identifier from step 1. This domain must be set as primary with primary: true in the request. For more information on making the request, see the Domain Association: Create endpoint.
5. Now the domain will be serving the content at the site!

I currently have my domain attached to another vendor, but am building a site on Yext. How do I ensure I have a zero-downtime cutover?

1. Send a POST API call to https://api.yextapis.com/v2/accounts/<business-id>/domains with the domain setup. For reference, see the expected request information in the Domain: Create endpoint. To ensure no downtime, use TXT for the validation method and managed SSL.
2. Use the GET API calls to https://api.yextapis.com/v2/accounts/<business-id>/domains/<domain-id> to get the status of the domain and the ownership verification steps. You can proceed to the next step when the domain is in an ACTIVE state and ready to cutover.
   • During the PENDING_VERIFICATION state, you will need to verify the ownership of the domain through a TXT record or HTTP validation.
   • During the PENDING_CREATION state or CREATION state, you will need to verify the ownership of the domain with the certificate authority. This will include adding the TXT records presented in the hostname validation in the response to the GET requests.
3. Find the site to which you wish to attach the domain and derive the resource identifier. It will be of the format accounts/<business-id>/sites/<site-id>, where both the business ID and the site ID can be found in the URL for the page: https://www.yext.com/s/<business-id>/yextsites/<site-id>/overview.
4. Send a POST API call to https://api.yextapis.com/v2/accounts/<business-id>/domains/<domain-id>/associations using the site identifier from step 1. This domain will need to be set as primary with primary: true in the request. For more information on making the request, see the Domain Association: Create endpoint.
5. Add the CNAME record from the GET API calls when ready to cutover. There should be zero downtime.
6. Now the domain will be serving the content at the site!

I am a reseller and I want to host the sites I have built on a wildcard domain

1. Send a POST API call to https://api.yextapis.com/v2/accounts/<business-id>/domains with the domain setup. For reference, see the expected request information in the Domain: Create endpoint. As part of this request, the wildcard flag must be set to true and TXT validation is required. For serving the content, you will still need to set up the CNAME from the wildcard. For example, if the hostname is example.com, the CNAME must be set on the *.example.com record.
2. Use the GET API calls to https://api.yextapis.com/v2/accounts/<business-id>/domains/<domain-id> to get the status of the domain and the ownership verification steps. You can proceed to the next step when the domain is in an ACTIVE state and ready to cutover.
   • During the PENDING_VERIFICATION state, you will need to verify the ownership of the domain through a TXT record or HTTP validation.
   • During the PENDING_CREATION state or CREATION state, you will need to verify the ownership of the domain to the certificate authority. This will include adding the TXT records presented in the hostname validation in the response to the GET requests.
3. Find your site that you wish to attach the domain to and derive the resource identifier. It will be of the format accounts/<business-id>/sites/<site-id>, where both the business ID and the site ID can be found in the URL for the page: https://www.yext.com/s/<business-id>/yextsites/<site-id>/overview.
4. Send a POST API call to https://api.yextapis.com/v2/accounts/<business-id>/domains/<domain-id>/associations using the site identifier from step 1. The hostname for this request can be anything that is one level above the wildcard hostname. For example, if the wildcard hostname were example.com, help.example.com would be valid for this request, whereas en.help.example.com would not. This domain must be set as primary with primary: true in the request. For more information on making the request, see the Domain Association: Create endpoint.
5. Now the domain will be serving the content at the site! Repeat the preceding two steps for any sites you wish to use with the wildcard.

My security practices only allow me to use Let's Encrypt and DigiCert as Certificate Authorities

1. Find your site that you wish to attach the domain to and derive the resource identifier. It will be of the format accounts/<business-id>/sites/<site-id>, where both the business ID and the site ID can be found in the URL for the page: https://www.yext.com/s/<business-id>/yextsites/<site-id>/overview
2. Send a POST API call to https://api.yextapis.com/v2/accounts/<business-id>/domains with the domain setup. For reference, see the expected request information in the Domain: Create endpoint. For simplicity, use the HTTP validation type with managed SSL. To not use Google Trust and set the certificate authority on the Yext-managed certificate, specify LETS_ENCRYPT as the certificate authority.
3. Use the GET API calls to https://api.yextapis.com/v2/accounts/<business-id>/domains/<domain-id> to get the status of the domain and the ownership verification steps. You can proceed to the next step when the domain is in an ACTIVE state.
   • During the PENDING_VERIFICATION state, you will need to verify the ownership of the domain through a CNAME record, TXT record, or HTTP validation.
   • During the PENDING_CREATION state or CREATION state, you will need to verify the ownership of the domain to the certificate authority. If the CNAME record was used for ownership verification, no additional steps are needed; you'll just need to wait for verification.
4. Send a POST API call to https://api.yextapis.com/v2/accounts/<business-id>/domains/<domain-id>/associations using the site identifier from step 1. This domain will need to be set as primary with primary: true in the request. For more information on making the request, see the Domain Association: Create endpoint.
5. Now the domain will be serving the content at the site!

I have a site, but I want to add other domains that serve the same content

1. Find the site to which you wish to attach the domain and derive the resource identifier. It will be of the format accounts/<business-id>/sites/<site-id>, where both the business ID and the site ID can be found in the URL for the page: https://www.yext.com/s/<business-id>/yextsites/<site-id>/overview
2. Send a POST API call to https://api.yextapis.com/v2/accounts/<business-id>/domains with the domain setup. For reference, see the expected request information in the Domain: Create endpoint. For simplicity, use the HTTP validation type with managed SSL.
3. Use the GET API calls to https://api.yextapis.com/v2/accounts/<business-id>/domains/<domain-id> to get the status of the domain and the ownership verification steps. You can proceed to the next step when the domain is in an ACTIVE state.
   • During the PENDING_VERIFICATION state, you will need to verify the ownership of the domain through a CNAME record, TXT record, or HTTP validation.
   • During the PENDING_CREATION state or CREATION state, you will need to verify the ownership of the domain to the certificate authority. If the CNAME record was used for ownership verification, no additional steps are needed; you'll just need to wait for verification.
4. Send a POST API call to https://api.yextapis.com/v2/accounts/<business-id>/domains/<domain-id>/associations using the site identifier from step 1. This domain must be set as primary with primary: true in the request. For more information on making the request, see the Domain Association: Create endpoint.
5. Now the domain will be serving the content at the site!
6. For additional domains, follow steps 1–4 again, except that during step 4, set the primary field to false. Each additional domain added here will be referred to as an alias and will signal to search engines that the canonical domain is the one added in step 4.

I accidentally deleted my domain. Can I get it back?

Each domain is unique for the hostname while it is active. However, if the domain is deleted, just recreate it and follow the same steps. Associations will need to be recreated as well. See the single domain example above.

I've moved to a new account, but my domain is stuck on my old account. How do I move it?

1. Create the same domain in the new account with the desired settings using the Domain: Create endpoint.
2. Follow all of the verification steps until you are presented with a MOVE_REQUIRED state.
3. At this point, send a PATCH request to the Domain endpoint with the parameter force set to true.
4. Now the domain will be moved to this account. Use the domain association endpoint to associate the domain with a new site in the new account.
5. The old domain will be left in the old account, but in a verification failed state. This domain can be deleted now. If the operation needs to be reversed, a patch request can be sent to the domain to repeat this process in reverse.

I have a legacy Pages 2.0 domain created prior to this new API. How do I migrate it?

1. Use the Migrate Legacy Pages Domain endpoint to kick off the migration process. The hostname at the end should match the domain you want to migrate. If the domain has a Pages CDN integration and domain accessible integration, both will be migrated to the new system.
2. All of the sites associated with that domain will automatically pick up on the changes to use the new domains API.

I want to create a Certificate Signing Request for a client for Custom SSL

1. Send a POST request to the Managed CSR: Create endpoint to create a managed CSR with all the relevant information.
2. Note the managed CSR ID in the response.
3. Copy the CSR from the response and unescape the newline characters to turn them into real newlines.
4. Provision a certificate with your desired certificate authority. The newlines must be escaped before adding it to the domain.
5. Create a new domain with the Domain: Create endpoint. But instead of putting managed_ssl in the body, use managed_csr and the fields specified in the Managed CSR section of the Domain SSL Configuration section. The managed CSR ID field should match the managed CSR ID from the response in the first step.
6. The domain will now be provisioned with the custom SSL.