> ## 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.

# Cover Page

> Generate a branded, data-driven cover page that is prepended to the signing package — personalized per submission.

Cover pages let you generate a dynamic, branded first page for each submission with personalized financial data, company details, and a call-to-action. The cover page is prepended to the template PDF automatically — the original template is never modified.

## How it works

1. You pass a `cover_page` object when creating a submission
2. SpitShake generates a single-page PDF with your data
3. The cover page is prepended to the template as page 1
4. All existing field positions are automatically shifted by +1 page
5. The signer sees the cover page first, then scrolls to the signing fields

<Note>
  Each submission gets its own cover page with its own data. The original template is cloned internally — your template is never modified.
</Note>

## API usage

### Create a submission with cover page

Add the `cover_page` object to your `POST /api/submissions` request. All 14 fields are required when `cover_page` is present.

```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_dKvEa39aA22Cz4k6N",
    "quick_sign_mode": "confirmation_modal",
    "submitters": [
      {
        "role": "Importer",
        "email": "john@example.com",
        "name": "John Smith"
      }
    ],
    "cover_page": {
      "company_name": "Upper Echelon Products LLC",
      "entry_count": 142,
      "entry_type": "IEEPA tariff recovery",
      "estimated_refund": 345175,
      "phase_1_amount": 244375,
      "phase_1_entries": 98,
      "phase_1_label": "Filing Immediately",
      "phase_2_amount": 100800,
      "phase_2_entries": 44,
      "phase_2_label": "After Liquidation",
      "base_interest_1": 287500,
      "admin_fee_1": -43125,
      "base_interest_2": 112000,
      "admin_fee_2": -11200
    }
  }'
```

### Cover page parameters

All fields are **required** when the `cover_page` object is present. Omitting `cover_page` entirely creates a normal submission (backward compatible).

<ParamField body="cover_page.company_name" type="string" required>
  The company or individual name displayed prominently on the cover page. Long names wrap to multiple lines automatically.
</ParamField>

<ParamField body="cover_page.entry_count" type="integer" required>
  Total number of entries in the claim. Displayed in the header subtitle.
</ParamField>

<ParamField body="cover_page.entry_type" type="string" required>
  Type of recovery or claim. Displayed in the header subtitle. Example: `"IEEPA tariff recovery"`, `"Section 301 recovery"`.
</ParamField>

<ParamField body="cover_page.estimated_refund" type="integer" required>
  Total estimated net refund in **whole dollars** (no cents, no decimals). This is the hero number displayed in a large emerald card. Example: `345175` renders as `$345,175`.
</ParamField>

<ParamField body="cover_page.phase_1_amount" type="integer" required>
  Phase 1 net refund amount in whole dollars.
</ParamField>

<ParamField body="cover_page.phase_1_entries" type="integer" required>
  Number of entries in Phase 1.
</ParamField>

<ParamField body="cover_page.phase_1_label" type="string" required>
  Phase 1 description. Example: `"Filing Immediately"`.
</ParamField>

<ParamField body="cover_page.phase_2_amount" type="integer" required>
  Phase 2 net refund amount in whole dollars.
</ParamField>

<ParamField body="cover_page.phase_2_entries" type="integer" required>
  Number of entries in Phase 2.
</ParamField>

<ParamField body="cover_page.phase_2_label" type="string" required>
  Phase 2 description. Example: `"After Liquidation"`.
</ParamField>

<ParamField body="cover_page.base_interest_1" type="integer" required>
  Phase 1 estimated base refund plus interest, before admin fees.
</ParamField>

<ParamField body="cover_page.admin_fee_1" type="integer" required>
  Phase 1 admin/broker fee. **Must be a negative value.** Example: `-43125` renders as `- $43,125`.
</ParamField>

<ParamField body="cover_page.base_interest_2" type="integer" required>
  Phase 2 estimated base refund plus interest, before admin fees.
</ParamField>

<ParamField body="cover_page.admin_fee_2" type="integer" required>
  Phase 2 admin/broker fee. **Must be a negative value.** Example: `-11200` renders as `- $11,200`.
</ParamField>

## Cover page layout

The generated cover page is a single US Letter (8.5" x 11") PDF with these sections:

| Section              | Content                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------ |
| **Header**           | Company name, entry count, and entry type                                                        |
| **Hero card**        | Large emerald card displaying the total `estimated_refund`                                       |
| **Phase cards**      | Two side-by-side cards showing each phase's amount and entry count                               |
| **Fee breakdown**    | Two side-by-side tables: base + interest, admin fee, and net per phase                           |
| **Trust indicators** | Three green dots: "Zero cost upfront", "Broker files under their license", "90-120 day timeline" |
| **CTA**              | "Sign below to authorize your refund"                                                            |
| **Footer**           | Legal disclaimer and company information                                                         |

