> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spitshake.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Sign

> Streamline the signing experience with pre-filled fields, auto-generated signatures, and one-click completion.

Quick Sign lets you pre-fill all required fields before sending a document, so the signer only needs to review and confirm — no manual data entry. Combined with auto-generated signatures, signers can complete a document in seconds.

## Quick Sign modes

Set the `quick_sign_mode` parameter when creating a submission to control the signing experience:

| Mode                    | Behavior                                                                                                  | Best for                                                        |
| ----------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `normal`                | Standard field-by-field signing. No shortcuts.                                                            | Complex documents requiring careful review.                     |
| `review_and_sign`       | Shows a summary of pre-filled data before signing begins. Signer reviews, then proceeds.                  | Documents where the signer should verify prefilled information. |
| `confirmation_modal`    | Displays a carousel modal with signature/initials fields. Signer taps through each one. **Default mode.** | One-click signing flows with pre-filled data.                   |
| `auto_scroll_signature` | Automatically scrolls to the first signature field after the document loads.                              | Documents where signers just need to sign at the bottom.        |

## How it works

1. You create a submission with pre-filled field values via the API
2. SpitShake evaluates whether all required fields are satisfied
3. Based on the `quick_sign_mode`, the signing UI adapts:
   * **`confirmation_modal`**: If all required fields are pre-filled, the signer sees a carousel overlay presenting each signature/initials field one at a time. They can sign with a single tap per field.
   * **`auto_scroll_signature`**: The page scrolls directly to the first unsigned signature field.
   * **`review_and_sign`**: A summary screen lists all pre-filled values for the signer to review before proceeding.

### Auto-generated signatures

When a signer's `name` is provided and `auto_prefill_signatures` is enabled (default: `true`), SpitShake automatically generates a cursive signature image from the name. The signer can accept the auto-generated signature or draw/type their own.

Auto-generated signatures are created for both `signature` and `initials` field types.

## API usage

### Create a Quick Sign submission

```bash theme={null}
curl -X POST https://spitshake.io/api/submissions \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tpl_7VQhP2tM9xA1kR8bN",
    "quick_sign_mode": "confirmation_modal",
    "submitters": [
      {
        "role": "Signer",
        "email": "jane@example.com",
        "name": "Jane Doe",
        "values": {
          "full_name": "Jane Doe",
          "company": "Acme Corp",
          "title": "CEO",
          "date": "2026-05-01"
        }
      }
    ]
  }'
```

### Parameters

<ParamField body="quick_sign_mode" type="string" default="confirmation_modal">
  The signing UX mode. One of: `normal`, `review_and_sign`, `confirmation_modal`, `auto_scroll_signature`.
</ParamField>

<ParamField body="submitters[].name" type="string">
  The signer's full name. When provided, SpitShake auto-generates a cursive signature image from this name (unless `auto_prefill_signatures` is `false` in template preferences).
</ParamField>

<ParamField body="submitters[].values" type="object">
  Key-value pairs matching field keys defined in the template schema. Pre-fills fields before the signer opens the document.
</ParamField>

### Response

The response includes a `signing_url` for each submitter. When the signer opens this URL, the Quick Sign experience activates automatically based on the mode you selected.

```json theme={null}
{
  "id": 203,
  "slug": "k9m2x4p7",
  "status": "pending",
  "submitters": [
    {
      "id": 405,
      "uuid": "a1b2c3d4-...",
      "email": "jane@example.com",
      "role": "Signer",
      "status": "sent",
      "signing_url": "https://spitshake.io/s/k9m2x4p7"
    }
  ]
}
```

### Validate before creating

Use the read-only qualification endpoint with the same inputs that affect submission creation:

```bash theme={null}
curl -X POST https://spitshake.io/api/templates/tpl_7VQhP2tM9xA1kR8bN/validate_quick_sign \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quick_sign_mode": "confirmation_modal",
    "variable_values": { "case_number": "A-1042" },
    "submitters": [{
      "role": "Signer",
      "name": "Jane Doe",
      "values": { "full_name": "Jane Doe" },
      "fields": [{ "name": "title", "default_value": "Director" }]
    }]
  }'
```

```json theme={null}
{
  "quick_sign_mode": "confirmation_modal",
  "all_fields_qualified": true,
  "gates": {
    "esign_disclosure": true,
    "identity_verification": false,
    "email_2fa": false,
    "kba": false,
    "phone_verification": false,
    "payment": false
  },
  "one_click": false,
  "submitters": [{
    "uuid": "61187bd6-77f7-48a3-a182-747b796b1cd7",
    "role": "Signer",
    "fields_qualified": true,
    "blocking_fields": []
  }]
}
```

