The Domains API supports three top-level resources: Domain, Domain Association, and Managed CSR. This reference describes the fields, states, and configurations for each.
Domain
Domains are a top-level resource within the Domains API. The domain object guides you through setting up the correct DNS configuration and generating an SSL certificate.
The following fields are defined on a domain object. They are available through the GET and LIST endpoints and are used during the creation process.
| Field | Description | Example Value |
|---|---|---|
Name name
|
The unique identifier for the domain. The domain will use a resource identifier that identifies it and indicates what business it belongs to. It will follow the format: /accounts/{business_id}/domains/{domain_id}. The domain ID will be in UUIDv7 format. |
/accounts/123456/domains/abcdf-12343-defsg-12345 |
Hostname hostname
|
The hostname that the domain will be accessed at. This is also the hostname for the generated SSL certificate. For a wildcard domain, this hostname can be specified without the asterisk. The asterisk will be added if the wildcard field is set to true. |
hitchhikers.yext.com |
Wildcard wildcard
|
A boolean value to indicate whether or not this domain will be a wildcard domain, meaning that all subdomains of the provided hostname will be served and a wildcard SSL certificate will be issued. For attaching specific subdomains to a wildcard domain, see the Domain Association section below. | false |
Destination destination
|
This value indicates what product and content this domain will be serving. The only available option is PAGES which indicates this domain will be serving site content through the Pages product. |
PAGES |
Integration Type integration_type
|
This indicates how the domain is set up. If you are bringing your own domain, this value will be USER_OWNED. USER_OWNED is the only integration currently supported for creation. If the value includes a LEGACY_ prefix, this indicates that the domain was migrated from the old system, so certain functionality will differ from regular USER_OWNED domains. LEGACY_YEXT_MANAGED refers to domains that were migrated from the old system to Domains API that used the legacy JS Snippet feature. |
USER_OWNED |
State state
|
This value indicates the state of the domain. See the Domain States section below for more information. | ACTIVE |
Ownership Verification ownership_verification
|
An object that returns the different methods and values that can be used for verifying ownership of the provided domain. Ownership is required for issuing an SSL certificate and creating a domain association. | See Domain Ownership Verification below |
SSL ssl
|
An object that returns information about the domain's SSL configuration. This includes fields such as the certificate authority, the validation method, and any ownership instructions needed for the domain. | See Domain SSL Configuration below |
Errors errors
|
An optional object returned if there are any asynchronous issues with the domain setup. The GET and LIST endpoints return this if the view mode is set to full. | |
Created Timestamp create_time
|
The UTC time when the domain was created. | "2025-01-07T18:48:38.390Z" |
Last Updated Timestamp update_time
|
The UTC time when the domain was last updated. | "2025-01-07T18:48:38.390Z" |
Deleted Timestamp delete_time
|
This is empty for any domain that has not been deleted. If this is provided, it is the UTC time when the domain was deleted. | "2025-01-07T18:48:38.390Z" |
Domain Ownership Verification
To verify ownership of a domain, the owner of the DNS configuration will need to use one of the following options to prove ownership to Yext: CNAME to the Bridge Domain, TXT records matching the ones generated, or an HTTP token served at a specific path.
| Field | Description | Example |
|---|---|---|
CNAME Target cname_target
|
The bridge domain that should be added as the CNAME record for the hostname being added for Pages. | a6482bws.yext.pgscdncf.com. |
TXT Domain txt_domain
|
The record identifier used along with the TXT value to prove ownership of the domain. | _yext-domain.<hostname> |
TXT Value txt_value
|
A unique identifier used as the value for TXT ownership verification. This should be the value in the DNS registrar with the TXT Domain being the key. | abcdef-1234-ghijk-2349 |
HTTP URI http_uri
|
The URL that needs to host the HTTP token if using HTTP verification. This URI must be accessible via HTTP; HTTP to HTTPS redirecting precludes this method from being used. | <hostname>/.well-known/yext-domain-challenge/abcdef-1234-ghijkl-1234 |
HTTP Body http_body
|
The body that needs to be returned from the HTTP URI path when a GET request is issued. | abcdef-1234-ghijkl-1234 |
Domain SSL Configuration
There are three different SSL options for domains.
- Managed SSL: The default provisioning option for new domains. This option will handle the entire SSL provisioning process with the provided parameters. The user will be responsible for adding any DNS or HTTP records to validate ownership with the certificate authority.
- Managed CSR: This option allows users to issue their own public certificate with their desired certificate authority. The user is responsible for setting up a certificate signing request object and providing the fields necessary for a certificate signing request. The private key used to generate the certificate will not be available to the user or Yext and will be stored in Cloudflare for use in the SSL handshake.
- Custom SSL Certificate: This option allows the user to have full control over the certificate generation lifecycle. The user is responsible for generating the private key, the certificate signing request, and the public certificate. These will all need to be provided during domain setup. Note: Yext will never store the private key provided at rest; it will be stored in Cloudflare, our CDN provider, for the SSL handshake.
Managed SSL
Some portions of the SSL for the domain are configurable and some are read-only.
| Field | Mutability | Description | Example |
|---|---|---|---|
Certificate Authority certificate_authority
|
Can read and write to this field during creation and for updates | The name of the certificate authority that will provision the certificate. The only options are Let's Encrypt or Google Trust Services (default). This field is only for domains that use managed SSL. | GOOGLE_TRUST |
Validation Method validation_method
|
Can read and write this field during creation. This field cannot be updated. | How Cloudflare and the certificate authority will verify ownership to provision the SSL certificate. HTTP and TXT are the only two options. HTTP validation is the simplest and works with the CNAME bridge. TXT validation allows for SSL issuance without pointing the domain at Yext, allowing for zero-downtime cutovers. All wildcard records are required to use TXT. | HTTP |
Hostname Validation hostname_validation
|
Read-only | Cloudflare provides this field to indicate what needs to be done in the DNS settings to verify hostname ownership with Cloudflare. If using the CNAME bridge, this will be done automatically. | |
| SSL Validation | Read-only | This field provides instructions from Cloudflare and the certificate authority on what to do in the DNS settings to provision the SSL certificate. If using the CNAME bridge, this will be done automatically. |
Managed CSR
| Field | Mutability | Description | Example |
|---|---|---|---|
Managed CSR ID managed_csr_id
|
Can read and write to this field during creation and for updates | The identifier for the managed CSR created with the managed CSR endpoints. This will instruct Cloudflare to use the private key generated with the CSR request and the provided public certificate. This value will be a UUIDv7 identifier. See the Managed CSR section below for more info. | abcd-def-ghi-jkl |
Custom Public Certificate custom_public_certificate
|
Can read and write this field during creation. This field cannot be updated. | The public certificate generated with the CSR referenced by the "Managed CSR ID". This value must be newline encoded. | |
Hostname Validation hostname_validation
|
Read-only | Cloudflare provides this field to indicate what needs to be done in the DNS settings to verify hostname ownership with Cloudflare. If using the CNAME bridge, this will be done automatically. |
Custom SSL
| Field | Mutability | Description | Example |
|---|---|---|---|
Public Certificate public_certificate
|
Can read and write to this field during creation and for updates | The public certificate for the domain being added. This value must be newline encoded, and the domain to which this is being added must be in the SANS of the public certificate. | |
Private Key private_key
|
Can read and write this field during creation. This field cannot be updated. | The corresponding private key for the provided public certificate. This value must be newline encoded. | |
Hostname Validation hostname_validation
|
Read-only | Cloudflare provides this field to indicate what needs to be done in the DNS settings to verify hostname ownership with Cloudflare. If using the CNAME bridge, this will be done automatically. |
Domain States
| State | Description | Possible Actions |
|---|---|---|
PENDING_VERIFICATION |
This is the first state a domain enters. This state indicates that the domain system is waiting to confirm that the user owns the domain through HTTP, CNAME, or TXT validation before proceeding to the next step. | See the values in the ownership_verification field and pick one integration method to use for validation. Once the CNAME, TXT, or HTTP value has been installed, wait for reverification or use the PATCH endpoint to reattempt. |
VERIFICATION_FAILED |
This state indicates that the domain timed out when trying to validate ownership. Domains in this state will eventually be cleaned up. | Ensure that the steps were followed in the PENDING_VERIFICATION state. To reattempt verification, use the PATCH endpoint. |
PENDING_CREATION |
This state indicates that the domain ownership has been verified and SSL issuance has begun. | If the validation method in the SSL configuration is TXT or the domain is a wildcard, there will be additional steps within the SSL configuration that need to be followed. |
CREATING |
This state indicates that the SSL certificate is being issued. | If the validation method in the SSL configuration is TXT or the domain is a wildcard, there will be additional steps within the SSL configuration that need to be followed. |
CREATION_FAILED |
A domain in this state failed the certificate creation step. Errors will be returned within the errors object to explain why. | Some errors will require user action, such as CAA records blocking issuance. |
ACTIVE |
The domain has an SSL setup and is ready to serve content. Domain associations can be created. | There are no further actions. If TXT pre-verification was chosen, then DNS setup is still required to serve content. See the errors object in the domain for more information. |
PENDING_DELETION |
This domain has been marked for deletion by the user. | No action; this is an intermediary state. |
DELETED |
This domain has been deleted. | No action. If the domain needs to be recreated, use the CREATE endpoint. |
DELETION_FAILED |
The deletion failed due to errors. | See the errors object on the domain. If there are no errors, call the DELETE endpoint again. |
MOVE_REQUIRED |
This state indicates that a newly created domain matches a domain in another account. | Follow the pending verification steps to verify ownership of the domain by this account. After verification, a PATCH call needs to be made with the force flag parameter set to true. |
BLOCKED |
This state indicates that the domain has been blocked by Cloudflare or the certificate authority. | This is most likely due to a zone block; this will require Yext support. |
Domain Association
Domain associations are a top-level resource within the Domains API. Creating a Domain Association will begin serving the contents of the associated resource at the Domain Association's hostname (given DNS for the hostname is already set up).
| Field | Description | Example |
|---|---|---|
Name name
|
The unique identifier for the domain association. It will follow the format: /accounts/{business_id}/domains/{domain_id}/associations/{association_id}. The association ID will be in UUIDv7 format. |
/accounts/123456/domains/abcdf-12343-defsg-12345/associations/abcdf-12343-defsg-12345 |
Hostname hostname
|
This is the hostname that will serve the content that the association provides. If the parent domain is a wildcard, this can be any subdomain of the wildcard. If the parent domain is not a wildcard, this must match the parent domain's hostname. | hitchhikers.yext.com |
| Association | This is the field that ties the domain to the resource within the Yext system, such as Pages. This will be an object. See the Association Types table below. | |
Create time create_time
|
This is the UTC time when the domain association was created. | |
Update time update_time
|
This is the UTC time when the domain association was last updated. | |
Errors errors
|
An optional object returned if there are any asynchronous issues with the domain association setup. The GET and LIST endpoints return this if the view mode is set to full. |
Association Types
For now, the only association type available is Pages, so all domains must use the Pages destination, and all associations must have a site resource defined. The site resource cannot reference a classic site.
| Field | Description | Example |
|---|---|---|
Name name
|
The resource name for the site that the domain should be connected to. This will follow the format /accounts/{business_id}/sites/{site_id}, where the site_id is the numeric identifier found in the URL for the Pages site. |
/accounts/123/sites/456 |
Primary primary
|
A boolean to indicate whether or not the domain should be the canonical domain for the site. Sites support aliases which allow content to be served on different domains. Only one association for a site can have primary = true. |
Managed CSR
Managed CSRs are a top-level resource in the Domains API. This object represents a private key and a managed certificate signing request stored in Cloudflare. When a managed CSR is created, a new private key will be created in Cloudflare, which is inaccessible to the user or Yext. Then a CSR will also be created from the provided fields and returned. From there, this CSR can be used with any certificate authority to generate a public key. This public key will be associated with a domain and specified in the Managed CSR SSL configuration section above.
| Field | Description | Example |
|---|---|---|
Name name
|
The unique identifier for the managed CSR. It will follow the format: /accounts/{business_id}/csrs/{managed_csr_id}. The managed CSR ID will be in UUIDv7 format. |
/accounts/123456/csrs/abcdf-12343-defsg-12345 |
CSR Payload csr_payload
|
The payload for the CSR, which follows the typical required fields when generating a certificate signing request. See the table below. | |
CSR csr
|
A newline-encoded string, which is the certificate signing request, meant to be used to generate the public certificate with a certificate authority. | |
Create time created_time
|
This is the UTC time when the managed CSR was created. |
CSR Payload
All of these fields are required and match the expected format of CSRs (example article).
| Field | Description | Example |
|---|---|---|
Country country
|
The two-letter country code where your organization is located. | US |
State state
|
The two-letter state/province code where your organization is located. | NY |
Locality locality
|
The city/locality where your organization is located. | New York |
Organization organization
|
The name of your organization. | Yext |
Organizational Unit organizational_unit
|
An optional field to specify the division of your organization handling the certificate. | |
Common Name common_name
|
The fully qualified domain name (FQDN) of your server. | yext.com |
SANs sans
|
Additional hostnames that should be covered by this certificate. | hitchhikers.yext.com |
Key Type key_type
|
An optional field to specify the key type for the private key associated with the CSR. Options are rsa2048 and p256v1. If no choice is provided, rsa2048 will be used. |
rsa2048 |