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

DocuTrust integrates with Google Gemini to provide intelligent document analysis. The AI can detect signature fields, extract form data, suggest field placements, and respond to natural-language instructions for template configuration.

Detection Pipeline v2

DocuTrust’s AI field detection runs through a staged pipeline that produces materially more accurate templates than the earlier single-pass approach: stricter field-type discrimination, PDF text-layer position anchoring, canonical key matching for cross-document consistency, per-field confidence scores, and a gated self-review pass on uncertain extractions.
Pipeline v2 rolls out per-account and is backward compatible — existing consumers continue to receive the same response shape, plus a new pipeline metadata block and richer preferences fields per detected field. No action required on your side.

What’s new in responses

Accounts on v2 see these additions on smart_setup and smart_create:
  • pipeline — top-level metadata with version, request_id, latency_ms, anchor_hits, anchor_misses, corrections_applied, critic_ran.
  • preferences.key — canonical snake_case identifier (e.g. full_name, signature, signed_date). Stable across documents with the same semantic field, making downstream field mapping trivial.
  • preferences.confidence — float 0–1 indicating the model’s certainty on both field type AND placement.
  • preferences.anchor_text — verbatim label text from the PDF (e.g. "Printed Name:").
  • preferences.anchor_method — one of snapped_to_blank, snapped_to_label, llm_only, no_text_layer — describes how the field’s position was determined.
See the AI Field Detection Pipeline guide for the full pipeline architecture, confidence score interpretation, and tips for working with the new response shape.

Check AI Configuration Status

Verify that the AI backend is properly configured before making analysis requests.
curl -X GET "https://spitshake.io/api/templates/{template_id}/ai/status" \
  -H "X-Auth-Token: YOUR_API_TOKEN"
{
  "configured": true,
  "project_id": "configured"
}

Analyze Document

Run a targeted analysis pass on a template’s uploaded document. Use type=detect_rotations to identify page orientations, or type=extract_fields to detect fillable areas.
curl -X POST "https://spitshake.io/api/templates/{template_id}/ai/analyze?type=detect_rotations" \
  -H "X-Auth-Token: YOUR_API_TOKEN"
{
  "rotations": [
    { "page": 0, "angle": 0 },
    { "page": 1, "angle": 0 },
    { "page": 2, "angle": 90 }
  ]
}

Smart Create

