Docs / Your customers' DNS

Your customers' DNS

The two DNS records your customers add to connect their own domain to your SaaS, how to word the instructions, and the usual DNS console mistakes.

When you register a hostname, the API returns two records. Show both to your customer exactly as returned: the values are unique to each registration.

Type	Name	Value	Why
TXT	`_custom-domain-challenge.forms.acme.com`	`custom-domain-verify=…`	Proves they control the name.
CNAME	`forms.acme.com`	`edge.customdomainapi.com` (Free) or your edge name	Sends the hostname’s traffic to the edge.

Instructions you can give your customer

To use forms.acme.com for your workspace, add these two records at the company that manages your domain’s DNS (your registrar, Cloudflare, Route 53, …). It usually takes a few minutes; we’ll let you know when your address works.

Common mistakes

Each record’s help text in the API response covers these too.

The console adds the domain itself. Many consoles want only the part before the domain: _custom-domain-challenge.forms and forms for acme.com. Entering the full name there produces forms.acme.com.acme.com.
An A or AAAA record is still there. A name can’t have a CNAME and other records at once: remove old A/AAAA records for the hostname.
A proxy is on. With Cloudflare, set the CNAME to DNS only (grey cloud). The edge must see the visitor’s TLS connection to issue the certificate.
Quotes. Some consoles add quotes around TXT values; that’s fine. Don’t add extra spaces.
Apex domains. Only subdomains such as forms.acme.com or www.acme.com can be used, not acme.com itself.

After they add the records

The domain’s checks report what was found, in plain words, such as cname_target_mismatch: CNAME points to old-host.example. Show the message to your customer, and let them press a “check again” button that calls POST /v1/domains/{id}/checks.