Template & Submission Preferences

Preferences control signing behavior at three levels. When the same key exists at multiple levels, the submission preference wins, then template, then account settings.

Submission preference  →  Template preference  →  Account setting
     (highest)                                       (lowest)

Branding keys have two extra layers — a named brand and the sending custom domain. See Priority resolution.

Template preferences

Set via PUT /api/templates/:id in the preferences object.

Signing behavior

Key	Type	Default	Description
`quick_sign_mode`	string	`"confirmation_modal"`	Signing UX mode. Submissions created via `POST /api/submissions` default to `confirmation_modal` when no mode is specified; `normal` applies only when no mode is set at the submission or template level. See Quick sign modes.
`redirect_url`	string	`null`	Where to send signers after completion, unless the submission or signer sets its own (see Redirect after signing). Must be an absolute `http(s)` URL; anything else is rejected with `422` and `"code": "invalid_redirect_url"`.
`disable_start_screen`	boolean	`false`	Skip the “Welcome” start page and go directly to signing.
`start_screen_title`	string	`null`	Custom title for the start page (e.g. “Review Your Agreement”).
`start_screen_message`	string	`null`	Custom message body for the start page.
`skip_start_when_prefilled`	boolean	`false`	Auto-skip the start page when all required fields are pre-filled or auto-generatable.
`auto_prefill_signatures`	boolean	`true`	Auto-generate typed signatures and initials from the submitter’s name.
`carousel_review_documents`	array	`[]`	Document UUIDs whose fields the signer confirms in the `confirmation_modal` carousel. See Review fields in the carousel.
`require_email_2fa`	boolean	`false`	Require email verification code before the signer can access the document.
`signing_nav_style`	string	`"standard"`	Bottom navigation on the signing page. `"standard"` shows Previous/Next buttons. `"branded_bar"` shows a sticky bar in the header colour with icon buttons: Back, Next, Clear, and a menu holding Complete & Submit (plus Review & Sign when quick sign is on). Both styles show a card above the buttons that names the current field and fills it in place. Also set in the Template Builder under Signing Experience → Bottom navigation style.

Branding

Everything the signer sees in the signing page header — and in the invitation, reminder and completion emails — resolves key by key through submission › submission’s brand › template › template’s brand › custom domain › account (full rules in Priority resolution). A brand is a named set of these keys saved on the account and selected with brand_id, for accounts that sign on behalf of more than one brand. The custom-domain level is the branding of the domain the submission is sent on, so choosing a domain brings its look with it.

Key	Type	Default	Description
`display_title`	string	`"<display name> SecureSign"`	Header title, shown verbatim (no suffix is added). Also the email title and the first part of the browser-tab title. When no level sets it, the header shows the account’s white-label display name followed by “SecureSign”. See Tab title and favicon.
`logo_url`	string	Account `logo_url`	Logo shown beside the title and in emails (recommended 200x50px).
`favicon_url`	string	`logo_url`	Browser-tab icon on the signing page, resolved per submission through the same layers. Only an `http(s)` URL is used; otherwise the resolved `logo_url` is, and with neither the page sets no icon.
`company_name`	string	Account `company_name`	Alt text / email wordmark, and the second part of the browser-tab title (falling back to the account’s display name, then its name).
`primary_button_color`	string	Account default	Hex color for the buttons (e.g. `"#3A9191"`), for the header — darkened 20% — unless `header_color` is set, and for the accents: the current-field ring, “Prefilled” badge, checkboxes and the signature window, darkened until white text reads on it.
`header_color`	string	`primary_button_color` darkened 20%	Header bar colour, used verbatim, for brands whose header is not a shade of their button colour. Only a `#rrggbb` dark enough for the header’s white text is used; a light or malformed value is not rejected here but is ignored when rendered, and the header falls back to the derived shade.
`show_branding`	boolean	`true`	`false` removes the “Powered by SpitShake” line under the title and from the footer of every email for the submission.
`brand_id`	integer	—	Id of one of the account’s brands. Its branding fills any of the keys above that this template leaves unset, and outranks the custom domain’s branding. An id that is not one of your brands is ignored.

Domain

Key	Type	Default	Description
`custom_domain`	string	Account primary domain	Host every link for this template’s submissions is minted on: the signing link in the API response, emails and SMS, and the document URLs in webhooks. Must be one of your active custom domains, or `"default"` to force `spitshake.io` even when the account has a primary custom domain. Any other value is rejected with `422`.

ESIGN disclosure

