Skip to main content

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 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
Each submission gets its own cover page with its own data. The original template is cloned internally — your template is never modified.

​
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. 
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).
​
cover_page.company_name
string
required
The company or individual name displayed prominently on the cover page. Long names wrap to multiple lines automatically.
​
cover_page.entry_count
integer
required
Total number of entries in the claim. Displayed in the header subtitle.
​
cover_page.entry_type
string
required
Type of recovery or claim. Displayed in the header subtitle. Example: "IEEPA tariff recovery", "Section 301 recovery".
​
cover_page.estimated_refund
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.
​
cover_page.phase_1_amount
integer
required
Phase 1 net refund amount in whole dollars.
​
cover_page.phase_1_entries
integer
required
Number of entries in Phase 1.
​
cover_page.phase_1_label
string
required
Phase 1 description. Example: "Filing Immediately".
​
cover_page.phase_2_amount
integer
required
Phase 2 net refund amount in whole dollars.
​
cover_page.phase_2_entries
integer
required
Number of entries in Phase 2.
​
cover_page.phase_2_label
string
required
Phase 2 description. Example: "After Liquidation".
​
cover_page.base_interest_1
integer
required
Phase 1 estimated base refund plus interest, before admin fees.
​
cover_page.admin_fee_1
integer
required
Phase 1 admin/broker fee. Must be a negative value. Example: -43125 renders as - $43,125.
​
cover_page.base_interest_2
integer
required
Phase 2 estimated base refund plus interest, before admin fees.
​
cover_page.admin_fee_2
integer
required
Phase 2 admin/broker fee. Must be a negative value. Example: -11200 renders as - $11,200.

​
Cover page layout

The generated cover page is a single US Letter (8.5” x 11”) PDF with these sections:
SectionContent
HeaderCompany name, entry count, and entry type
Hero cardLarge emerald card displaying the total estimated_refund
Phase cardsTwo side-by-side cards showing each phase’s amount and entry count
Fee breakdownTwo side-by-side tables: base + interest, admin fee, and net per phase
Trust indicatorsThree green dots: “Zero cost upfront”, “Broker files under their license”, “90-120 day timeline”
CTA”Sign below to authorize your refund”
FooterLegal 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 work together for a seamless one-click signing experience: 
{
  "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

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

All monetary values are integers in whole dollars. No cents, no decimals. 345175 means $345,175.
Admin fees must be negative. Pass -43125, not 43125.
  • 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

StatusCauseFix
400Missing required cover_page fieldInclude all 14 fields listed above.
404Invalid template_idVerify the template exists and belongs to your account.
500PDF generation failedEnsure all values are integers (not strings or nulls).
500Template PDF is corrupted or missingRe-upload the template document.