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)

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`	URL to redirect signers after completion.
`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.

Branding

Key	Type	Default	Description
`primary_button_color`	string	Account default	Hex color for buttons and accents (e.g. `"#3A9191"`). Overrides the account-level setting.

ESIGN disclosure

Key	Type	Default	Description
`esign_disclosure_enabled`	boolean	`true`	Show the ESIGN Act consent modal 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",
    "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	Override the post-completion redirect URL.

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.
`completion_message`	string	Custom message shown on the signing page after completion. Falls back to default if blank.
`redirect_url`	string	Default redirect URL for all templates.
`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	`preferences.completed_redirect_url`	`preferences.redirect_url`	`settings.redirect_url`
Button color	—	`preferences.primary_button_color`	`settings.primary_button_color`
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.

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

Template & Submission Preferences

Template preferences

Signing behavior

Branding

ESIGN disclosure

Variables

Example

Submission preferences

Signing behavior

Email customization

Variable values

Pre-fill behavior

Example

Account settings

Priority resolution

​Template preferences

​Signing behavior

​Branding

​ESIGN disclosure

​Variables

​Example

​Submission preferences

​Signing behavior

​Email customization

​Variable values

​Pre-fill behavior

​Example

​Account settings

​Priority resolution

Template preferences

Signing behavior

Branding

ESIGN disclosure

Variables

Example

Submission preferences

Signing behavior

Email customization

Variable values

Pre-fill behavior

Example

Account settings

Priority resolution