`gates` are screens that the signer will still see. The endpoint guarantees field-level
eligibility; it does not promise a literal one-click experience unless `one_click` is `true`.
That requires all fields to qualify, `confirmation_modal` mode, and every gate to be `false`.
For example, the ESIGN disclosure remains a gate unless both the disable flag and its B2B
acknowledgment are set on the template.

If `submitters` is omitted, the endpoint validates every template submitter with no prefills.
Within the array, `uuid` takes precedence over `role`; conflicting, unknown, ambiguous, or
duplicate mappings return `422`.

## Review fields in the carousel

You can have the signer confirm specific **prefilled** values inside the confirmation modal carousel — useful for fields like "Authorized Signatory" or "Title" where you want explicit confirmation (or an edit) before signing, all within the same modal flow with no context switching. Turn this on **per field** with the `review_in_carousel` preference, or for an **entire document** with the `carousel_review_documents` template preference.

By default, prefilled fields are **not** shown as review steps — the signer only taps through signatures. Review steps appear only for the fields (or documents) you explicitly flag.

### How it works

1. Fields with `review_in_carousel: true` appear **before** signature/initials steps in the carousel
2. If the field is also editable (not readonly), the signer sees an input they can modify
3. If the field is read-only, the signer sees the value displayed for confirmation
4. The signer taps "Confirm" on each review step, then "Next" on signature steps, then "Complete"

### Example flow

A signer opens a document with `authorized_signatory`, `title`, `signature`, and `initials` fields — all prefilled:

| Step | Field                | Display                                          | Button   |
| ---- | -------------------- | ------------------------------------------------ | -------- |
| 1    | Authorized Signatory | Editable text input, prefilled with "Jane Smith" | CONFIRM  |
| 2    | Title                | Editable text input, prefilled with "CFO"        | CONFIRM  |
| 3    | Signature            | Auto-generated signature image                   | NEXT     |
| 4    | Initials             | Auto-generated initials image                    | COMPLETE |

### Setting `review_in_carousel` on fields

Set it per field in the template schema via the API:

```bash theme={null}
curl -X PUT https://spitshake.io/api/templates/tpl_... \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": [
      {
        "uuid": "existing-field-uuid",
        "name": "Authorized Signatory",
        "key": "authorized_signatory",
        "type": "text",
        "required": true,
        "preferences": {
          "review_in_carousel": true,
          "editable_if_prefilled": true
        }
      },
      {
        "uuid": "existing-field-uuid-2",
        "name": "Title",
        "key": "title",
        "type": "text",
        "required": true,
        "preferences": {
          "review_in_carousel": true,
          "editable_if_prefilled": true
        }
      }
    ]
  }'
```

<Note>
  `review_in_carousel` only affects the `confirmation_modal` Quick Sign mode. In other modes, these fields behave normally (inline in the document).
</Note>

### Review an entire document

To make the signer confirm **every** field in a specific document, add that document's UUID to the template's `carousel_review_documents` preference. This is convenient for an attachment such as a government form or a key exhibit where each value should be verified, without flagging fields one at a time.

```bash theme={null}
curl -X PUT https://spitshake.io/api/templates/tpl_... \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "carousel_review_documents": ["doc-uuid-1", "doc-uuid-2"]
    }
  }'
```

Every non-signature field whose area falls in one of these documents becomes a review step. Document UUIDs come from `template_documents[].uuid` (returned by `GET /api/templates/:id`).

<Note>
  Template `preferences` is replaced wholesale on update. To turn document review **off** again, send `carousel_review_documents: []` — an empty object `{}` is treated as "no change" by the update endpoint, so send the empty array explicitly.
</Note>

### Precedence and opting out

A field's effective review setting resolves in this order:

1. Field `review_in_carousel: true` → always reviewed
2. Field `review_in_carousel: false` → never reviewed, even if its document is flagged
3. Otherwise, reviewed if its document is in `carousel_review_documents`
4. Otherwise, not reviewed (default)

So an individual field can opt **out** of a reviewed document by setting `review_in_carousel: false` on itself:

```json theme={null}
{
  "uuid": "existing-field-uuid",
  "name": "Internal Reference",
  "preferences": { "review_in_carousel": false }
}
```

Fields hidden by an unmet conditional rule, and `stamp` fields, are never shown as review steps — even when their document is flagged.

### Field type support in carousel

| Field Type                | Carousel Display                            |
| ------------------------- | ------------------------------------------- |
| `text`, `number`, `phone` | Editable text input (if not readonly)       |
| `date`                    | Date picker (if not readonly)               |
| `select`, `radio`         | Dropdown selector (if not readonly)         |
| `checkbox`                | Toggle with label (if not readonly)         |
| `signature`, `initials`   | Signature image with redraw option (always) |
| All types when readonly   | Read-only confirmation card                 |