All dollar amounts are dynamically centered and scale to fit regardless of digit count — from `$500` to `$500,000,000`.

## Combining with Quick Sign

Cover page and [Quick Sign](/features/quick-sign) work together for a seamless one-click signing experience:

```json theme={null}
{
  "template_id": "tpl_dKvEa39aA22Cz4k6N",
  "quick_sign_mode": "confirmation_modal",
  "submitters": [
    {
      "role": "Importer",
      "email": "john@example.com",
      "name": "John Smith",
      "values": {
        "full_name": "John Smith",
        "company": "Upper Echelon Products LLC",
        "date_signed": "2026-05-01"
      }
    }
  ],
  "cover_page": {
    "company_name": "Upper Echelon Products LLC",
    "entry_count": 142,
    "entry_type": "IEEPA tariff recovery",
    "estimated_refund": 345175,
    "phase_1_amount": 244375,
    "phase_1_entries": 98,
    "phase_1_label": "Filing Immediately",
    "phase_2_amount": 100800,
    "phase_2_entries": 44,
    "phase_2_label": "After Liquidation",
    "base_interest_1": 287500,
    "admin_fee_1": -43125,
    "base_interest_2": 112000,
    "admin_fee_2": -11200
  }
}
```

The signer opens the link, sees the cover page with their refund summary, then a carousel modal presents their signature fields with auto-generated signatures. One tap per field and they're done.

## Node.js / TypeScript example

```typescript theme={null}
const response = await fetch('https://spitshake.io/api/submissions', {
  method: 'POST',
  headers: {
    'X-Auth-Token': process.env.SPITSHAKE_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    template_id: 'tpl_dKvEa39aA22Cz4k6N',
    quick_sign_mode: 'confirmation_modal',
    submitters: [
      {
        role: 'Importer',
        email: importerEmail,
        name: importerName,
      },
    ],
    cover_page: {
      company_name: companyName,
      entry_count: entries.length,
      entry_type: 'IEEPA tariff recovery',
      estimated_refund: Math.round(phase1Net + phase2Net),
      phase_1_amount: Math.round(phase1Net),
      phase_1_entries: phase1Entries.length,
      phase_1_label: 'Filing Immediately',
      phase_2_amount: Math.round(phase2Net),
      phase_2_entries: phase2Entries.length,
      phase_2_label: 'After Liquidation',
      base_interest_1: Math.round(phase1Gross),
      admin_fee_1: Math.round(-phase1Fee),
      base_interest_2: Math.round(phase2Gross),
      admin_fee_2: Math.round(-phase2Fee),
    },
  }),
});

const submission = await response.json();
console.log(submission.submitters[0].signing_url);
```

## Important notes

<Warning>
  **All monetary values are integers in whole dollars.** No cents, no decimals. `345175` means \$345,175.
</Warning>

<Warning>
  **Admin fees must be negative.** Pass `-43125`, not `43125`.
</Warning>

* The math should be internally consistent:
  * `estimated_refund` = `phase_1_amount` + `phase_2_amount`
  * `phase_1_amount` = `base_interest_1` + `admin_fee_1`
  * `phase_2_amount` = `base_interest_2` + `admin_fee_2`
  * SpitShake does **not** validate the math — it renders whatever you send. But signers will notice if the numbers don't add up.

* Omitting `cover_page` entirely creates a normal submission with no cover page (backward compatible).

* The cover page is generated per submission. Each signer gets their own personalized page.

* Field positions on the original template are automatically shifted by +1 page to account for the prepended cover page.

## Enabling in the template builder

You can also enable cover pages from the template builder UI:

1. Open the template in the builder
2. Go to **Template Settings**
3. Toggle **Cover Page** on
4. The first page of the first document shows a "Dynamic" badge in the builder

When enabled via the builder, submissions created from the dashboard will prompt for cover page data. API submissions always control cover page inclusion via the `cover_page` parameter regardless of this setting.

## Error handling

| Status | Cause                                | Fix                                                     |
| ------ | ------------------------------------ | ------------------------------------------------------- |
| `400`  | Missing required `cover_page` field  | Include all 14 fields listed above.                     |
| `404`  | Invalid `template_id`                | Verify the template exists and belongs to your account. |
| `500`  | PDF generation failed                | Ensure all values are integers (not strings or nulls).  |
| `500`  | Template PDF is corrupted or missing | Re-upload the template document.                        |