Key	Type	Default	Description
`esign_disclosure_style`	string	`"inline"`	How signers give ESIGN consent: `"inline"` — a consent line under the final sign button (clicking it consents); `"modal"` — a pop-up before the form. See ESIGN Consent.
`esign_disclosure_enabled`	boolean	`true`	Collect ESIGN Act consent before signing. Required for legal compliance in most cases.
`esign_disclosure_title`	string	`"Consent to Electronic Records & Signatures"`	Custom modal title.
`esign_disclosure_body`	string	Federal default text	Custom disclosure body. Leave blank for the built-in federally-compliant text.
`esign_disclosure_agree_button_text`	string	`"I Agree & Continue"`	Custom button label.
`esign_disclosure_bypass_acknowledged`	boolean	`false`	B2B acknowledgment that the sender takes responsibility for bypassing the disclosure. Both this AND `esign_disclosure_enabled: false` must be set to suppress the modal.

Variables

Key	Type	Default	Description
`variables`	array	`[]`	Template variables for dynamic content. Each entry: `{ "key": "company_name", "label": "Company Name" }`.

Example

PUT /api/templates/tpl_7VQhP2tM9xA1kR8bN
{
  "preferences": {
    "quick_sign_mode": "confirmation_modal",
    "redirect_url": "https://yourapp.com/thank-you",
    "disable_start_screen": true,
    "auto_prefill_signatures": true,
    "primary_button_color": "#3A9191",
    "brand_id": 7,
    "esign_disclosure_enabled": true,
    "esign_disclosure_title": "Electronic Signature Consent",
    "esign_disclosure_body": "By proceeding, you consent to electronic signing."
  }
}

Submission preferences

Set via POST /api/submissions in the preferences object. These override template-level preferences for the specific submission.

Signing behavior

Key	Type	Default	Description
`quick_sign_mode`	string	Template default	Override the template’s quick sign mode for this submission.
`completed_redirect_url`	string	Template default	Where to send every signer of this submission after they complete (also accepted as a top-level `completed_redirect_url` parameter, and per signer as `submitters[].completed_redirect_url`). Must be an absolute `http(s)` URL; otherwise `422` with `"code": "invalid_redirect_url"`. See Redirect after signing.
`redirect_url`	string	Template default	Also honoured here, after `completed_redirect_url`.

Branding

Same keys as the template Branding table — display_title, logo_url, favicon_url, company_name, primary_button_color, header_color, show_branding and brand_id — each overriding the template and account for this submission only. Use these to brand a document for the signer’s counterparty (e.g. "display_title": "Acme Legal Retainer"). A submission’s brand_id replaces the template’s brand: the template’s brand is not used at all, even for keys the submission’s brand leaves unset (the template’s own branding keys still apply). A submission brand_id that is not one of your brands is ignored, and the template’s brand is still not used.

Domain

Key	Type	Default	Description
`custom_domain`	string	Template, then account primary	Host for this submission’s links (see the template Domain table). Must be an active custom domain of the account or `"default"`; otherwise `422`. Every submitter in the `POST /api/submissions` response carries the resulting absolute `signing_url`.

An unknown or inactive domain is rejected before anything is sent. The message lists your active domains (or says “none yet”):

{
  "error": [
    "Preferences custom_domain must be one of your active custom domains (sign.example-firm.com) or \"default\""
  ]
}

POST /api/submissions
{
  "template_id": "tpl_7VQhP2tM9xA1kR8bN",
  "preferences": {
    "display_title": "Acme Legal Retainer",
    "brand_id": 7,
    "show_branding": false,
    "custom_domain": "sign.example.com"
  },
  "submitters": [{ "role": "Client", "email": "client@example.com" }]
}

Email customization

Key	Type	Default	Description
`message_subject`	string	Account default	Custom email subject. Supports placeholders.
`message_body`	string	Account default	Custom email body. Supports placeholders.
`reply_to`	string	`null`	Reply-to email address for invitation emails.
`bcc_completed`	string	`null`	BCC email address for completion notifications.

Available placeholders: {{template.name}}, {{submitter.name}}, {{submitter.email}}, {{submitter.link}}, {{account.name}}

Variable values

Key	Type	Default	Description
`variable_values`	object	`{}`	Key-value pairs for template variables. Keys must match variables defined in the template preferences.

Pre-fill behavior

Pass as a top-level prefill_behavior parameter (not inside preferences):

Key	Type	Default	Description
`skip_if_prefilled`	boolean	`true`	Pre-filled fields are skipped in the field-by-field navigation (but still rendered as read-only overlays on the document).
`editable_if_prefilled`	boolean	`false`	Whether signers can edit pre-filled values.

Example

