Custom Domains

curl -X POST "https://spitshake.io/api/custom_domains" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "sign.example-firm.com"
  }'

{
  "domain": {
    "id": 42,
    "domain": "sign.example-firm.com",
    "status": "pending",
    "primary": false,
    "verification_record_name": "_spitshake-verification.sign.example-firm.com",
    "verification_record_value": "spitshake-verify=9905bf29d0fa929f119ad5baeba8d9952fc2df44f8e65c9770113bddbe483093",
    "ssl_status": null,
    "dns_verified_at": null,
    "ssl_provisioned_at": null,
    "last_checked_at": null,
    "last_error": null,
    "branding": {},
    "website_url": null,
    "created_at": "2026-04-08T15:00:00Z"
  }
}

{
  "error": ["Domain has already been taken"]
}

{
  "error": ["Domain must be a valid hostname"]
}

{
  "error": ["Domain is reserved and cannot be used"]
}

Overview

Custom domains let you serve signing pages, and the links in your emails, SMS and webhooks, from your own branded domain (e.g., sign.example-firm.com) instead of the default spitshake.io. SpitShake verifies that you own the domain and then provisions its TLS certificate for you. All custom domain endpoints require an admin API token or user; anyone else gets 403 {"error": "Forbidden"}.

Add a Custom Domain

curl -X POST "https://spitshake.io/api/custom_domains" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "sign.example-firm.com"
  }'

{
  "domain": {
    "id": 42,
    "domain": "sign.example-firm.com",
    "status": "pending",
    "primary": false,
    "verification_record_name": "_spitshake-verification.sign.example-firm.com",
    "verification_record_value": "spitshake-verify=9905bf29d0fa929f119ad5baeba8d9952fc2df44f8e65c9770113bddbe483093",
    "ssl_status": null,
    "dns_verified_at": null,
    "ssl_provisioned_at": null,
    "last_checked_at": null,
    "last_error": null,
    "branding": {},
    "website_url": null,
    "created_at": "2026-04-08T15:00:00Z"
  }
}

{
  "error": ["Domain has already been taken"]
}

{
  "error": ["Domain must be a valid hostname"]
}

{
  "error": ["Domain is reserved and cannot be used"]
}

The domain is lowercased and trimmed before it is saved.
A domain can be registered only once across all SpitShake accounts, and a removed domain still counts: re-adding a domain you deleted returns “Domain has already been taken”.
SpitShake’s own hosts (such as spitshake.io, app.spitshake.io and api.spitshake.io) are reserved.

DNS Setup

After adding a domain, create two DNS records with your DNS provider. Settings → Custom Domains → DNS Configuration Instructions shows both, with copy buttons.

Required Records

Type	Name	Value	Purpose
CNAME	`sign.example-firm.com`	The target shown in Settings → Custom Domains (the host you use SpitShake on, e.g. `spitshake.io`)	Routes traffic to SpitShake
TXT	`_spitshake-verification.sign.example-firm.com`	`spitshake-verify=9905bf29d0fa929f119ad5baeba8d9952fc2df44f8e65c9770113bddbe483093`	Proves domain ownership

Use the exact verification_record_name and verification_record_value from the API response. The token is 64 hexadecimal characters and is unique to the domain. A domain added before the DocuTrust → SpitShake rename may keep its older _docutrust-verification.<domain> = docutrust-verify=<token> record; either one verifies.

DNS propagation can take up to 48 hours, though most providers finish within 15 minutes. SpitShake checks the TXT record automatically: first 30 seconds after you add the domain, then after 1, 2 and 4 minutes, and then every 5 minutes. After 60 checks without finding the record (about 5 hours) the domain is marked failed with "DNS verification timed out after 60 attempts". You can check it yourself at any time.

Status Lifecycle

Custom domains progress through the following statuses:

pending → dns_verified → ssl_pending → active
   │                          │
   └──────────────────────────┴──▶ failed

any status ──▶ removed (after DELETE)

Status	Description
`pending`	Domain added, waiting for the TXT record
`dns_verified`	TXT record confirmed; certificate provisioning is starting
`ssl_pending`	SpitShake is provisioning the domain’s TLS certificate. This usually takes a few minutes
`active`	Domain is live. Signing links can use it and it can be made primary
`failed`	DNS verification or certificate provisioning timed out. `last_error` says which
`removed`	Domain has been deleted from the account

