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.

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"
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"
      }
    ]
  }'
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"
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"
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.