AI Document Analysis

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

{
  "configured": false,
  "project_id": null
}

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"

curl -X POST "https://spitshake.io/api/templates/{template_id}/ai/analyze?type=extract_fields" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

{
  "rotations": [
    { "page": 0, "angle": 0 },
    { "page": 1, "angle": 0 },
    { "page": 2, "angle": 90 }
  ]
}

{
  "fields": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Full Name",
      "type": "text",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "areas": [
        {
          "page": 0,
          "x": 0.12,
          "y": 0.34,
          "w": 0.20,
          "h": 0.04,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    },
    {
      "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Signature",
      "type": "signature",
      "submitter_uuid": "s1a2b3c4-d5e6-7890-abcd-111111111111",
      "required": true,
      "readonly": false,
      "preferences": {},
      "areas": [
        {
          "page": 1,
          "x": 0.10,
          "y": 0.82,
          "w": 0.25,
          "h": 0.08,
          "attachment_uuid": "doc-uuid-1111-2222-3333-444444444444"
        }
      ]
    }
  ]
}

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

Action	Description
`add_field`	Creates a new field at the specified position
`update_field`	Modifies properties of an existing field by `field_uuid`
`delete_field`	Removes a field by `field_uuid`
`move_field`	Repositions 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"
  }'

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_image": "iVBORw0KGgoAAAANSUhEUgAAA..."
  }'

{
  "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):

Type	Default Width	Default Height	Description
`signature`	25%	8%	Full signature capture pad
`initials`	10%	5%	Compact initials box
`text`	20%	4%	Single-line text input
`date`	20%	4%	Date picker field
`checkbox`	4%	4%	Boolean toggle checkbox
`number`	20%	4%	Numeric-only input
`phone`	20%	4%	Phone number with formatting
`image`	20%	4%	Image upload area

Error Handling

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

{
  "error": "AI analysis is not configured. Please set the GEMINI_API_KEY environment variable. Visit Settings > Integrations > AI Analysis for setup instructions."
}

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

AI Document Analysis

Overview

Detection Pipeline v2

What’s new in responses

Check AI Configuration Status

Analyze Document

Smart Create

Smart Setup

Chat

Available Chat Actions

Key Assignment

Detectable Field Types

Error Handling

​Overview

​Detection Pipeline v2

​What’s new in responses

​Check AI Configuration Status

​Analyze Document

​Smart Create

​Smart Setup

​Chat

​Available Chat Actions

​Key Assignment

​Detectable Field Types

​Error Handling

Overview

Detection Pipeline v2

What’s new in responses

Check AI Configuration Status

Analyze Document

Smart Create

Smart Setup

Chat

Available Chat Actions

Key Assignment

Detectable Field Types

Error Handling