While a domain is ssl_pending, SpitShake re-checks the certificate after 30 seconds, 1 minute and 2 minutes, then every 5 minutes, plus a sweep every 15 minutes. When the certificate is issued the domain becomes active and ssl_provisioned_at is set. If the domain has had 120 checks in total (DNS and certificate checks together) without a certificate, it is marked failed with "SSL provisioning timed out".

Verify Domain DNS

Trigger a DNS check yourself. Useful if you have just added the TXT record and do not want to wait for the next automatic check. On success, certificate provisioning starts at once.

curl -X POST "https://spitshake.io/api/custom_domains/42/verify" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

{
  "domain": {
    "id": 42,
    "domain": "sign.example-firm.com",
    "status": "dns_verified",
    "primary": false,
    "verification_record_name": "_spitshake-verification.sign.example-firm.com",
    "verification_record_value": "spitshake-verify=9905bf29d0fa929f119ad5baeba8d9952fc2df44f8e65c9770113bddbe483093",
    "ssl_status": null,
    "dns_verified_at": "2026-04-08T15:20:00Z",
    "ssl_provisioned_at": null,
    "last_checked_at": "2026-04-08T15:20:00Z",
    "last_error": null,
    "branding": {},
    "website_url": null,
    "created_at": "2026-04-08T15:00:00Z"
  },
  "message": "DNS verified. SSL provisioning started."
}

{
  "domain": {
    "id": 42,
    "domain": "sign.example-firm.com",
    "status": "pending",
    "primary": false,
    "verification_record_name": "_spitshake-verification.sign.example-firm.com",
    "verification_record_value": "spitshake-verify=9905bf29d0fa929f119ad5baeba8d9952fc2df44f8e65c9770113bddbe483093",
    "ssl_status": null,
    "dns_verified_at": null,
    "ssl_provisioned_at": null,
    "last_checked_at": "2026-04-08T15:20:00Z",
    "last_error": null,
    "branding": {},
    "website_url": null,
    "created_at": "2026-04-08T15:00:00Z"
  },
  "message": "DNS verification failed. Please ensure the TXT record is set correctly."
}

Check Domain Status

Read a domain’s current status without triggering a check. Poll this while a domain moves from pending to active. GET /api/custom_domains/{id} returns the same body.

curl -X GET "https://spitshake.io/api/custom_domains/42/status" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

{
  "domain": {
    "id": 42,
    "domain": "sign.example-firm.com",
    "status": "ssl_pending",
    "primary": false,
    "verification_record_name": "_spitshake-verification.sign.example-firm.com",
    "verification_record_value": "spitshake-verify=9905bf29d0fa929f119ad5baeba8d9952fc2df44f8e65c9770113bddbe483093",
    "ssl_status": "pending_validation",
    "dns_verified_at": "2026-04-08T15:20:00Z",
    "ssl_provisioned_at": null,
    "last_checked_at": "2026-04-08T15:21:00Z",
    "last_error": null,
    "branding": {},
    "website_url": null,
    "created_at": "2026-04-08T15:00:00Z"
  }
}

Use status to decide what to do next. ssl_status is informational; it reads active once the certificate is issued.

List All Domains

Returns the account’s domains, newest first. Removed domains are not listed. account_branding is what a domain’s unset branding keys fall back to (the account’s own signing-page branding).

curl -X GET "https://spitshake.io/api/custom_domains" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

{
  "domains": [
    {
      "id": 43,
      "domain": "docs.example-firm.com",
      "status": "pending",
      "primary": false,
      "verification_record_name": "_spitshake-verification.docs.example-firm.com",
      "verification_record_value": "spitshake-verify=c280e49a43f47bb9036e7cfc2a27c07e572dc461bc6ac7df56d2e73b4d8ac6ce",
      "ssl_status": null,
      "dns_verified_at": null,
      "ssl_provisioned_at": null,
      "last_checked_at": null,
      "last_error": null,
      "branding": {},
      "website_url": null,
      "created_at": "2026-04-08T16:00:00Z"
    },
    {
      "id": 42,
      "domain": "sign.example-firm.com",
      "status": "active",
      "primary": true,
      "verification_record_name": "_spitshake-verification.sign.example-firm.com",
      "verification_record_value": "spitshake-verify=9905bf29d0fa929f119ad5baeba8d9952fc2df44f8e65c9770113bddbe483093",
      "ssl_status": "active",
      "dns_verified_at": "2026-04-08T15:20:00Z",
      "ssl_provisioned_at": "2026-04-08T15:22:00Z",
      "last_checked_at": "2026-04-08T15:22:00Z",
      "last_error": null,
      "branding": {},
      "website_url": null,
      "created_at": "2026-04-08T15:00:00Z"
    }
  ],
  "account_branding": {
    "display_title": "Example Firm SecureSign",
    "logo_url": "https://cdn.example.com/example-firm/logo.png",
    "company_name": "Example Firm LLP",
    "primary_button_color": "#2f5d8a",
    "header_color": null,
    "show_branding": true
  }
}

