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.

​
Overview

Bulk import lets you create many submissions from a single CSV file. Upload a CSV with submitter information, preview the parsed data, and create all submissions in one request. For files with more than 100 rows, processing runs in the background with status polling.

​
CSV Format

The CSV file must include a header row. Column names are matched to template field names (case-insensitive). The email column is required for each submitter role. 
email,name,phone,company
jane@example.com,Jane Doe,+15551234567,Acme Corp
bob@example.com,Bob Smith,+15559876543,Widget Inc
maria@example.com,Maria Garcia,+15555551234,TechStart LLC
david@example.com,David Park,+15558887777,Global Solutions
lisa@example.com,Lisa Chen,+15552223333,Bright Ideas Co
For templates with multiple submitter roles, prefix columns with the role name: 
signer_email,signer_name,witness_email,witness_name
jane@example.com,Jane Doe,bob@example.com,Bob Smith
maria@example.com,Maria Garcia,david@example.com,David Park
lisa@example.com,Lisa Chen,alex@example.com,Alex Rivera

​
Preview CSV

Upload a CSV to validate and preview the parsed data before creating submissions. This endpoint does not create any records. 
curl -X POST "https://spitshake.io/api/templates/{template_id}/bulk/preview" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -F "csv=@/path/to/submitters.csv"

{
  "valid": true,
  "total_rows": 5,
  "columns": ["email", "name", "phone", "company"],
  "column_mappings": {
    "email": "email",
    "name": "Full Name",
    "phone": "Phone Number",
    "company": "Company"
  },
  "preview_rows": [
    {
      "row_number": 1,
      "valid": true,
      "errors": [],
      "data": {
        "email": "jane@example.com",
        "name": "Jane Doe",
        "phone": "+15551234567",
        "company": "Acme Corp"
      }
    },
    {
      "row_number": 2,
      "valid": true,
      "errors": [],
      "data": {
        "email": "bob@example.com",
        "name": "Bob Smith",
        "phone": "+15559876543",
        "company": "Widget Inc"
      }
    },
    {
      "row_number": 3,
      "valid": true,
      "errors": [],
      "data": {
        "email": "maria@example.com",
        "name": "Maria Garcia",
        "phone": "+15555551234",
        "company": "TechStart LLC"
      }
    },
    {
      "row_number": 4,
      "valid": true,
      "errors": [],
      "data": {
        "email": "david@example.com",
        "name": "David Park",
        "phone": "+15558887777",
        "company": "Global Solutions"
      }
    },
    {
      "row_number": 5,
      "valid": true,
      "errors": [],
      "data": {
        "email": "lisa@example.com",
        "name": "Lisa Chen",
        "phone": "+15552223333",
        "company": "Bright Ideas Co"
      }
    }
  ],
  "unmapped_columns": [],
  "warnings": []
}

​
Create Bulk Submissions

Create submissions for all valid rows in the CSV. For files with 100 or fewer rows, submissions are created synchronously. For larger files, processing runs in the background. 
curl -X POST "https://spitshake.io/api/templates/{template_id}/bulk/create" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -F "csv=@/path/to/submitters.csv" \
  -F "send_emails=true" \
  -F "message=Please review and sign the attached document at your earliest convenience."

{
  "status": "completed",
  "batch_id": "batch_a1b2c3d4e5f6",
  "total_rows": 5,
  "created": 5,
  "skipped": 0,
  "failed": 0,
  "submissions": [
    {
      "id": 1001,
      "slug": "aB3cD4eF",
      "status": "sent",
      "submitter_email": "jane@example.com",
      "submitter_name": "Jane Doe",
      "signing_url": "https://spitshake.io/s/aB3cD4eF",
      "created_at": "2026-04-08T15:00:00Z"
    },
    {
      "id": 1002,
      "slug": "gH5iJ6kL",
      "status": "sent",
      "submitter_email": "bob@example.com",
      "submitter_name": "Bob Smith",
      "signing_url": "https://spitshake.io/s/gH5iJ6kL",
      "created_at": "2026-04-08T15:00:01Z"
    },
    {
      "id": 1003,
      "slug": "mN7oP8qR",
      "status": "sent",
      "submitter_email": "maria@example.com",
      "submitter_name": "Maria Garcia",
      "signing_url": "https://spitshake.io/s/mN7oP8qR",
      "created_at": "2026-04-08T15:00:02Z"
    },
    {
      "id": 1004,
      "slug": "sT9uV0wX",
      "status": "sent",
      "submitter_email": "david@example.com",
      "submitter_name": "David Park",
      "signing_url": "https://spitshake.io/s/sT9uV0wX",
      "created_at": "2026-04-08T15:00:03Z"
    },
    {
      "id": 1005,
      "slug": "yZ1aB2cD",
      "status": "sent",
      "submitter_email": "lisa@example.com",
      "submitter_name": "Lisa Chen",
      "signing_url": "https://spitshake.io/s/yZ1aB2cD",
      "created_at": "2026-04-08T15:00:04Z"
    }
  ],
  "created_at": "2026-04-08T15:00:00Z",
  "completed_at": "2026-04-08T15:00:05Z"
}

​
Check Batch Status

Poll the status of a background bulk import job. 
curl -X GET "https://spitshake.io/api/templates/{template_id}/bulk/status/{batch_id}" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

{
  "status": "processing",
  "batch_id": "batch_x9y8z7w6v5u4",
  "total_rows": 350,
  "created": 142,
  "skipped": 3,
  "failed": 0,
  "progress_percent": 41,
  "created_at": "2026-04-08T15:00:00Z",
  "completed_at": null
}

​
Export Submissions as CSV

Download all submissions for a template as a CSV file, useful for reconciliation after a bulk import. 
curl -X GET "https://spitshake.io/api/templates/{template_id}/bulk/export" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -o submissions_export.csv

submission_id,slug,status,email,name,phone,company,sent_at,completed_at,signing_url
1001,aB3cD4eF,completed,jane@example.com,Jane Doe,+15551234567,Acme Corp,2026-04-08T15:00:00Z,2026-04-08T16:30:00Z,https://spitshake.io/s/aB3cD4eF
1002,gH5iJ6kL,sent,bob@example.com,Bob Smith,+15559876543,Widget Inc,2026-04-08T15:00:01Z,,https://spitshake.io/s/gH5iJ6kL
1003,mN7oP8qR,opened,maria@example.com,Maria Garcia,+15555551234,TechStart LLC,2026-04-08T15:00:02Z,,https://spitshake.io/s/mN7oP8qR
1004,sT9uV0wX,sent,david@example.com,David Park,+15558887777,Global Solutions,2026-04-08T15:00:03Z,,https://spitshake.io/s/sT9uV0wX
1005,yZ1aB2cD,completed,lisa@example.com,Lisa Chen,+15552223333,Bright Ideas Co,2026-04-08T15:00:04Z,2026-04-08T17:15:00Z,https://spitshake.io/s/yZ1aB2cD

​
Limits and Performance

MetricValue
Maximum CSV file size10 MB
Maximum rows per import5,000
Synchronous processing threshold100 rows
Background processing rate~100 submissions per minute
Email send rateThrottled to avoid spam filters
For imports larger than 5,000 rows, split your CSV into multiple files and run separate bulk imports. Each batch is assigned a unique batch_id for independent tracking.