Set a custom resolver hostname's unresolved-scan fallback policy
curl --request POST \
--url https://www.closient.com/resolver/api/v1/organizations/{organization_id}/custom-hostnames/fallback-policy \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"hostname": "id.theirco.com",
"mode": "redirect",
"redirect_url": "https://theirco.com/not-found",
"utm_campaign": "",
"utm_content": "",
"utm_medium": "",
"utm_source": "closient-resolver",
"utm_term": ""
}
'import requests
url = "https://www.closient.com/resolver/api/v1/organizations/{organization_id}/custom-hostnames/fallback-policy"
payload = {
"hostname": "id.theirco.com",
"mode": "redirect",
"redirect_url": "https://theirco.com/not-found",
"utm_campaign": "",
"utm_content": "",
"utm_medium": "",
"utm_source": "closient-resolver",
"utm_term": ""
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
hostname: 'id.theirco.com',
mode: 'redirect',
redirect_url: 'https://theirco.com/not-found',
utm_campaign: '',
utm_content: '',
utm_medium: '',
utm_source: 'closient-resolver',
utm_term: ''
})
};
fetch('https://www.closient.com/resolver/api/v1/organizations/{organization_id}/custom-hostnames/fallback-policy', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://www.closient.com/resolver/api/v1/organizations/{organization_id}/custom-hostnames/fallback-policy",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'hostname' => 'id.theirco.com',
'mode' => 'redirect',
'redirect_url' => 'https://theirco.com/not-found',
'utm_campaign' => '',
'utm_content' => '',
'utm_medium' => '',
'utm_source' => 'closient-resolver',
'utm_term' => ''
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://www.closient.com/resolver/api/v1/organizations/{organization_id}/custom-hostnames/fallback-policy"
payload := strings.NewReader("{\n \"hostname\": \"id.theirco.com\",\n \"mode\": \"redirect\",\n \"redirect_url\": \"https://theirco.com/not-found\",\n \"utm_campaign\": \"\",\n \"utm_content\": \"\",\n \"utm_medium\": \"\",\n \"utm_source\": \"closient-resolver\",\n \"utm_term\": \"\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://www.closient.com/resolver/api/v1/organizations/{organization_id}/custom-hostnames/fallback-policy")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"hostname\": \"id.theirco.com\",\n \"mode\": \"redirect\",\n \"redirect_url\": \"https://theirco.com/not-found\",\n \"utm_campaign\": \"\",\n \"utm_content\": \"\",\n \"utm_medium\": \"\",\n \"utm_source\": \"closient-resolver\",\n \"utm_term\": \"\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://www.closient.com/resolver/api/v1/organizations/{organization_id}/custom-hostnames/fallback-policy")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"hostname\": \"id.theirco.com\",\n \"mode\": \"redirect\",\n \"redirect_url\": \"https://theirco.com/not-found\",\n \"utm_campaign\": \"\",\n \"utm_content\": \"\",\n \"utm_medium\": \"\",\n \"utm_source\": \"closient-resolver\",\n \"utm_term\": \"\"\n}"
response = http.request(request)
puts response.read_body{
"fallback_mode": "hosted_404",
"fallback_redirect_url": "",
"fallback_utm_campaign": "",
"fallback_utm_content": "",
"fallback_utm_medium": "",
"fallback_utm_source": "",
"fallback_utm_term": "",
"hostname": "id.theirco.com",
"is_qr_ready": true,
"last_checked_at": "2026-07-20T18:04:11Z",
"last_error": "",
"setup": {
"challenge": {
"name": "_closient-challenge.id.theirco.com",
"purpose": "ownership_verification",
"type": "CNAME",
"value": "9f86d081884c.verify.gtin.one"
},
"qr_density_warning": false,
"serving": {
"name": "id.theirco.com",
"purpose": "resolver_routing",
"type": "CNAME",
"value": "gtin.one"
}
},
"status": "VERIFIED",
"tls_status": "ACTIVE",
"verified_at": "2026-07-20T18:04:11Z"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}Resolver Custom Hostnames
Set a custom resolver hostname's unresolved-scan fallback policy
Set what a dead-end scan on this hostname does: hosted_404 (default, a Closient-hosted brand-themed 404) or redirect (a 307 to a dashboard-configured destination). Returns 422 if the hostname isn’t the org’s, or if mode is redirect and redirect_url isn’t a well-formed absolute https URL. Requires CHANGE permission — this is the only write path for the policy, and by construction the destination can never be sourced from anything but this request’s own redirect_url field (see apps.resolver.services.fallback_policy).
POST
/
resolver
/
api
/
v1
/
organizations
/
{organization_id}
/
custom-hostnames
/
fallback-policy
Set a custom resolver hostname's unresolved-scan fallback policy
curl --request POST \
--url https://www.closient.com/resolver/api/v1/organizations/{organization_id}/custom-hostnames/fallback-policy \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"hostname": "id.theirco.com",
"mode": "redirect",
"redirect_url": "https://theirco.com/not-found",
"utm_campaign": "",
"utm_content": "",
"utm_medium": "",
"utm_source": "closient-resolver",
"utm_term": ""
}
'import requests
url = "https://www.closient.com/resolver/api/v1/organizations/{organization_id}/custom-hostnames/fallback-policy"
payload = {
"hostname": "id.theirco.com",
"mode": "redirect",
"redirect_url": "https://theirco.com/not-found",
"utm_campaign": "",
"utm_content": "",
"utm_medium": "",
"utm_source": "closient-resolver",
"utm_term": ""
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
hostname: 'id.theirco.com',
mode: 'redirect',
redirect_url: 'https://theirco.com/not-found',
utm_campaign: '',
utm_content: '',
utm_medium: '',
utm_source: 'closient-resolver',
utm_term: ''
})
};
fetch('https://www.closient.com/resolver/api/v1/organizations/{organization_id}/custom-hostnames/fallback-policy', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://www.closient.com/resolver/api/v1/organizations/{organization_id}/custom-hostnames/fallback-policy",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'hostname' => 'id.theirco.com',
'mode' => 'redirect',
'redirect_url' => 'https://theirco.com/not-found',
'utm_campaign' => '',
'utm_content' => '',
'utm_medium' => '',
'utm_source' => 'closient-resolver',
'utm_term' => ''
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://www.closient.com/resolver/api/v1/organizations/{organization_id}/custom-hostnames/fallback-policy"
payload := strings.NewReader("{\n \"hostname\": \"id.theirco.com\",\n \"mode\": \"redirect\",\n \"redirect_url\": \"https://theirco.com/not-found\",\n \"utm_campaign\": \"\",\n \"utm_content\": \"\",\n \"utm_medium\": \"\",\n \"utm_source\": \"closient-resolver\",\n \"utm_term\": \"\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://www.closient.com/resolver/api/v1/organizations/{organization_id}/custom-hostnames/fallback-policy")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"hostname\": \"id.theirco.com\",\n \"mode\": \"redirect\",\n \"redirect_url\": \"https://theirco.com/not-found\",\n \"utm_campaign\": \"\",\n \"utm_content\": \"\",\n \"utm_medium\": \"\",\n \"utm_source\": \"closient-resolver\",\n \"utm_term\": \"\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://www.closient.com/resolver/api/v1/organizations/{organization_id}/custom-hostnames/fallback-policy")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"hostname\": \"id.theirco.com\",\n \"mode\": \"redirect\",\n \"redirect_url\": \"https://theirco.com/not-found\",\n \"utm_campaign\": \"\",\n \"utm_content\": \"\",\n \"utm_medium\": \"\",\n \"utm_source\": \"closient-resolver\",\n \"utm_term\": \"\"\n}"
response = http.request(request)
puts response.read_body{
"fallback_mode": "hosted_404",
"fallback_redirect_url": "",
"fallback_utm_campaign": "",
"fallback_utm_content": "",
"fallback_utm_medium": "",
"fallback_utm_source": "",
"fallback_utm_term": "",
"hostname": "id.theirco.com",
"is_qr_ready": true,
"last_checked_at": "2026-07-20T18:04:11Z",
"last_error": "",
"setup": {
"challenge": {
"name": "_closient-challenge.id.theirco.com",
"purpose": "ownership_verification",
"type": "CNAME",
"value": "9f86d081884c.verify.gtin.one"
},
"qr_density_warning": false,
"serving": {
"name": "id.theirco.com",
"purpose": "resolver_routing",
"type": "CNAME",
"value": "gtin.one"
}
},
"status": "VERIFIED",
"tls_status": "ACTIVE",
"verified_at": "2026-07-20T18:04:11Z"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}{
"detail": "The requested resource was not found.",
"error_code": "not_found",
"retryable": false,
"status": 404,
"timestamp": "2026-03-31T12:00:00+00:00",
"title": "Not Found",
"type": "https://closient.com/docs/errors/not_found"
}Authorizations
APIKeyHeaderAuthOAuthTokenAuthCookieGatedSessionAuth
Path Parameters
Organization UUID.
Required string length:
22Pattern:
^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$Body
application/json
Set a custom hostname's unresolved-scan fallback policy (C-4755).
redirect_url and the utm_* overrides are ignored (left at their
submitted value, but only redirect_url is actually validated) unless
mode is redirect — the model layer requires redirect_url to be
a well-formed absolute https URL in that case and rejects the save
otherwise (surfaced here as 422).
The registered hostname to set the policy for.
hosted_404 (default) or redirect.
Available options:
hosted_404, redirect Required, absolute https URL, when mode is redirect.
Maximum string length:
2048Overrides the platform default utm_source.
Maximum string length:
255Overrides the platform default utm_medium.
Maximum string length:
255Overrides the platform default utm_campaign.
Maximum string length:
255Overrides the platform default utm_term.
Maximum string length:
255Overrides the platform default utm_content.
Maximum string length:
255Response
OK
The customer-owned hostname, normalized lowercase.
Ownership-verification state.
Available options:
PENDING, VERIFIED, DISABLED Edge-certificate state (read-only; driven by the cert pipeline).
Available options:
NOT_REQUESTED, PENDING, ACTIVE, FAILED True when this hostname is VERIFIED and its edge cert is ACTIVE — QRs may print against it.
Unresolved-scan fallback policy (C-4755). hosted_404 (default) or redirect.
Available options:
hosted_404, redirect DNS records to publish for this hostname.
Show child attributes
Show child attributes
Example:
{
"challenge": {
"name": "_closient-challenge.id.theirco.com",
"purpose": "ownership_verification",
"type": "CNAME",
"value": "9f86d081884c.verify.gtin.one"
},
"qr_density_warning": false,
"serving": {
"name": "id.theirco.com",
"purpose": "resolver_routing",
"type": "CNAME",
"value": "gtin.one"
}
}
ISO-8601 timestamp of the last successful verification, or null.
ISO-8601 timestamp of the last verification attempt, or null.
Reason the last verification attempt failed (empty on success).
Reason the last certificate issuance or renewal check failed (empty on success).
ISO-8601 time before which certificate issuance will not be retried, or null when not in cooldown.
ISO-8601 expiry of the certificate seen at the last successful probe, or null.
Redirect-mode destination. Empty unless fallback_mode is redirect.
Maximum string length:
2048UTM source override for redirect-mode fallback. Empty = platform default.
Maximum string length:
255UTM medium override for redirect-mode fallback. Empty = platform default.
Maximum string length:
255UTM campaign override for redirect-mode fallback. Empty = platform default.
Maximum string length:
255UTM term override for redirect-mode fallback. Empty = platform default.
Maximum string length:
255UTM content override for redirect-mode fallback. Empty = platform default.
Maximum string length:
255