Set Primary Domain

Designate a domain as the primary. Submissions that do not pick a domain themselves (see below) use the primary domain for their signing links and emails. Only one domain can be primary; setting a new one unsets the old one.

curl -X POST "https://spitshake.io/api/custom_domains/42/set_primary" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

{
  "domain": {
    "id": 42,
    "domain": "sign.example-firm.com",
    "status": "active",
    "primary": true,
    "verification_record_name": "_spitshake-verification.sign.example-firm.com",
    "verification_record_value": "spitshake-verify=9905bf29d0fa929f119ad5baeba8d9952fc2df44f8e65c9770113bddbe483093",
    "ssl_status": "active",
    "dns_verified_at": "2026-04-08T15:20:00Z",
    "ssl_provisioned_at": "2026-04-08T15:22:00Z",
    "last_checked_at": "2026-04-08T15:22:00Z",
    "last_error": null,
    "branding": {},
    "website_url": null,
    "created_at": "2026-04-08T15:00:00Z"
  }
}

{
  "error": "Domain must be active to set as primary"
}

Choose a Domain per Template or Submission

Once a domain is active you can pick it for a single template or a single submission with preferences.custom_domain, instead of (or on top of) setting an account-wide primary. Resolution is submission › template › account primary › spitshake.io. In the Template Builder the same choice is the Signing domain picker in Template Settings.

POST /api/submissions
{
  "template_id": "tpl_7VQhP2tM9xA1kR8bN",
  "preferences": { "custom_domain": "sign.example-firm.com" },
  "submitters": [{ "role": "Client", "email": "client@example.com" }]
}

The value must be one of the account’s active domains, or "default" to force spitshake.io for that template/submission even when a primary custom domain is set. Anything else is rejected with 422 and the message lists your active domains:
422
{ "error": ["Preferences custom_domain must be one of your active custom domains (sign.example-firm.com) or \"default\""] }
The chosen host is used everywhere a link is minted for that submission: each submitter’s signing_url in the POST /api/submissions response, the embed_src links returned by POST /api/submissions/emails, invitation/reminder/completion emails, SMS invitations, and the download_urls in submission.completed webhooks.
The submission also takes the domain’s branding (next section), so the page and emails look like the brand in the URL without passing any branding keys.

Brand each Domain

Each domain carries its own header title, logo, favicon, colours and “Powered by” setting. The keys are display_title, logo_url, favicon_url, company_name, primary_button_color, header_color and show_branding — the same set a brand uses. Every submission sent on the domain shows them — whether the domain was chosen on the submission, on its template, or is the account’s primary. Set them in Settings → Custom Domains → Edit branding (with a live preview of the signer’s header), or via the API:

Saving replaces the domain’s whole branding object (PUT is not a merge). The Settings editor sends every key it shows, Favicon URL included, and leaves blank fields out, so a blank field in the editor clears that key.

curl -X PUT "https://spitshake.io/api/custom_domains/42" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "branding": {
      "display_title": "Example Firm",
      "logo_url": "https://cdn.example.com/example-firm/logo.png",
      "favicon_url": "https://cdn.example.com/example-firm/favicon.png",
      "company_name": "Example Firm LLP",
      "primary_button_color": "#2f5d8a",
      "header_color": "#14213d",
      "show_branding": false
    }
  }'

{
  "domain": {
    "id": 42,
    "domain": "sign.example-firm.com",
    "status": "active",
    "primary": false,
    "verification_record_name": "_spitshake-verification.sign.example-firm.com",
    "verification_record_value": "spitshake-verify=9905bf29d0fa929f119ad5baeba8d9952fc2df44f8e65c9770113bddbe483093",
    "ssl_status": "active",
    "dns_verified_at": "2026-04-08T15:20:00Z",
    "ssl_provisioned_at": "2026-04-08T15:22:00Z",
    "last_checked_at": "2026-04-08T15:22:00Z",
    "last_error": null,
    "branding": {
      "display_title": "Example Firm",
      "logo_url": "https://cdn.example.com/example-firm/logo.png",
      "favicon_url": "https://cdn.example.com/example-firm/favicon.png",
      "company_name": "Example Firm LLP",
      "primary_button_color": "#2f5d8a",
      "header_color": "#14213d",
      "show_branding": false
    },
    "website_url": null,
    "created_at": "2026-04-08T15:00:00Z"
  }
}

