Yext Domains API

openapi: 3.0.0
info:
  title: Yext Admin Account Settings Domains API
  version: '2.0'
servers:
- url: https://api.yextapis.com/v2
security:
- api_key: []
- api-key: []
tags:
- name: Domains
paths:
  /accounts/{accountId}/domains:
    parameters:
    - $ref: '#/components/parameters/accountId'
    - $ref: '#/components/parameters/v'
    post:
      operationId: createDomain
      tags:
      - Domains
      summary: 'Domain: Create

        '
      requestBody:
        description: Configuration for the domain to be created.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Identifier for the resource.
                  type: string
                  readOnly: true
                  example: accounts/123456/domains/4f72b877-e2d0-4de4-9324-b9cf2c03e1a0
                hostname:
                  description: Fully qualified domain name that will be delegated to Yext.
                  type: string
                  example: www.example.com
                wildcard:
                  description: 'If set to true, [Domain Associations](#tag/Domains/operation/createDomainAssociation) can be created for single-level subdomains of the given hostname.

                    '
                  type: boolean
                  default: false
                destination:
                  description: 'The Yext product the domain will be used for. Currently, only `PAGES` is supported.

                    '
                  type: string
                  enum:
                  - PAGES
                  example: PAGES
                integration_type:
                  description: 'How the domain will be integrated with Yext. Only `USER_OWNED` is supported for domains created via the API.

                    '
                  type: string
                  enum:
                  - USER_OWNED
                  - CUSTOM
                  - LEGACY_YEXT_MANAGED
                  example: USER_OWNED
                state:
                  type: string
                  readOnly: true
                  enum:
                  - PENDING_VERIFICATION
                  - VERIFICATION_FAILED
                  - PENDING_CREATION
                  - CREATING
                  - CREATION_FAILED
                  - ACTIVE
                  - PENDING_DELETION
                  - DELETED
                  - BLOCKED
                  - DELETION_FAILED
                  - MOVE_REQUIRED
                  example: ACTIVE
                ownership_verification:
                  description: 'One of CNAME, TXT, or HTTP verification must be used to complete Yext ownership verification for the domain.

                    The tokens to use for each of these methods are provided in this object.

                    '
                  type: object
                  readOnly: true
                  properties:
                    cname_target:
                      type: string
                      example: idzm5s34j5.yext.pgscdncf.com.
                    txt_domain:
                      type: string
                      example: _yext-domain.www.example.com
                    txt_value:
                      type: string
                      format: uuid
                    http_uri:
                      type: string
                      example: http://www.example.com/.well-known/yext-domain-challenge/35f00e6a-61c2-4857-b2cc-4c736f86b5ac
                    http_body:
                      type: string
                      format: uuid
                managed_ssl:
                  description: 'SSL certificate will be automatically managed by Yext.

                    Exactly one of `managed_ssl`, `managed_csr`, or `custom_ssl_certificate` must be set for a domain.

                    '
                  type: object
                  required:
                  - certificate_authority
                  - validation_method
                  properties:
                    certificate_authority:
                      type: string
                      enum:
                      - GOOGLE_TRUST
                      - LETS_ENCRYPT
                      default: GOOGLE_TRUST
                    validation_method:
                      type: string
                      enum:
                      - HTTP
                      - TXT
                      example: HTTP
                    hostname_validation:
                      description: 'Proof of ownership for the SSL provider.

                        '
                      type: object
                      readOnly: true
                      properties:
                        cname_target:
                          type: string
                          example: idzm5s34j5.yext.pgscdncf.com.
                        txt_domain:
                          type: string
                          example: _yext-domain.www.example.com
                        txt_value:
                          type: string
                          format: uuid
                        http_uri:
                          type: string
                          example: http://www.example.com/.well-known/yext-domain-challenge/35f00e6a-61c2-4857-b2cc-4c736f86b5ac
                        http_body:
                          type: string
                          format: uuid
                    http_validation:
                      description: 'This will only be set if `HTTP` is selected via the `validation_method` field.

                        '
                      type: object
                      readOnly: true
                      properties:
                        uri:
                          type: string
                          example: http://www.example.com/.well-known/acme-challenge/0NW3MkWCrnT_5dwos0fKtwrPAqMygpcUqLqDNibb0xLXH3Zjag6wSqPfcvWTGkRr
                        body:
                          type: string
                          example: 0NW3MkWCrnT_5dwos0fKtwrPAqMygpcUqLqDNibb0xLXH3Zjag6wSqPfcvWTGkRr.r54qAqCZSs4xyyeamMffaxyR1FWYVb5OvwUh8EcrhpI
                    txt_validation:
                      description: 'This will only be set if `TXT` is selected via the `validation_method` field.

                        The delegated DCV CNAME is recommended over the individual TXT records,since delegated DCV would only need to be

                        done one time, whereas the individual TXT records would have to be set everytime the certificate is renewed.

                        '
                      type: object
                      readOnly: true
                      properties:
                        delegated_dcv_domain:
                          type: string
                        delegated_dcv_cname_target:
                          type: string
                        txt_records:
                          description: 'Will have multiple required tokens if the domain is a wildcard domain.

                            '
                          type: array
                          items:
                            type: object
                            properties:
                              domain:
                                type: string
                                example: _acme-challenge.www.example.com
                              value:
                                type: string
                                example: -sXIiCspHlmE7GU-vV-6oBR-M6BU-4d1A4Ak3O1cGos
                managed_csr:
                  description: 'SSL certificate will be issued using the given [Managed CSR](#tag/Domains/operation/createManagedCsr).

                    Exactly one of `managed_ssl`, `managed_csr`, or `custom_ssl_certificate` must be set for a domain.

                    '
                  type: object
                  properties:
                    managed_csr_id:
                      description: 'The name of the [Managed CSR](#tag/Domains/operation/createManagedCsr) resource.

                        '
                      type: string
                      example: accounts/123456/csrs/4f72b877-e2d0-4de4-9324-b9cf2c03e1a0
                    custom_public_certificate:
                      description: 'Public CA signed certificate.

                        '
                      type: string
                      format: pem
                      writeOnly: true
                      example: '-----BEGIN CERTIFICATE-----

                        MIIC2DCCAcCAQAwgY4xCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlh

                        ...

                        -----END CERTIFICATE-----

                        '
                    hostname_validation:
                      description: 'Proof of ownership for the SSL provider.

                        '
                      type: object
                      readOnly: true
                      properties:
                        cname_target:
                          type: string
                          example: idzm5s34j5.yext.pgscdncf.com.
                        txt_domain:
                          type: string
                          example: _yext-domain.www.example.com
                        txt_value:
                          type: string
                          format: uuid
                        http_uri:
                          type: string
                          example: http://www.example.com/.well-known/yext-domain-challenge/35f00e6a-61c2-4857-b2cc-4c736f86b5ac
                        http_body:
                          type: string
                          format: uuid
                custom_ssl_certificate:
                  description: 'The provided custom SSL certificate will be used for serving requests to the domain.

                    Exactly one of `managed_ssl`, `managed_csr`, or `custom_ssl_certificate` must be set for a domain.

                    '
                  type: object
                  required:
                  - public_certificate
                  - private_key
                  properties:
                    public_certificate:
                      type: string
                      format: pem
                      writeOnly: true
                      example: '-----BEGIN CERTIFICATE-----

                        MIIC2DCCAcCAQAwgY4xCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlh

                        ...

                        -----END CERTIFICATE-----

                        '
                    private_key:
                      type: string
                      format: pem
                      writeOnly: true
                      example: '-----BEGIN PRIVATE KEY-----

                        MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDBj08sp5++4anG

                        ...

                        -----END PRIVATE KEY-----

                        '
                    hostname_validation:
                      description: 'Proof of ownership for the SSL provider.

                        '
                      type: object
                      readOnly: true
                      properties:
                        cname_target:
                          type: string
                          example: idzm5s34j5.yext.pgscdncf.com.
                        txt_domain:
                          type: string
                          example: _yext-domain.www.example.com
                        txt_value:
                          type: string
                          format: uuid
                        http_uri:
                          type: string
                          example: http://www.example.com/.well-known/yext-domain-challenge/35f00e6a-61c2-4857-b2cc-4c736f86b5ac
                        http_body:
                          type: string
                          format: uuid
                serving_dns_targets:
                  description: 'DNS targets used to serve traffic through Yext. For apex domains, `a_records` is returned. For subdomains, `cname` is returned.

                    Only one of `a_records` or `cname` will be set.

                    '
                  type: object
                  readOnly: true
                  properties:
                    a_records:
                      description: 'Expected A record targets to serve traffic. Returned for apex domains.

                        '
                      type: array
                      items:
                        type: string
                      example:
                      - 104.17.134.18
                    cname:
                      description: 'Expected CNAME target to serve traffic. Returned for subdomains.

                        '
                      type: string
                      example: 93bpo083jheeb.yext.pagescdn.com
                errors:
                  description: Errors and/or warnings regarding the Domain setup.
                  type: array
                  readOnly: true
                  items:
                    $ref: '#/components/schemas/ResponseError'
                create_time:
                  type: string
                  format: date-time
                  readOnly: true
                update_time:
                  type: string
                  format: date-time
                  readOnly: true
                delete_time:
                  type: string
                  format: date-time
                  readOnly: true
              required:
              - hostname
              - destination
              - integration_type
      responses:
        '201':
          description: Domain created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                  response:
                    title: Domain
                    type: object
                    properties:
                      name:
                        description: Identifier for the resource.
                        type: string
                        readOnly: true
                        example: accounts/123456/domains/4f72b877-e2d0-4de4-9324-b9cf2c03e1a0
                      hostname:
                        description: Fully qualified domain name that will be delegated to Yext.
                        type: string
                        example: www.example.com
                      wildcard:
                        description: 'If set to true, [Domain Associations](#tag/Domains/operation/createDomainAssociation) can be created for single-level subdomains of the given hostname.

                          '
                        type: boolean
                        default: false
                      destination:
                        description: 'The Yext product the domain will be used for. Currently, only `PAGES` is supported.

                          '
                        type: string
                        enum:
                        - PAGES
                        example: PAGES
                      integration_type:
                        description: 'How the domain will be integrated with Yext. Only `USER_OWNED` is supported for domains created via the API.

                          '
                        type: string
                        enum:
                        - USER_OWNED
                        - CUSTOM
                        - LEGACY_YEXT_MANAGED
                        example: USER_OWNED
                      state:
                        type: string
                        readOnly: true
                        enum:
                        - PENDING_VERIFICATION
                        - VERIFICATION_FAILED
                        - PENDING_CREATION
                        - CREATING
                        - CREATION_FAILED
                        - ACTIVE
                        - PENDING_DELETION
                        - DELETED
                        - BLOCKED
                        - DELETION_FAILED
                        - MOVE_REQUIRED
                        example: ACTIVE
                      ownership_verification:
                        description: 'One of CNAME, TXT, or HTTP verification must be used to complete Yext ownership verification for the domain.

                          The tokens to use for each of these methods are provided in this object.

                          '
                        type: object
                        readOnly: true
                        properties:
                          cname_target:
                            type: string
                            example: idzm5s34j5.yext.pgscdncf.com.
                          txt_domain:
                            type: string
                            example: _yext-domain.www.example.com
                          txt_value:
                            type: string
                            format: uuid
                          http_uri:
                            type: string
                            example: http://www.example.com/.well-known/yext-domain-challenge/35f00e6a-61c2-4857-b2cc-4c736f86b5ac
                          http_body:
                            type: string
                            format: uuid
                      managed_ssl:
                        description: 'SSL certificate will be automatically managed by Yext.

                          Exactly one of `managed_ssl`, `managed_csr`, or `custom_ssl_certificate` must be set for a domain.

                          '
                        type: object
                        required:
                        - certificate_authority
                        - validation_method
                        properties:
                          certificate_authority:
                            type: string
                            enum:
                            - GOOGLE_TRUST
                            - LETS_ENCRYPT
                            default: GOOGLE_TRUST
                          validation_method:
                            type: string
                            enum:
                            - HTTP
                            - TXT
                            example: HTTP
                          hostname_validation:
                            description: 'Proof of ownership for the SSL provider.

                              '
                            type: object
                            readOnly: true
                            properties:
                              cname_target:
                                type: string
                                example: idzm5s34j5.yext.pgscdncf.com.
                              txt_domain:
                                type: string
                                example: _yext-domain.www.example.com
                              txt_value:
                                type: string
                                format: uuid
                              http_uri:
                                type: string
                                example: http://www.example.com/.well-known/yext-domain-challenge/35f00e6a-61c2-4857-b2cc-4c736f86b5ac
                              http_body:
                                type: string
                                format: uuid
                          http_validation:
                            description: 'This will only be set if `HTTP` is selected via the `validation_method` field.

                              '
                            type: object
                            readOnly: true
                            properties:
                              uri:
                                type: string
                                example: http://www.example.com/.well-known/acme-challenge/0NW3MkWCrnT_5dwos0fKtwrPAqMygpcUqLqDNibb0xLXH3Zjag6wSqPfcvWTGkRr
                              body:
                                type: string
                                example: 0NW3MkWCrnT_5dwos0fKtwrPAqMygpcUqLqDNibb0xLXH3Zjag6wSqPfcvWTGkRr.r54qAqCZSs4xyyeamMffaxyR1FWYVb5OvwUh8EcrhpI
                          txt_validation:
                            description: 'This will only be set if `TXT` is selected via the `validation_method` field.

                              The delegated DCV CNAME is recommended over the individual TXT records,since delegated DCV would only need to be

                              done one time, whereas the individual TXT records would have to be set everytime the certificate is renewed.

                              '
                            type: object
                            readOnly: true
                            properties:
                              delegated_dcv_domain:
                                type: string
                              delegated_dcv_cname_target:
                                type: string
                              txt_records:
                                description: 'Will have multiple required tokens if the domain is a wildcard domain.

                                  '
                                type: array
                                items:
                                  type: object
                                  properties:
                                    domain:
                                      type: string
                                      example: _acme-challenge.www.example.com
                                    value:
                                      type: string
                                      example: -sXIiCspHlmE7GU-vV-6oBR-M6BU-4d1A4Ak3O1cGos
                      managed_csr:
                        description: 'SSL certificate will be issued using the given [Managed CSR](#tag/Domains/operation/createManagedCsr).

                          Exactly one of `managed_ssl`, `managed_csr`, or `custom_ssl_certificate` must be set for a domain.

                          '
                        type: object
                        properties:
                          managed_csr_id:
                            description: 'The name of the [Managed CSR](#tag/Domains/operation/createManagedCsr) resource.

                              '
                            type: string
                            example: accounts/123456/csrs/4f72b877-e2d0-4de4-9324-b9cf2c03e1a0
                          custom_public_certificate:
                            description: 'Public CA signed certificate.

                              '
                            type: string
                            format: pem
                            writeOnly: true
                            example: '-----BEGIN CERTIFICATE-----

                              MIIC2DCCAcCAQAwgY4xCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlh

                              ...

                              -----END CERTIFICATE-----

                              '
                          hostname_validation:
                            description: 'Proof of ownership for the SSL provider.

                              '
                            type: object
                            readOnly: true
                            properties:
                              cname_target:
                                type: string
                                example: idzm5s34j5.yext.pgscdncf.com.
                              txt_domain:
                                type: string
                                example: _yext-domain.www.example.com
                              txt_value:
                                type: string
                                format: uuid
                              http_uri:
                                type: string
                                example: http://www.example.com/.well-known/yext-domain-challenge/35f00e6a-61c2-4857-b2cc-4c736f86b5ac
                              http_body:
                                type: string
                                format: uuid
                      custom_ssl_certificate:
                        description: 'The provided custom SSL certificate will be used for serving requests to the domain.

                          Exactly one of `managed_ssl`, `managed_csr`, or `custom_ssl_certificate` must be set for a domain.

                          '
                        type: object
                        required:
                        - public_certificate
                        - private_key
                        properties:
                          public_certificate:
                            type: string
                            format: pem
                            writeOnly: true
                            example: '-----BEGIN CERTIFICATE-----

                              MIIC2DCCAcCAQAwgY4xCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlh

                              ...

                              -----END CERTIFICATE-----

                              '
                          private_key:
                            type: string
                            format: pem
                            writeOnly: true
                            example: '-----BEGIN PRIVATE KEY-----

                              MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDBj08sp5++4anG

                              ...

                              -----END PRIVATE KEY-----

                              '
                          hostname_validation:
                            description: 'Proof of ownership for the SSL provider.

                              '
                            type: object
                            readOnly: true
                            properties:
                              cname_target:
                                type: string
                                example: idzm5s34j5.yext.pgscdncf.com.
                              txt_domain:
                                type: string
                                example: _yext-domain.www.example.com
                              txt_value:
                                type: string
                                format: uuid
                              http_uri:
                                type: string
                                example: http://www.example.com/.well-known/yext-domain-challenge/35f00e6a-61c2-4857-b2cc-4c736f86b5ac
                              http_body:
                                type: string
                                format: uuid
                      serving_dns_targets:
                        description: 'DNS targets used to serve traffic through Yext. For apex domains, `a_records` is returned. For subdomains, `cname` is returned.

                          Only one of `a_records` or `cname` will be set.

                          '
                        type: object
                        readOnly: true
                        properties:
                          a_records:
                            description: 'Expected A record targets to serve traffic. Returned for apex domains.

                              '
                            type: array
                            items:
                              type: string
                            example:
                            - 104.17.134.18
                          cname:
                            description: 'Expected CNAME target to serve traffic. Returned for subdomains.

                              '
                            type: string
                            example: 93bpo083jheeb.yext.pagescdn.com
                      errors:
                        description: Errors and/or warnings regarding the Domain setup.
                        type: array
                        readOnly: true
                        items:
                          $ref: '#/components/schemas/ResponseError'
                      create_time:
                        type: string
                        format: date-time
                        readOnly: true
                      update_time:
                        type: string
                        format: date-time
                        readOnly: true
                      delete_time:
                        type: string
                        format: date-time
                        readOnly: true
        default:
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: listDomains
      tags:
      - Domains
      summary: 'Domain: List

        '
      parameters:
      - $ref: '#/components/parameters/hostnameFilters'
      - $ref: '#/components/parameters/hostnameSearchFilter'
      - $ref: '#/components/parameters/showDeleted'
      - $ref: '#/components/parameters/index_pageSize'
      - $ref: '#/components/parameters/index_pageToken'
      - $ref: '#/components/parameters/viewDefaultBasic'
      responses:
        '200':
          description: Paginated list of Domains matching request filters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                  response:
                    type: object
                    properties:
                      domains:
                        type: array
                        items:
                          title: Domain
                          type: object
                          properties:
                            name:
                              description: Identifier for the resource.
                              type: string
                              readOnly: true
                              example: accounts/123456/domains/4f72b877-e2d0-4de4-9324-b9cf2c03e1a0
                            hostname:
                              description: Fully qualified domain name that will be delegated to Yext.
                              type: string
                              example: www.example.com
                            wildcard:
                              description: 'If set to true, [Domain Associations](#tag/Domains/operation/createDomainAssociation) can be created for single-level subdomains of the given hostname.

                                '
                              type: boolean
                              default: false
                            destination:
                              description: 'The Yext product the domain will be used for. Currently, only `PAGES` is supported.

                                '
                              type: string
                              enum:
                              - PAGES
                              example: PAGES
                            integration_type:
                              description: 'How the domain will be integrated with Yext. Only `USER_OWNED` is supported for domains created via the API.

                                '
                              type: string
                              enum:
                              - USER_OWNED
                              - CUSTOM
                              - LEGACY_YEXT_MANAGED
                              example: USER_OWNED
                            state:
                              type: string
                              readOnly: true
                              enum:
                              - PENDING_VERIFICATION
                              - VERIFICATION_FAILED
                              - PENDING_CREATION
                              - CREATING
                              - CREATION_FAILED
                              - ACTIVE
                              - PENDING_DELETION
                              - DELETED
                              - BLOCKED
                              - DELETION_FAILED
                              - MOVE_REQUIRED
                              example: ACTIVE
                            ownership_verification:
                              description: 'One of CNAME, TXT, or HTTP verification must be used to complete Yext ownership verification for the domain.

                                The tokens to use for each of these methods are provided in this object.

                                '
                              type: object
                              readOnly: true
                              properties:
                                cname_target:
                                  type: string
                                  example: idzm5

# --- truncated at 32 KB (134 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/yext/refs/heads/main/openapi/yext-domains-api-openapi.yml