Custom Domains

Overview

Custom domains let you serve signing pages, emails, and API endpoints from your own branded domain (e.g., sign.yourcompany.com) instead of the default spitshake.io. DocuTrust handles DNS verification and automatic SSL certificate provisioning.

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.yourcompany.com"
  }'

{
  "id": 42,
  "domain": "sign.yourcompany.com",
  "status": "pending",
  "primary": false,
  "verification_record_name": "_docutrust-verify.sign.yourcompany.com",
  "verification_record_value": "docutrust-verify=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "ssl_status": "pending",
  "dns_verified_at": null,
  "ssl_provisioned_at": null,
  "last_checked_at": null,
  "last_error": null,
  "created_at": "2026-04-08T15:00:00Z"
}

{
  "error": "The domain sign.yourcompany.com is already registered to this account."
}

{
  "error": "Invalid domain format. Please provide a valid subdomain (e.g., sign.yourcompany.com)."
}

DNS Setup

After adding a domain, create the following DNS records with your domain registrar:

Required Records

Type	Name	Value	Purpose
CNAME	`sign.yourcompany.com`	`spitshake.io`	Routes traffic to DocuTrust
TXT	`_docutrust-verify.sign.yourcompany.com`	`docutrust-verify=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6`	Proves domain ownership

DNS propagation can take up to 48 hours, though most providers complete within 15 minutes. DocuTrust checks DNS records automatically every 10 minutes.

Status Lifecycle

Custom domains progress through the following statuses:

pending → dns_verified → ssl_pending → active
                                         │
                                         ├──▶ failed (recoverable)
                                         └──▶ removed (terminal)

Status	Description
`pending`	Domain added, awaiting DNS verification
`dns_verified`	TXT record confirmed, SSL provisioning starting
`ssl_pending`	SSL certificate is being issued by Let’s Encrypt
`active`	Domain is fully operational with valid SSL
`failed`	DNS or SSL verification failed (see `last_error` for details)
`removed`	Domain has been deleted from the account

Verify Domain DNS

Manually trigger a DNS verification check. Useful if you have just added the DNS records and do not want to wait for the automatic check cycle.

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

{
  "id": 42,
  "domain": "sign.yourcompany.com",
  "status": "dns_verified",
  "primary": false,
  "verification_record_name": "_docutrust-verify.sign.yourcompany.com",
  "verification_record_value": "docutrust-verify=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "ssl_status": "pending",
  "dns_verified_at": "2026-04-08T15:20:00Z",
  "ssl_provisioned_at": null,
  "last_checked_at": "2026-04-08T15:20:00Z",
  "last_error": null,
  "created_at": "2026-04-08T15:00:00Z"
}

{
  "id": 42,
  "domain": "sign.yourcompany.com",
  "status": "pending",
  "primary": false,
  "verification_record_name": "_docutrust-verify.sign.yourcompany.com",
  "verification_record_value": "docutrust-verify=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "ssl_status": "pending",
  "dns_verified_at": null,
  "ssl_provisioned_at": null,
  "last_checked_at": "2026-04-08T15:20:00Z",
  "last_error": "TXT record not found at _docutrust-verify.sign.yourcompany.com. Please check your DNS configuration.",
  "created_at": "2026-04-08T15:00:00Z"
}

List All Domains

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

[
  {
    "id": 42,
    "domain": "sign.yourcompany.com",
    "status": "active",
    "primary": true,
    "verification_record_name": "_docutrust-verify.sign.yourcompany.com",
    "verification_record_value": "docutrust-verify=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "ssl_status": "active",
    "dns_verified_at": "2026-04-08T15:20:00Z",
    "ssl_provisioned_at": "2026-04-08T15:22:00Z",
    "last_checked_at": "2026-04-08T16:00:00Z",
    "last_error": null,
    "created_at": "2026-04-08T15:00:00Z"
  },
  {
    "id": 43,
    "domain": "docs.yourcompany.com",
    "status": "pending",
    "primary": false,
    "verification_record_name": "_docutrust-verify.docs.yourcompany.com",
    "verification_record_value": "docutrust-verify=f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3",
    "ssl_status": "pending",
    "dns_verified_at": null,
    "ssl_provisioned_at": null,
    "last_checked_at": null,
    "last_error": null,
    "created_at": "2026-04-08T16:00:00Z"
  }
]

Set Primary Domain

Designate a domain as the primary. The primary domain is used in all outgoing emails and signing URLs.

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

{
  "id": 42,
  "domain": "sign.yourcompany.com",
  "status": "active",
  "primary": true,
  "verification_record_name": "_docutrust-verify.sign.yourcompany.com",
  "verification_record_value": "docutrust-verify=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "ssl_status": "active",
  "dns_verified_at": "2026-04-08T15:20:00Z",
  "ssl_provisioned_at": "2026-04-08T15:22:00Z",
  "last_checked_at": "2026-04-08T16:00:00Z",
  "last_error": null,
  "created_at": "2026-04-08T15:00:00Z"
}

{
  "error": "Only active domains can be set as primary. Current status: dns_verified"
}

Delete a Domain

Remove a custom domain. If the deleted domain was primary, signing URLs revert to spitshake.io.

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

{
  "id": 43,
  "domain": "docs.yourcompany.com",
  "status": "removed",
  "primary": false,
  "verification_record_name": "_docutrust-verify.docs.yourcompany.com",
  "verification_record_value": "docutrust-verify=f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3",
  "ssl_status": "pending",
  "dns_verified_at": null,
  "ssl_provisioned_at": null,
  "last_checked_at": null,
  "last_error": null,
  "created_at": "2026-04-08T16:00:00Z"
}

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

Overview

Add a Custom Domain

DNS Setup

Required Records

Status Lifecycle

Verify Domain DNS

List All Domains

Set Primary Domain

Delete a Domain

​Overview

​Add a Custom Domain

​DNS Setup

​Required Records

​Status Lifecycle

​Verify Domain DNS

​List All Domains

​Set Primary Domain

​Delete a Domain

Overview

Add a Custom Domain

DNS Setup

Required Records

Status Lifecycle

Verify Domain DNS

List All Domains

Set Primary Domain

Delete a Domain