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

SMS verification adds an extra layer of identity assurance by requiring signers to confirm their phone number via a one-time password (OTP) before completing a submission. Codes expire after 5 minutes and are tied to a specific submission.

​
Step 1: Configure SMS Provider

Set up your Twilio credentials. This only needs to be done once per account. 
curl -X POST "https://spitshake.io/api/verify/update_config" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sms_provider": "twilio",
    "twilio_account_sid": "ACe1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6",
    "twilio_auth_token": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "twilio_phone_number": "+15559876543"
  }'

{
  "success": true,
  "message": "SMS verification configuration saved successfully",
  "provider": "twilio"
}

​
Step 2: Check Configuration

Verify that SMS verification is properly configured before initiating a flow. 
curl -X GET "https://spitshake.io/api/verify/config" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

{
  "configured": true,
  "provider": "twilio"
}

​
Step 3: Send OTP

Send a 6-digit verification code to the signer’s phone number. The code is valid for 300 seconds (5 minutes). 
curl -X POST "https://spitshake.io/api/verify/{submission_id}/send_otp" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567"
  }'

{
  "success": true,
  "message": "Verification code sent",
  "expires_in": 300
}

​
Step 4: Verify OTP

Submit the 6-digit code the signer received. On success, the verification result is stored in the submitter’s values. 
curl -X POST "https://spitshake.io/api/verify/{submission_id}/verify_otp" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567",
    "code": "123456",
    "field_uuid": "f1a2b3c4-d5e6-7890-abcd-000000000001"
  }'

{
  "success": true,
  "verified": true
}

​
Stored Verification Data

After successful verification, the following object is saved to the submitter’s values hash under the corresponding field UUID: 
{
  "phone": "+15551234567",
  "verified_at": "2026-04-09T14:30:00Z",
  "method": "sms_otp"
}
This data is included in the submission response and audit trail, providing a permanent record that the signer verified their phone number.

​
Step 5: Check Verification Status

Poll the current status of a pending verification. Useful for showing countdown timers in the signing UI. 
curl -X GET "https://spitshake.io/api/verify/{submission_id}/status?phone=%2B15551234567" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

{
  "pending": true,
  "expires_in": 245
}

​
Complete Flow Diagram

┌──────────────────┐
│  Signer reaches  │
│  phone field     │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐      ┌──────────────────┐
│  POST send_otp   │─────▶│  Twilio delivers │
│  phone: +1...    │      │  6-digit SMS     │
└────────┬─────────┘      └──────────────────┘
         │
         ▼
┌──────────────────┐
│  Signer enters   │
│  code in UI      │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐      ┌──────────────────┐
│  POST verify_otp │─────▶│  Result stored   │
│  code: 123456    │      │  in submitter    │
└────────┬─────────┘      │  values          │
         │                └──────────────────┘
         ▼
┌──────────────────┐
│  Signing flow    │
│  continues       │
└──────────────────┘

​
Phone Number Format

All phone numbers must use E.164 format:
FormatValid
+15551234567Yes
+442071234567Yes
+61412345678Yes
555-123-4567No
(555) 123-4567No
5551234567No