--- title: Custom Hostname Details --- [Skip to content](#_top) [API Reference](https://developers.cloudflare.com/api) [Custom Hostnames](https://developers.cloudflare.com/api/resources/custom_hostnames) Copy Markdown Open in **Claude**Open in **ChatGPT**Open in **Cursor** --- **Copy Markdown****View as Markdown** # Custom Hostname Details GET/zones/{zone\_id}/custom\_hostnames/{custom\_hostname\_id} Retrieves detailed information about a specific custom hostname, including SSL certificate status, ownership verification, and origin configuration. ##### Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token. **Example:**Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key. **Example:**X-Auth-Email: user@example.com The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys. **Example:**X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

##### Accepted Permissions (at least one required) `SSL and Certificates Write``SSL and Certificates Read` ##### P ath ParametersExpand Collapse zone\_id: string Identifier. maxLength32 [Link to this property](<#(resource)%20custom_hostnames%20%3E%20(method)%20get%20%3E%20(params)%20default%20%3E%20(param)%20zone_id%20%3E%20(schema)>) custom\_hostname\_id: string Custom hostname identifier tag. maxLength36 minLength36 [Link to this property](<#(resource)%20custom_hostnames%20%3E%20(method)%20get%20%3E%20(params)%20default%20%3E%20(param)%20custom_hostname_id%20%3E%20(schema)>) ##### ReturnsExpand Collapse

errors: array of object {code, message, documentation\_url, source }

code: number minimum1000 Link to this property message: string Link to this property documentation\_url: optional string Link to this property

source: optional object {pointer }

pointer: optional string Link to this property

Link to this property

[Link to this property](<#(resource)%20custom_hostnames%20%3E%20(method)%20get%20%3E%20(network%20schema)%20%3E%20(property)%20errors>) messages: array of string Informational messages returned by the custom hostname API. [Link to this property](<#(resource)%20custom_hostnames%20%3E%20(method)%20get%20%3E%20(network%20schema)%20%3E%20(property)%20messages>) success: true Whether the API call was successful. [Link to this property](<#(resource)%20custom_hostnames%20%3E%20(method)%20get%20%3E%20(network%20schema)%20%3E%20(property)%20success>)

result: optional object {id, hostname, created\_at, 8 more }

id: string Custom hostname identifier tag. maxLength36 minLength36 Link to this property hostname: string The custom hostname that will point to your hostname via CNAME. maxLength255 Link to this property created\_at: optional string This is the time the hostname was created. formatdate-time Link to this property custom\_metadata: optional map\[string] Unique key/value metadata for this hostname. These are per-hostname (customer) settings. Link to this property custom\_origin\_server: optional string a valid hostname that’s been added to your DNS zone as an A, AAAA, or CNAME record. Link to this property custom\_origin\_sni: optional string A hostname that will be sent to your custom origin server as SNI for TLS handshake. This can be a valid subdomain of the zone or custom origin server name or the string ‘:request\_host\_header:’ which will cause the host header in the request to be used as SNI. Not configurable with default/fallback origin server. Link to this property

ownership\_verification: optional object {name, type, value } This is a record which can be placed to activate a hostname.

name: optional string DNS Name for record. Link to this property type: optional "txt" DNS Record type. Link to this property value: optional string Content for the record. Link to this property

Link to this property

ownership\_verification\_http: optional object {http\_body, http\_url } This presents the token to be served by the given http url to activate a hostname.

http\_body: optional string Token to be served. Link to this property http\_url: optional string The HTTP URL that will be checked during custom hostname verification and where the customer should host the token. Link to this property

Link to this property

ssl: optional object {id, bundle\_method, certificate\_authority, 17 more }

id: optional string Custom hostname SSL identifier tag. maxLength36 minLength36 Link to this property

bundle\_method: optional BundleMethod A ubiquitous bundle has the highest probability of being verified everywhere, even by clients using outdated or unusual trust stores. An optimal bundle uses the shortest chain and newest intermediates. And the force bundle verifies the chain, but does not otherwise modify it.

One of the following: "ubiquitous" Link to this property "optimal" Link to this property "force" Link to this property

Link to this property

certificate\_authority: optional CertificateCA The Certificate Authority that will issue the certificate.

One of the following: "digicert" Link to this property "google" Link to this property "lets\_encrypt" Link to this property "ssl\_com" Link to this property

Link to this property custom\_certificate: optional string If a custom uploaded certificate is used. Link to this property custom\_csr\_id: optional string The identifier for the Custom CSR that was used. Link to this property custom\_key: optional string The key for a custom uploaded certificate. Link to this property

dcv\_delegation\_records: optional array of object {cname, cname\_target, emails, 5 more } DCV Delegation records for domain validation.

cname: optional string The CNAME record hostname for DCV delegation. Link to this property cname\_target: optional string The CNAME record target value for DCV delegation. Link to this property emails: optional array of string The set of email addresses that the certificate authority (CA) will use to complete domain validation. Link to this property http\_body: optional string The content that the certificate authority (CA) will expect to find at the http\_url during the domain validation. Link to this property http\_url: optional string The url that will be checked during domain validation. Link to this property status: optional string Status of the validation record. Link to this property txt\_name: optional string The hostname that the certificate authority (CA) will check for a TXT record during domain validation . Link to this property txt\_value: optional string The TXT record that the certificate authority (CA) will check during domain validation. Link to this property

Link to this property expires\_on: optional string The time the custom certificate expires on. formatdate-time Link to this property hosts: optional array of string A list of Hostnames on a custom uploaded certificate. Link to this property issuer: optional string The issuer on a custom uploaded certificate. Link to this property

method: optional DCVMethod Domain control validation (DCV) method used for this hostname.

One of the following: "http" Link to this property "txt" Link to this property "email" Link to this property

Link to this property serial\_number: optional string The serial number on a custom uploaded certificate. Link to this property

settings: optional object {ciphers, early\_hints, http2, 2 more }

ciphers: optional array of string An allowlist of ciphers for TLS termination. These ciphers must be in the BoringSSL format. Link to this property

early\_hints: optional "on"or "off" Whether or not Early Hints is enabled.

One of the following: "on" Link to this property "off" Link to this property

Link to this property

http2: optional "on"or "off" Whether or not HTTP2 is enabled.

One of the following: "on" Link to this property "off" Link to this property

Link to this property

min\_tls\_version: optional "1.0"or "1.1"or "1.2"or "1.3" The minimum TLS version supported.

One of the following: "1.0" Link to this property "1.1" Link to this property "1.2" Link to this property "1.3" Link to this property

Link to this property

tls\_1\_3: optional "on"or "off" Whether or not TLS 1.3 is enabled.

One of the following: "on" Link to this property "off" Link to this property

Link to this property

Link to this property signature: optional string The signature on a custom uploaded certificate. Link to this property

status: optional "initializing"or "pending\_validation"or "deleted"or 18 more Status of the hostname’s SSL certificates.

One of the following: "initializing" Link to this property "pending\_validation" Link to this property "deleted" Link to this property "pending\_issuance" Link to this property "pending\_deployment" Link to this property "pending\_deletion" Link to this property "pending\_expiration" Link to this property "expired" Link to this property "active" Link to this property "initializing\_timed\_out" Link to this property "validation\_timed\_out" Link to this property "issuance\_timed\_out" Link to this property "deployment\_timed\_out" Link to this property "deletion\_timed\_out" Link to this property "pending\_cleanup" Link to this property "staging\_deployment" Link to this property "staging\_active" Link to this property "deactivating" Link to this property "inactive" Link to this property "backup\_issued" Link to this property "holding\_deployment" Link to this property

Link to this property type: optional DomainValidationType Level of validation to be used for this hostname. Domain validation (dv) must be used. Link to this property uploaded\_on: optional string The time the custom certificate was uploaded. formatdate-time Link to this property

validation\_errors: optional array of object {message } Domain validation errors that have been received by the certificate authority (CA).

message: optional string A domain validation error. Link to this property

Link to this property

validation\_records: optional array of object {cname, cname\_target, emails, 5 more }

Link to this property wildcard: optional boolean Indicates whether the certificate covers a wildcard. Link to this property

Link to this property

status: optional "active"or "pending"or "active\_redeploying"or 13 more Status of the hostname’s activation.

Link to this property verification\_errors: optional array of string These are errors that were encountered while trying to activate a hostname. Link to this property

[Link to this property](<#(resource)%20custom_hostnames%20%3E%20(method)%20get%20%3E%20(network%20schema)%20%3E%20(property)%20result>) ### Custom Hostname Details HTTP HTTPTypeScriptPythonGoTerraform ``` curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/custom_hostnames/$CUSTOM_HOSTNAME_ID \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` 200 example ``` { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "success": true, "result": { "id": "0d89c70d-ad9f-4843-b99f-6cc0252067e9", "hostname": "app.example.com", "created_at": "2020-02-06T18:11:23.531995Z", "custom_metadata": { "foo": "string" }, "custom_origin_server": "origin2.example.com", "custom_origin_sni": "sni.example.com", "ownership_verification": { "name": "_cf-custom-hostname.app.example.com", "type": "txt", "value": "5cc07c04-ea62-4a5a-95f0-419334a875a4" }, "ownership_verification_http": { "http_body": "5cc07c04-ea62-4a5a-95f0-419334a875a4", "http_url": "http://custom.test.com/.well-known/cf-custom-hostname-challenge/0d89c70d-ad9f-4843-b99f-6cc0252067e9" }, "ssl": { "id": "0d89c70d-ad9f-4843-b99f-6cc0252067e9", "bundle_method": "ubiquitous", "certificate_authority": "google", "custom_certificate": "-----BEGIN CERTIFICATE-----\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\n-----END CERTIFICATE-----\n", "custom_csr_id": "7b163417-1d2b-4c84-a38a-2fb7a0cd7752", "custom_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----\n", "dcv_delegation_records": [ { "cname": "_acme-challenge.example.com", "cname_target": "dcv.cloudflare.com", "emails": [ "administrator@example.com", "webmaster@example.com" ], "http_body": "ca3-574923932a82475cb8592200f1a2a23d", "http_url": "http://app.example.com/.well-known/pki-validation/ca3-da12a1c25e7b48cf80408c6c1763b8a2.txt", "status": "pending", "txt_name": "_acme-challenge.app.example.com", "txt_value": "810b7d5f01154524b961ba0cd578acc2" } ], "expires_on": "2021-02-06T18:11:23.531995Z", "hosts": [ "app.example.com", "*.app.example.com" ], "issuer": "DigiCertInc", "method": "http", "serial_number": "6743787633689793699141714808227354901", "settings": { "ciphers": [ "ECDHE-RSA-AES128-GCM-SHA256", "AES128-SHA" ], "early_hints": "on", "http2": "on", "min_tls_version": "1.2", "tls_1_3": "on" }, "signature": "SHA256WithRSA", "status": "pending_validation", "type": "dv", "uploaded_on": "2020-02-06T18:11:23.531995Z", "validation_errors": [ { "message": "SERVFAIL looking up CAA for app.example.com" } ], "validation_records": [ { "cname": "_acme-challenge.example.com", "cname_target": "dcv.cloudflare.com", "emails": [ "administrator@example.com", "webmaster@example.com" ], "http_body": "ca3-574923932a82475cb8592200f1a2a23d", "http_url": "http://app.example.com/.well-known/pki-validation/ca3-da12a1c25e7b48cf80408c6c1763b8a2.txt", "status": "pending", "txt_name": "_acme-challenge.app.example.com", "txt_value": "810b7d5f01154524b961ba0cd578acc2" } ], "wildcard": false }, "status": "pending", "verification_errors": [ "None of the A or AAAA records are owned by this account and the pre-generated ownership verification token was not found." ] } } ``` ##### Returns Examples 200 example ``` { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "success": true, "result": { "id": "0d89c70d-ad9f-4843-b99f-6cc0252067e9", "hostname": "app.example.com", "created_at": "2020-02-06T18:11:23.531995Z", "custom_metadata": { "foo": "string" }, "custom_origin_server": "origin2.example.com", "custom_origin_sni": "sni.example.com", "ownership_verification": { "name": "_cf-custom-hostname.app.example.com", "type": "txt", "value": "5cc07c04-ea62-4a5a-95f0-419334a875a4" }, "ownership_verification_http": { "http_body": "5cc07c04-ea62-4a5a-95f0-419334a875a4", "http_url": "http://custom.test.com/.well-known/cf-custom-hostname-challenge/0d89c70d-ad9f-4843-b99f-6cc0252067e9" }, "ssl": { "id": "0d89c70d-ad9f-4843-b99f-6cc0252067e9", "bundle_method": "ubiquitous", "certificate_authority": "google", "custom_certificate": "-----BEGIN CERTIFICATE-----\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\n-----END CERTIFICATE-----\n", "custom_csr_id": "7b163417-1d2b-4c84-a38a-2fb7a0cd7752", "custom_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----\n", "dcv_delegation_records": [ { "cname": "_acme-challenge.example.com", "cname_target": "dcv.cloudflare.com", "emails": [ "administrator@example.com", "webmaster@example.com" ], "http_body": "ca3-574923932a82475cb8592200f1a2a23d", "http_url": "http://app.example.com/.well-known/pki-validation/ca3-da12a1c25e7b48cf80408c6c1763b8a2.txt", "status": "pending", "txt_name": "_acme-challenge.app.example.com", "txt_value": "810b7d5f01154524b961ba0cd578acc2" } ], "expires_on": "2021-02-06T18:11:23.531995Z", "hosts": [ "app.example.com", "*.app.example.com" ], "issuer": "DigiCertInc", "method": "http", "serial_number": "6743787633689793699141714808227354901", "settings": { "ciphers": [ "ECDHE-RSA-AES128-GCM-SHA256", "AES128-SHA" ], "early_hints": "on", "http2": "on", "min_tls_version": "1.2", "tls_1_3": "on" }, "signature": "SHA256WithRSA", "status": "pending_validation", "type": "dv", "uploaded_on": "2020-02-06T18:11:23.531995Z", "validation_errors": [ { "message": "SERVFAIL looking up CAA for app.example.com" } ], "validation_records": [ { "cname": "_acme-challenge.example.com", "cname_target": "dcv.cloudflare.com", "emails": [ "administrator@example.com", "webmaster@example.com" ], "http_body": "ca3-574923932a82475cb8592200f1a2a23d", "http_url": "http://app.example.com/.well-known/pki-validation/ca3-da12a1c25e7b48cf80408c6c1763b8a2.txt", "status": "pending", "txt_name": "_acme-challenge.app.example.com", "txt_value": "810b7d5f01154524b961ba0cd578acc2" } ], "wildcard": false }, "status": "pending", "verification_errors": [ "None of the A or AAAA records are owned by this account and the pre-generated ownership verification token was not found." ] } } ```