## Mode details

### `confirmation_modal`

The most streamlined mode. When all required fields are pre-filled:

1. The start screen is skipped automatically
2. A full-screen carousel modal appears immediately
3. Review fields (if any) appear first — the signer confirms or edits each value
4. Signature and initials fields appear next with auto-generated images
5. The signer taps through each step, then "Complete" on the last one
6. The document is submitted

If any required fields are **not** pre-filled, the modal does not appear and the signer fills in missing fields manually before the modal triggers.

<Note>
  Signature/initials fields are grouped by type — one carousel step per type. Review fields each get their own step. A template with 2 review fields, 3 signature fields, and 1 initials field produces 4 carousel steps total (2 review + 1 signature + 1 initials).
</Note>

### `auto_scroll_signature`

A lighter touch than `confirmation_modal`:

1. The document loads normally
2. The view automatically smooth-scrolls to the first signature field
3. The signer can review the document by scrolling up, or sign immediately
4. No modal overlay — the signer interacts with the document directly

### `review_and_sign`

Best for documents where the signer should verify pre-filled data:

1. The welcome screen displays a summary of all pre-filled field values
2. The signer reviews the data and clicks "Continue"
3. Standard signing flow begins with fields already populated
4. The signer can modify any editable pre-filled field before submitting

### `normal`

Standard signing with no Quick Sign behavior:

* No auto-scrolling, no modal, no pre-fill summary
* Signatures are not auto-generated from the signer's name
* The signer fills in every field manually

## Template-level configuration

Quick Sign mode can also be set at the template level in template preferences. The submission-level `quick_sign_mode` parameter always takes precedence over the template default.

```bash theme={null}
curl -X PUT https://spitshake.io/api/templates/tpl_7VQhP2tM9xA1kR8bN \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "quick_sign_mode": "confirmation_modal",
      "auto_prefill_signatures": true,
      "skip_start_when_prefilled": true
    }
  }'
```

| Preference                  | Type    | Default                | Description                                                            |
| --------------------------- | ------- | ---------------------- | ---------------------------------------------------------------------- |
| `quick_sign_mode`           | string  | `"confirmation_modal"` | Default Quick Sign mode for submissions created from this template.    |
| `auto_prefill_signatures`   | boolean | `true`                 | Auto-generate signature images from the signer's name.                 |
| `skip_start_when_prefilled` | boolean | `false`                | Skip the welcome/start screen when all required fields are pre-filled. |

## Precedence rules

The effective Quick Sign mode for a signing session is resolved in this order:

1. **Submission-level** `quick_sign_mode` parameter (highest priority)
2. **Template-level** `preferences.quick_sign_mode`
3. **Default**: `"confirmation_modal"`

## Best practices

<CardGroup cols={2}>
  <Card title="Pre-fill everything" icon="fill-drip">
    Quick Sign works best when **all** required fields are pre-filled via `submitters[].values`. The confirmation modal only triggers when nothing is left for the signer to type.
  </Card>

  <Card title="Always include name" icon="user">
    Pass the signer's `name` so SpitShake can auto-generate signatures. Without a name, the signer must draw or type their signature manually.
  </Card>

  <Card title="Use field keys" icon="key">
    Pre-fill values using the field `key` (not `name` or `uuid`). Set field keys in the template builder or via `PUT /api/templates/:id`.
  </Card>

  <Card title="Test with review mode" icon="magnifying-glass">
    During development, use `review_and_sign` to verify that your pre-fill values map correctly before switching to `confirmation_modal` for production.
  </Card>
</CardGroup>

## E-sign consent disclosure

Before any signature is captured, signers see a federally-required consent disclosure modal (ESIGN Act § 101(c)). This modal:

* Shows automatically on first visit
* Requires the signer to click "I Agree & Continue" before proceeding
* Is re-shown if the signer returns after 24 hours (same-session refreshes skip it)
* On mobile, buttons are sticky at the bottom of the screen so they're always accessible
* Can be customized via template preferences (`esign_disclosure_title`, `esign_disclosure_body`, `esign_disclosure_agree_button_text`)
* Can be disabled for B2B/non-consumer transactions via `esign_disclosure_enabled: false` + `esign_disclosure_bypass_acknowledged: true`

<Warning>
  **Updating template schema via PUT**: `PUT /api/templates/:id` replaces the **entire** schema array. Always GET the full schema first, modify the fields you need, and PUT the complete array back. Sending a partial schema will delete all fields not included. If this happens, use the [Restore Version](/api-reference/templates/restore-template-version) endpoint to roll back.
</Warning>