Domains API: Domain | Yext Hitchhikers Platform

Domains are a top-level resource within the Domains API. It will guide 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.	`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 State section below for more information on the different states and the required action for each one.	`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 the Domain Ownership Verification section
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 the SSL Configuration section
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 generated.

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. The table below will indicate what each field means and what needs to be done.

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 field	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 field	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 CSRs section 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 field	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
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 field	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 in the domain object 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 at any point, 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.	In this state, the pending verification steps will need to be followed 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.

Back

< Domains Overview

Domains API: Domain Association >

<% elem.innerText %>