{
  "error": "Branding has unknown keys: display_titel (allowed: display_title, logo_url, favicon_url, company_name, primary_button_color, header_color, show_branding)"
}

{
  "error": "Branding header_color must be a #rrggbb colour dark enough for white header text"
}

PUT replaces the whole object; a key sent as null or "" is removed and falls back to the account. A branding value that is not an object is rejected with 422 {"error": "branding must be an object"}.
header_color sets the header bar verbatim; without it the header is primary_button_color darkened 20%. It must be a #rrggbb dark enough for the header’s white text. logo_url and favicon_url must be http(s) URLs; the favicon falls back to the logo.
display_title and company_name also make up the browser tab title, and favicon_url is the tab icon (see Brands).
Resolution is submission › submission’s brand › template › template’s brand › domain › account, key by key. A template that sets display_title: "Example Firm Retainer" keeps its title on this domain and takes the logo and colour from the domain; a submission can still override any single key. A brand selected with preferences.brand_id on the template or submission outranks the domain’s branding.
custom_domain: "default" uses no domain branding. A domain that is removed stops contributing branding, like it stops contributing links.
Branding is looked up when the signing page or an email is rendered, not copied onto the submission — editing a domain changes it for every signer who has not finished yet.

Send the Bare Domain to Your Website

Your signing domain only serves signing links (https://sign.example-firm.com/s/…). Someone who opens the domain itself, https://sign.example-firm.com/, is sent to your own site when you set website_url; without it they get a plain “Not found” page. SpitShake’s own homepage and marketing pages are never shown on your domain. Set it in Settings → Custom Domains → Edit branding → Your website, or via the API. Each of branding and website_url is changed only when it is sent, so this leaves the domain’s branding alone:

curl -X PUT "https://spitshake.io/api/custom_domains/42" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "website_url": "https://example-firm.com" }'

website_url must be an http(s) URL; null or "" clears it.
The redirect is a 302, so you can change the destination at any time.
Signing links, the signing pages’ assets and the API are not affected.

Delete a Domain

Remove a custom domain. Its status becomes removed and it is no longer primary. If it was the primary domain, signing links fall back to spitshake.io; submissions or templates that chose it with preferences.custom_domain fall back to the next level. A removed domain cannot be added again (see Add a Custom Domain).

curl -X DELETE "https://spitshake.io/api/custom_domains/43" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

{
  "success": true
}

curl -X POST "https://spitshake.io/api/custom_domains" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "sign.example-firm.com"
  }'

{
  "domain": {
    "id": 42,
    "domain": "sign.example-firm.com",
    "status": "pending",
    "primary": false,
    "verification_record_name": "_spitshake-verification.sign.example-firm.com",
    "verification_record_value": "spitshake-verify=9905bf29d0fa929f119ad5baeba8d9952fc2df44f8e65c9770113bddbe483093",
    "ssl_status": null,
    "dns_verified_at": null,
    "ssl_provisioned_at": null,
    "last_checked_at": null,
    "last_error": null,
    "branding": {},
    "website_url": null,
    "created_at": "2026-04-08T15:00:00Z"
  }
}

{
  "error": ["Domain has already been taken"]
}

{
  "error": ["Domain must be a valid hostname"]
}

{
  "error": ["Domain is reserved and cannot be used"]
}

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

Overview

Add a Custom Domain

DNS Setup

Required Records

Status Lifecycle

Verify Domain DNS

Check Domain Status

List All Domains

Set Primary Domain

Choose a Domain per Template or Submission

Brand each Domain

Send the Bare Domain to Your Website

Delete a Domain

​Overview

​Add a Custom Domain

​DNS Setup

​Required Records

​Status Lifecycle

​Verify Domain DNS

​Check Domain Status

​List All Domains

​Set Primary Domain

​Choose a Domain per Template or Submission

​Brand each Domain

​Send the Bare Domain to Your Website

​Delete a Domain

Overview

Add a Custom Domain

DNS Setup

Required Records

Status Lifecycle

Verify Domain DNS

Check Domain Status

List All Domains

Set Primary Domain

Choose a Domain per Template or Submission

Brand each Domain

Send the Bare Domain to Your Website

Delete a Domain