Quickstart

This guide walks you through the complete signing flow: uploading a PDF, sending it for signature, and downloading the completed document. By the end, you will have a working integration you can build on.

Prerequisites

A SpitShake account (sign up free)
A PDF document to send for signing
An API token (generated in the next step)

Step 1: Get your API token

Navigate to Settings > API in your SpitShake dashboard and click Create Token. Give it a descriptive name (e.g., “Quickstart”) and select the scopes you need. For this tutorial, enable templates:write and submissions:write. Copy the token — you will not be able to see it again.

export SPITSHAKE_TOKEN="your-api-token-here"
export SPITSHAKE_URL="https://spitshake.io"

Keep your API token secret. Do not commit it to version control or expose it in client-side code.

Step 2: Create a template from PDF

Upload a PDF and SpitShake will create a template with a default submitter role. You can optionally specify fields, but for this quickstart we will keep it simple and let the signer fill in all fields manually.

curl -X POST "$SPITSHAKE_URL/api/templates/pdf" \
  -H "X-Auth-Token: $SPITSHAKE_TOKEN" \
  -F "files[]=@/path/to/contract.pdf" \
  -F "name=Quickstart Contract"

const fs = require("fs");

const form = new FormData();
form.append("files[]", new Blob([fs.readFileSync("./contract.pdf")]), "contract.pdf");
form.append("name", "Quickstart Contract");

const response = await fetch(`${process.env.SPITSHAKE_URL}/api/templates/pdf`, {
  method: "POST",
  headers: { "X-Auth-Token": process.env.SPITSHAKE_TOKEN },
  body: form,
});

const template = await response.json();
console.log("Template ID:", template.id);

import requests
import os

url = f"{os.environ['SPITSHAKE_URL']}/api/templates/pdf"
headers = {"X-Auth-Token": os.environ["SPITSHAKE_TOKEN"]}

with open("contract.pdf", "rb") as f:
    files = {"files[]": ("contract.pdf", f, "application/pdf")}
    data = {"name": "Quickstart Contract"}
    response = requests.post(url, headers=headers, files=files, data=data)

template = response.json()
print("Template ID:", template["id"])

Response:

{
  "id": "tpl_7VQhP2tM9xA1kR8bN",
  "name": "Quickstart Contract",
  "slug": "qk7x9m2p",
  "external_id": null,
  "folder_name": "Default",
  "source": "api",
  "shared": false,
  "field_count": 0,
  "submitter_count": 1,
  "schema": [],
  "submitters": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "First Party"
    }
  ],
  "thumbnail_url": null,
  "created_at": "2026-04-08T10:30:00.000Z",
  "updated_at": "2026-04-08T10:30:00.000Z"
}

Save the id from the response. You will use it in the next step to create a submission.

Step 3: Create a submission

Now send the template for signing. Provide the submitter’s email and name, mapped to the submitter role from the template.

curl -X POST "$SPITSHAKE_URL/api/submissions" \
  -H "X-Auth-Token: $SPITSHAKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tpl_7VQhP2tM9xA1kR8bN",
    "send_email": true,
    "submitters": [
      {
        "role": "First Party",
        "email": "jane@example.com",
        "name": "Jane Smith"
      }
    ]
  }'

const response = await fetch(`${process.env.SPITSHAKE_URL}/api/submissions`, {
  method: "POST",
  headers: {
    "X-Auth-Token": process.env.SPITSHAKE_TOKEN,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    template_id: "tpl_7VQhP2tM9xA1kR8bN",
    send_email: true,
    submitters: [
      {
        role: "First Party",
        email: "jane@example.com",
        name: "Jane Smith",
      },
    ],
  }),
});

const submission = await response.json();
console.log("Submission ID:", submission.id);
console.log("Signing URL:", `${process.env.SPITSHAKE_URL}/s/${submission.submitters[0].slug}`);

import requests
import os
import json

url = f"{os.environ['SPITSHAKE_URL']}/api/submissions"
headers = {
    "X-Auth-Token": os.environ["SPITSHAKE_TOKEN"],
    "Content-Type": "application/json",
}
payload = {
    "template_id": "tpl_7VQhP2tM9xA1kR8bN",
    "send_email": True,
    "submitters": [
        {
            "role": "First Party",
            "email": "jane@example.com",
            "name": "Jane Smith",
        }
    ],
}

response = requests.post(url, headers=headers, json=payload)
submission = response.json()
print("Submission ID:", submission["id"])
print("Signing URL:", f"{os.environ['SPITSHAKE_URL']}/s/{submission['submitters'][0]['slug']}")

Response:

{
  "id": 187,
  "slug": "n3k8p1w5",
  "source": "api",
  "status": "pending",
  "template_id": "tpl_7VQhP2tM9xA1kR8bN",
  "submitter_count": 1,
  "created_at": "2026-04-08T10:31:00.000Z",
  "updated_at": "2026-04-08T10:31:00.000Z",
  "completed_at": null,
  "expire_at": null,
  "archived_at": null,
  "submitters": [
    {
      "id": 301,
      "uuid": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
      "slug": "r7t2q9v4",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "First Party",
      "status": "sent",
      "phone": null,
      "external_id": null,
      "metadata": {},
      "opened_at": null,
      "sent_at": "2026-04-08T10:31:01.000Z",
      "completed_at": null,
      "declined_at": null
    }
  ]
}

Jane will receive an email with a link to sign the document. You can also construct the signing URL directly: https://spitshake.io/s/r7t2q9v4.

Step 4: Check submission status

Poll the submission to see when it has been completed, or set up webhooks for real-time notifications.

curl "$SPITSHAKE_URL/api/submissions/187" \
  -H "X-Auth-Token: $SPITSHAKE_TOKEN"

const response = await fetch(`${process.env.SPITSHAKE_URL}/api/submissions/187`, {
  headers: { "X-Auth-Token": process.env.SPITSHAKE_TOKEN },
});

const submission = await response.json();
console.log("Status:", submission.status);

import requests
import os

url = f"{os.environ['SPITSHAKE_URL']}/api/submissions/187"
headers = {"X-Auth-Token": os.environ["SPITSHAKE_TOKEN"]}

response = requests.get(url, headers=headers)
submission = response.json()
print("Status:", submission["status"])

Response when completed:

{
  "id": 187,
  "slug": "n3k8p1w5",
  "source": "api",
  "status": "completed",
  "template_id": "tpl_7VQhP2tM9xA1kR8bN",
  "submitter_count": 1,
  "created_at": "2026-04-08T10:31:00.000Z",
  "updated_at": "2026-04-08T11:15:00.000Z",
  "completed_at": "2026-04-08T11:15:00.000Z",
  "expire_at": null,
  "archived_at": null,
  "submitters": [
    {
      "id": 301,
      "uuid": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
      "slug": "r7t2q9v4",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "First Party",
      "status": "completed",
      "phone": null,
      "external_id": null,
      "metadata": {},
      "opened_at": "2026-04-08T11:10:00.000Z",
      "sent_at": "2026-04-08T10:31:01.000Z",
      "completed_at": "2026-04-08T11:15:00.000Z",
      "declined_at": null
    }
  ]
}

Instead of polling, use webhooks to receive a submission.completed event in real time.

Step 5: Download the signed document

Once the submission status is completed, download the final signed PDF with all fields filled and signatures applied.

curl -O -J "$SPITSHAKE_URL/api/submissions/187/documents/download" \
  -H "X-Auth-Token: $SPITSHAKE_TOKEN"

const response = await fetch(
  `${process.env.SPITSHAKE_URL}/api/submissions/187/documents/download`,
  { headers: { "X-Auth-Token": process.env.SPITSHAKE_TOKEN } }
);

const buffer = await response.arrayBuffer();
const fs = require("fs");
fs.writeFileSync("signed-contract.pdf", Buffer.from(buffer));
console.log("Downloaded signed-contract.pdf");

import requests
import os

url = f"{os.environ['SPITSHAKE_URL']}/api/submissions/187/documents/download"
headers = {"X-Auth-Token": os.environ["SPITSHAKE_TOKEN"]}

response = requests.get(url, headers=headers)
with open("signed-contract.pdf", "wb") as f:
    f.write(response.content)
print("Downloaded signed-contract.pdf")

The response is a binary PDF file with Content-Disposition: attachment headers.

What’s next?

You have successfully sent a document for signing and downloaded the completed result. Here are some next steps to explore:

Templates

Define field schemas, submitter roles, and create templates from DOCX or HTML.

Submissions

Pre-fill fields, use quick sign modes, create drafts, and bulk-send documents.

Submitters

Track individual signer status, resend invitations, and map external IDs.

Webhooks

Get real-time notifications instead of polling for submission status changes.

Embedding

Embed the signing experience directly in your application.

Authentication

Learn about API token scopes, JWT tokens, and security best practices.

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

Prerequisites

Step 1: Get your API token

Step 2: Create a template from PDF

Step 3: Create a submission

Step 4: Check submission status

Step 5: Download the signed document

What’s next?

Templates

Submissions

Submitters

Webhooks

Embedding

Authentication

​Prerequisites

​Step 1: Get your API token

​Step 2: Create a template from PDF

​Step 3: Create a submission

​Step 4: Check submission status

​Step 5: Download the signed document

​What’s next?

Templates

Submissions

Submitters

Webhooks

Embedding

Authentication

Prerequisites

Step 1: Get your API token

Step 2: Create a template from PDF

Step 3: Create a submission

Step 4: Check submission status

Step 5: Download the signed document

What’s next?