Bulk Import

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": []
}

{
  "valid": false,
  "total_rows": 3,
  "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": false,
      "errors": ["Missing required field: email"],
      "data": {
        "email": "",
        "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"
      }
    }
  ],
  "unmapped_columns": [],
  "warnings": ["1 row has validation errors and will be skipped during import."]
}

{
  "error": "Unable to parse CSV file. Please ensure the file uses comma delimiters and includes a header row."
}

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"
}

{
  "status": "processing",
  "batch_id": "batch_x9y8z7w6v5u4",
  "total_rows": 350,
  "created": 0,
  "skipped": 0,
  "failed": 0,
  "submissions": [],
  "created_at": "2026-04-08T15:00:00Z",
  "completed_at": null
}

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
}

{
  "status": "completed",
  "batch_id": "batch_x9y8z7w6v5u4",
  "total_rows": 350,
  "created": 345,
  "skipped": 3,
  "failed": 2,
  "progress_percent": 100,
  "created_at": "2026-04-08T15:00:00Z",
  "completed_at": "2026-04-08T15:03:45Z"
}

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

Metric	Value
Maximum CSV file size	10 MB
Maximum rows per import	5,000
Synchronous processing threshold	100 rows
Background processing rate	~100 submissions per minute
Email send rate	Throttled 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.

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": []
}

{
  "valid": false,
  "total_rows": 3,
  "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": false,
      "errors": ["Missing required field: email"],
      "data": {
        "email": "",
        "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"
      }
    }
  ],
  "unmapped_columns": [],
  "warnings": ["1 row has validation errors and will be skipped during import."]
}

{
  "error": "Unable to parse CSV file. Please ensure the file uses comma delimiters and includes a header row."
}

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

Overview

CSV Format

Preview CSV

Create Bulk Submissions

Check Batch Status

Export Submissions as CSV

Limits and Performance

​Overview

​CSV Format

​Preview CSV

​Create Bulk Submissions

​Check Batch Status

​Export Submissions as CSV

​Limits and Performance

Overview

CSV Format

Preview CSV

Create Bulk Submissions

Check Batch Status

Export Submissions as CSV

Limits and Performance