POST /api/submissions
{
  "template_id": "tpl_7VQhP2tM9xA1kR8bN",
  "send_email": true,
  "submitters": [{
    "email": "signer@example.com",
    "name": "Jane Smith",
    "values": {
      "Client Legal Name": "Acme Corp",
      "Effective Date": "2026-04-21"
    }
  }],
  "preferences": {
    "quick_sign_mode": "confirmation_modal",
    "completed_redirect_url": "https://yourapp.com/done",
    "message_subject": "{{account.name}} — Please sign {{template.name}}",
    "message_body": "Hi {{submitter.name}}, your documents are ready."
  },
  "prefill_behavior": {
    "skip_if_prefilled": true,
    "editable_if_prefilled": false
  }
}

Account settings

Set via PUT /api/settings in the settings object. These are the lowest-priority defaults — overridden by template and submission preferences.

Key	Type	Description
`company_name`	string	Organization name shown in emails and signing page header.
`logo_url`	string	Logo URL for emails and signing page (recommended: 200x50px).
`primary_button_color`	string	Default brand color for all templates.
`header_color`	string	Default header bar colour (a dark `#rrggbb`; otherwise ignored when rendered).
`completion_message`	string	Custom message shown on the signing page after completion. Falls back to default if blank.
`redirect_url`	string	Saved, but not currently used. Set the redirect on the template or submission instead.
`signature_id_enabled`	boolean	Show signature ID on signed documents.
`download_enabled`	boolean	Allow signers to download signed documents.
`show_confetti`	boolean	Show confetti animation on completion.
`show_branding`	boolean	Show “Powered by SpitShake” attribution.
`cache_signatures_locally`	boolean	Cache signature drawings in the browser for reuse.

Priority resolution

When the same concept is configurable at multiple levels:

Setting	Submission	Template	Account
Quick sign mode	`preferences.quick_sign_mode`	`preferences.quick_sign_mode`	—
Redirect URL	`submitters[].completed_redirect_url`, then `preferences.completed_redirect_url`, then `preferences.redirect_url`	`preferences.redirect_url`	—
Branding (title, logo, favicon, colours, “Powered by”)	`preferences.<key>`, then its `preferences.brand_id` brand	`preferences.<key>`, then its `preferences.brand_id` brand (only if the submission sets no `brand_id`)	the sending custom domain’s `branding`, then `settings.<key>` (the title comes from the white-label display name; there is no account favicon setting)
Link host	`preferences.custom_domain`	`preferences.custom_domain`	primary custom domain
ESIGN disclosure	—	`preferences.esign_disclosure_*`	—
Completion message	—	—	`settings.completion_message`
Email subject/body	`preferences.message_subject/body`	—	`settings.email_templates`

The signing page resolves each setting top-down: submission first, then template, then account. The first non-null value wins. The redirect is the exception: it has no account level (see below). Branding is resolved per key through six layers, and the first non-empty value (null and "" are skipped) wins:

submission prefs → submission's brand → template prefs → template's brand → custom domain branding → account settings
                   (if it sets brand_id)                  (if the submission
                                                            sets no brand_id)

A submission’s brand_id replaces the template’s brand rather than being merged with it, and any brand outranks the custom domain. An unknown or deleted brand_id contributes nothing. See Brands.

Redirect after signing

The signer is sent to the first absolute http(s) URL in this list:

submitters[].completed_redirect_url → submission completed_redirect_url → submission preferences.redirect_url → template preferences.redirect_url

The account’s settings.redirect_url is not part of the chain. With none set, the signer stays on the completion screen. When the signer finishes, they see the completion screen and are then redirected (the whole tab when the signing page is embedded in an iframe). A signer who opens the link again later, or who still has the form open in another tab, gets an Already Completed page instead. It shows a Continue link to the same URL (opened in the top window) and does not redirect on its own, so the destination is not visited twice. Writes from a stale tab are refused with 422 and "code": "already_completed", and the page reloads to show Already Completed.

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

Template & Submission Preferences

Template preferences

Signing behavior

Branding

Domain

ESIGN disclosure

Variables

Example

Submission preferences

Signing behavior

Branding

Domain

Email customization

Variable values

Pre-fill behavior

Example

Account settings

Priority resolution

Redirect after signing

​Template preferences

​Signing behavior

​Branding

​Domain

​ESIGN disclosure

​Variables

​Example

​Submission preferences

​Signing behavior

​Branding

​Domain

​Email customization

​Variable values

​Pre-fill behavior

​Example

​Account settings

​Priority resolution

​Redirect after signing

Template preferences

Signing behavior

Branding

Domain

ESIGN disclosure

Variables

Example

Submission preferences

Signing behavior

Branding

Domain

Email customization

Variable values

Pre-fill behavior

Example

Account settings

Priority resolution

Redirect after signing