Skip to main content
A custom domain is returned as a JSON object with object: "custom_domain". The same shape is used for create, get, list, and the domain field embedded in the verify response.

​
Example

{
  "object": "custom_domain",
  "id": "2c8a4d6f-1e3b-4d5a-9b7c-8e1f2a3b4c5d",
  "domain": "acme.com",
  "verified": true,
  "verified_at": "2026-05-25T11:08:42+00:00",
  "last_checked_at": "2026-05-25T11:08:42+00:00",
  "check_error": null,
  "verification_records": [],
  "created_at": "2026-05-25T11:00:00+00:00"
}

​
Identifiers

​
object
string
required
Always "custom_domain".
​
id
string (uuid)
required
Stable UUID. Use it in /custom-domains/{id} and as the domain_id foreign key on routes.
​
domain
string
required
The hostname. Lowercased and trimmed on write. www.<apex> inputs are canonicalised to the apex form — www.acme.com becomes acme.com, and www is auto-paired as a redirect.

​
Verification

​
verified
boolean
required
Convenience boolean: true when verified_at is non-null.
​
verified_at
string (datetime) | null
required
When the domain became live. Null while DNS is still propagating or if the customer hasn’t published the records yet.
​
last_checked_at
string (datetime) | null
required
Most recent verification attempt. Updated by both the automatic poll and manual POST /custom-domains/{id}/verify calls.
​
check_error
string | null
required
Human-readable reason the last check failed, if any. Cleared on the next successful verify.
​
verification_records
array
required
DNS records the customer must publish to prove ownership and route traffic. The array is empty once the domain is verified.

​
Timestamps

​
created_at
string (datetime)
required
When the domain was connected. ISO 8601.

​
Delete behaviour

DELETE /custom-domains/{id} returns 204 No Content. The hostname is disconnected from the TLS terminator, the row is removed, and the billable add-on slot is released. Every custom_domain_route attached to the domain is removed by the database FK cascade — there is no soft-delete.
Deleting takes the domain offline immediately. Inbound traffic falls through to whatever your DNS now resolves to.