Use the Surface Tag with a Custom Domain

Use a custom domain when your Surface forms are served from a verified domain such as forms.example.com. The Surface Tag will use that domain for form communication, visitor identification, journey tracking, external-form events, and open triggers.

If your forms use forms.withsurface.com, you do not need to change your Surface Tag.

Before You Begin

You need access to:

Your Surface environment settings
Your DNS provider
Your website's global <head> code

Only use a domain that is verified in Surface and controlled by your organization.

1. Add and Verify Your Domain

In Surface, go to Settings → Domains.
Click Add domain and enter the subdomain you want to use.
Add the CNAME record and, when shown, the TXT verification record to your DNS provider.
Wait for the DNS changes to propagate.
Return to Settings → Domains and click Verify.

Continue only after the domain status is Verified.

2. Connect the Domain to Your Form

Open the form in Surface.
Go to Settings → Custom Domain.
Select the verified domain.

Use the custom-domain form URL generated by Surface when embedding or sharing the form.

3. Update the Surface Tag

Add data-custom-domain to the Surface Tag in your website's <head>:

<!-- Start Surface Tag -->
<script
  src="https://cdn.jsdelivr.net/gh/trysurface/scripts@latest/surface_tag.min.js"
  site-id="YOUR_SITE_ID"
  data-custom-domain="forms.example.com">
</script>
<!-- End Surface Tag -->

Replace YOUR_SITE_ID with the Site ID from Settings → Overview, and replace forms.example.com with the exact verified domain shown in Surface.

Using a cookie banner? Keep data-custom-domain and add data-consent-mode to the same tag, then follow the cookie consent setup guide to connect your banner's choices.

We recommend entering the hostname without https://. An HTTPS origin such as https://forms.example.com also works.

Do not include http://, a path, query string, fragment, or credentials. Invalid values fall back to https://forms.withsurface.com.

4. Optimize Loading

If you use connection hints, point them at the custom domain instead of forms.withsurface.com:

<link rel="dns-prefetch" href="https://forms.example.com">
<link rel="preconnect" href="https://forms.example.com" crossorigin>
<link rel="prefetch" href="YOUR_CUSTOM_DOMAIN_FORM_URL" as="document">

Replace YOUR_CUSTOM_DOMAIN_FORM_URL with the full form URL generated by Surface.

5. Test the Installation

Publish the website changes.
Open a page that contains the Surface Tag and a Surface form.
Open and submit the form with test data.
Confirm that the response appears in Surface.

If the form does not load or tracking is missing, confirm that:

The domain status is Verified in Surface.
The form is connected to that domain.
data-custom-domain exactly matches the verified hostname.
The form URL uses the same custom domain.

To return to the default Surface domain, remove data-custom-domain from the Surface Tag and use the form URL generated for forms.withsurface.com.