> ## 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.
# AI Document Analysis
> Leverage Google Gemini to automatically detect fields, extract data, and interactively configure templates via chat.
## 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](/guides/ai-field-detection-pipeline) 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.
```bash cURL theme={null}
curl -X GET "https://spitshake.io/api/templates/{template_id}/ai/status" \
-H "X-Auth-Token: YOUR_API_TOKEN"
```
```json 200 OK theme={null}
{
"configured": true,
"project_id": "configured"
}
```
```json 200 Not Configured theme={null}
{
"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.
```bash Detect Rotations theme={null}
curl -X POST "https://spitshake.io/api/templates/{template_id}/ai/analyze?type=detect_rotations" \
-H "X-Auth-Token: YOUR_API_TOKEN"
```
```bash Extract Fields theme={null}
curl -X POST "https://spitshake.io/api/templates/{template_id}/ai/analyze?type=extract_fields" \
-H "X-Auth-Token: YOUR_API_TOKEN"
```
```json 200 — detect_rotations theme={null}
{
"rotations": [
{ "page": 0, "angle": 0 },
{ "page": 1, "angle": 0 },
{ "page": 2, "angle": 90 }
]
}
```
```json 200 — extract_fields theme={null}
{
"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.
```bash cURL theme={null}
curl -X POST "https://spitshake.io/api/templates/{template_id}/ai/smart_create" \
-H "X-Auth-Token: YOUR_API_TOKEN"
```
```json 200 OK theme={null}
{
"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.
```bash cURL theme={null}
curl -X POST "https://spitshake.io/api/templates/{template_id}/ai/smart_setup" \
-H "X-Auth-Token: YOUR_API_TOKEN"
```
```json 200 OK theme={null}
{
"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.
```bash cURL theme={null}
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"
}
]
}'
```
```json 200 OK theme={null}
{
"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.
```bash Text Keys theme={null}
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"
}'
```
```bash Image Keys theme={null}
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..."
}'
```
```json 200 OK theme={null}
{
"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
```json 503 — AI API Error theme={null}
{
"error": "AI service temporarily unavailable. The Gemini API returned an error. Please try again in a few moments."
}
```
```json 422 — Configuration Error theme={null}
{
"error": "AI analysis is not configured. Please set the GEMINI_API_KEY environment variable. Visit Settings > Integrations > AI Analysis for setup instructions."
}
```