Automatically generate a complete set of fields for a template in a single call. The AI scans the document and returns every detected field with position data.
curl -X POST "https://spitshake.io/api/templates/{template_id}/ai/smart_create" \
  -H "X-Auth-Token: YOUR_API_TOKEN"
{
  "fields": [
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000001",
      "name": "Full Name",
      "type": "text",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "areas": [
        {
          "page": 0,
          "x": 0.08,
          "y": 0.22,
          "w": 0.20,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000002",
      "name": "Email Address",
      "type": "text",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "areas": [
        {
          "page": 0,
          "x": 0.08,
          "y": 0.28,
          "w": 0.20,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000003",
      "name": "Date of Birth",
      "type": "date",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "areas": [
        {
          "page": 0,
          "x": 0.08,
          "y": 0.34,
          "w": 0.20,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000004",
      "name": "Phone Number",
      "type": "phone",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": false,
      "readonly": false,
      "preferences": {},
      "areas": [
        {
          "page": 0,
          "x": 0.08,
          "y": 0.40,
          "w": 0.20,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000005",
      "name": "I Agree to Terms",
      "type": "checkbox",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "areas": [
        {
          "page": 1,
          "x": 0.06,
          "y": 0.72,
          "w": 0.04,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000006",
      "name": "Initials",
      "type": "initials",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "areas": [
        {
          "page": 1,
          "x": 0.70,
          "y": 0.78,
          "w": 0.10,
          "h": 0.05,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000007",
      "name": "Signature",
      "type": "signature",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "areas": [
        {
          "page": 1,
          "x": 0.10,
          "y": 0.85,
          "w": 0.25,
          "h": 0.08,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000008",
      "name": "Date Signed",
      "type": "date",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "areas": [
        {
          "page": 1,
          "x": 0.55,
          "y": 0.87,
          "w": 0.20,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    }
  ],
  "count": 8
}

Smart Setup

Perform a comprehensive analysis that returns a document summary, per-page breakdown, and a complete field schema with explanations for each detected field.
curl -X POST "https://spitshake.io/api/templates/{template_id}/ai/smart_setup" \
  -H "X-Auth-Token: YOUR_API_TOKEN"
{
  "document_summary": "Two-page employment agreement between an employer and new hire. Contains standard identification fields, compensation terms, and requires signature from both parties.",
  "pages": [
    {
      "page": 0,
      "description": "Employee personal information and employment terms including name, address, start date, and compensation details."
    },
    {
      "page": 1,
      "description": "Agreement acknowledgement section with terms acceptance checkbox, initials, and signature blocks for employee and employer."
    }
  ],
  "fields": [
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000001",
      "name": "Employee Full Name",
      "type": "text",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "reason": "Labeled text input on line 3 reads 'Full Name:' followed by a blank underline.",
      "areas": [
        {
          "page": 0,
          "x": 0.30,
          "y": 0.15,
          "w": 0.20,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000002",
      "name": "Employee Address",
      "type": "text",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "reason": "Labeled text input on line 5 reads 'Address:' followed by a blank underline.",
      "areas": [
        {
          "page": 0,
          "x": 0.30,
          "y": 0.22,
          "w": 0.20,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000003",
      "name": "Start Date",
      "type": "date",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "reason": "Date field labeled 'Start Date:' on page 1 with MM/DD/YYYY format hint.",
      "areas": [
        {
          "page": 0,
          "x": 0.30,
          "y": 0.35,
          "w": 0.20,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000004",
      "name": "Annual Salary",
      "type": "number",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "reason": "Numeric input labeled 'Annual Compensation ($):' on page 1.",
      "areas": [
        {
          "page": 0,
          "x": 0.45,
          "y": 0.48,
          "w": 0.20,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000005",
      "name": "Accept Terms",
      "type": "checkbox",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "reason": "Checkbox adjacent to 'I have read and agree to the terms of employment' on page 2.",
      "areas": [
        {
          "page": 1,
          "x": 0.06,
          "y": 0.60,
          "w": 0.04,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000006",
      "name": "Employee Initials",
      "type": "initials",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "reason": "Small box labeled 'Initials' in the bottom-right of page 2.",
      "areas": [
        {
          "page": 1,
          "x": 0.72,
          "y": 0.70,
          "w": 0.10,
          "h": 0.05,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000007",
      "name": "Employee Signature",
      "type": "signature",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "reason": "Signature line labeled 'Employee Signature' at the bottom of page 2.",
      "areas": [
        {
          "page": 1,
          "x": 0.08,
          "y": 0.85,
          "w": 0.25,
          "h": 0.08,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000008",
      "name": "Date Signed",
      "type": "date",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "reason": "Date field next to signature block labeled 'Date' on page 2.",
      "areas": [
        {
          "page": 1,
          "x": 0.55,
          "y": 0.87,
          "w": 0.20,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000009",
      "name": "Employer Profile Photo",
      "type": "image",
      "submitter_uuid": "s2b3c4d5-e6f7-8901-bcde-222222222222",
      "required": false,
      "readonly": false,
      "preferences": {},
      "reason": "Image placeholder box labeled 'Company Logo / Photo' on page 1 header.",
      "areas": [
        {
          "page": 0,
          "x": 0.80,
          "y": 0.02,
          "w": 0.12,
          "h": 0.08,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    }
  ],
  "field_count": 9
}

Chat

Send natural-language instructions to modify the template schema. The AI interprets your message and returns structured actions to apply.
curl -X POST "https://spitshake.io/api/templates/{template_id}/ai/chat" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Add a phone number field below the email field on page 1 and make the signature field larger"
      }
    ]
  }'
{
  "reply": "I have added a phone number field below the email on page 1 and increased the signature field size to 30x10.",
  "function_calls": [
    {
      "action": "add_field",
      "field": {
        "uuid": "c3d4e5f6-a7b8-9012-cdef-333333333333",
        "name": "Phone Number",
        "type": "phone",
        "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
        "required": false,
        "readonly": false,
        "preferences": {},
        "areas": [
          {
            "page": 0,
            "x": 0.08,
            "y": 0.34,
            "w": 0.20,
            "h": 0.04,
            "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
          }
        ]
      }
    },
    {
      "action": "update_field",
      "field_uuid": "f1a2b3c4-d5e6-7890-abcd-000000000007",
      "changes": {
        "areas": [
          {
            "page": 1,
            "x": 0.08,
            "y": 0.83,
            "w": 0.30,
            "h": 0.10,
            "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
          }
        ]
      }
    }
  ],
  "new_schema": [
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000001",
      "name": "Full Name",
      "type": "text",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "areas": [
        {
          "page": 0,
          "x": 0.08,
          "y": 0.22,
          "w": 0.20,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000002",
      "name": "Email Address",
      "type": "text",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "areas": [
        {
          "page": 0,
          "x": 0.08,
          "y": 0.28,
          "w": 0.20,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "c3d4e5f6-a7b8-9012-cdef-333333333333",
      "name": "Phone Number",
      "type": "phone",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": false,
      "readonly": false,
      "preferences": {},
      "areas": [
        {
          "page": 0,
          "x": 0.08,
          "y": 0.34,
          "w": 0.20,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-000000000007",
      "name": "Signature",
      "type": "signature",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "areas": [
        {
          "page": 1,
          "x": 0.08,
          "y": 0.83,
          "w": 0.30,
          "h": 0.10,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    }
  ]
}

Available Chat Actions

ActionDescription
add_fieldCreates a new field at the specified position
update_fieldModifies properties of an existing field by field_uuid
delete_fieldRemoves a field by field_uuid
move_fieldRepositions a field to new coordinates

Key Assignment

Assign external reference keys to fields using either plain text or a base64-encoded image of a key mapping document.
curl -X POST "https://spitshake.io/api/templates/{template_id}/ai/assign_keys" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "keys_text": "Full Name = applicant_name\nEmail Address = applicant_email\nSignature = applicant_sig\nDate Signed = sign_date"
  }'
{
  "assignments": [
    {
      "field_uuid": "f1a2b3c4-d5e6-7890-abcd-000000000001",
      "field_name": "Full Name",
      "key": "applicant_name"
    },
    {
      "field_uuid": "f1a2b3c4-d5e6-7890-abcd-000000000002",
      "field_name": "Email Address",
      "key": "applicant_email"
    },
    {
      "field_uuid": "f1a2b3c4-d5e6-7890-abcd-000000000007",
      "field_name": "Signature",
      "key": "applicant_sig"
    },
    {
      "field_uuid": "f1a2b3c4-d5e6-7890-abcd-000000000008",
      "field_name": "Date Signed",
      "key": "sign_date"
    }
  ]
}

Detectable Field Types

The AI recognizes and creates the following field types, each with a default size (expressed as percentage of page dimensions):
TypeDefault WidthDefault HeightDescription
signature25%8%Full signature capture pad
initials10%5%Compact initials box
text20%4%Single-line text input
date20%4%Date picker field
checkbox4%4%Boolean toggle checkbox
number20%4%Numeric-only input
phone20%4%Phone number with formatting
image20%4%Image upload area

Error Handling

{
  "error": "AI service temporarily unavailable. The Gemini API returned an error. Please try again in a few moments."
}