DeepRead Form Fill — AI-Powered PDF Form Filling API

Upload any PDF form + your data as JSON. AI detects fields, maps your data, fills the form, quality-checks the result, and returns a completed PDF you can download.

Works with any PDF — scanned paper forms, government PDFs, custom templates. No AcroForm fields required.

What This Skill Does

You provide:

1. A blank PDF form (upload)
2. Your data as JSON (e.g. {"full_name": "Jane Doe", "dob": "1990-03-15"})

DeepRead returns:

• A filled PDF with your data placed in the correct fields
• A quality report showing what was filled, what was verified, and what needs human review

No field mapping, no coordinates, no configuration. The AI figures out where everything goes.

Setup

Get Your API Key

# Sign up (free — 2,000 pages/month, no credit card)
# https://www.deepread.tech/dashboard/?utm_source=clawdhub

Save your API key:

export DEEPREAD_API_KEY="sk_live_your_key_here"

Quick Start

Fill a Form (3 lines)

# 1. Submit form + data
curl -X POST https://api.deepread.tech/v1/form-fill \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@application.pdf" \
  -F 'form_fields={"full_name": "Jane Doe", "date_of_birth": "03/15/1990", "address": "123 Main St, Portland OR 97201"}'

# Response (immediate):
# {"id": "<job_id>", "status": "queued"}

# 2. Poll for result (use the id from step 1)
curl https://api.deepread.tech/v1/form-fill/<job_id> \
  -H "X-API-Key: $DEEPREAD_API_KEY"

# 3. Download the filled PDF from filled_form_url in the response

API Reference

POST /v1/form-fill — Submit a Form for Filling

Authentication: X-API-Key header (required)

Content-Type: multipart/form-data

Parameters:

Example:

curl -X POST https://api.deepread.tech/v1/form-fill \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@tax_form.pdf" \
  -F 'form_fields={
    "taxpayer_name": "Jane Doe",
    "ssn": "123-45-6789",
    "filing_status": "Single",
    "total_income": "85000",
    "tax_year": "2025"
  }' \
  -F "webhook_url=https://your-app.com/webhooks/form-fill"

Response (immediate):

{
  "id": "<job_id>",
  "status": "queued"
}

Processing is asynchronous — poll the GET endpoint or use a webhook.

GET /v1/form-fill/{job_id} — Get Job Status & Results

Authentication: X-API-Key header (required)

Rate limit: 20 requests per 60 seconds

curl https://api.deepread.tech/v1/form-fill/<job_id> \
  -H "X-API-Key: $DEEPREAD_API_KEY"

Response when completed:

{
  "id": "<job_id>",
  "status": "completed",
  "file_name": "tax_form.pdf",
  "created_at": "2025-06-15T10:00:00Z",
  "completed_at": "2025-06-15T10:00:18Z",
  "filled_form_url": "https://storage.deepread.tech/form_fill/.../filled.pdf",
  "fields_detected": 25,
  "fields_filled": 23,
  "fields_verified": 21,
  "fields_hil_flagged": 2,
  "duration_seconds": 18.3,
  "report": {
    "summary": {
      "fields_detected": 25,
      "fields_filled": 23,
      "fields_verified": 21,
      "fields_hil_flagged": 2,
      "mappings_created": 23,
      "unmapped_keys": 0,
      "adjustments_made": 3
    },
    "fields": [
      {
        "field_index": 0,
        "label": "Taxpayer Name",
        "field_type": "text",
        "page": 1,
        "value": "Jane Doe",
        "hil_flag": false,
        "verified": true
      },
      {
        "field_index": 8,
        "label": "Total Income",
        "field_type": "text",
        "page": 2,
        "value": "85000",
        "hil_flag": true,
        "verified": false,
        "reason": "Text overlaps adjacent field"
      }
    ],
    "mappings": [
      {
        "user_key": "taxpayer_name",
        "field_index": 0,
        "value_to_fill": "Jane Doe",
        "confidence": 0.95
      }
    ],
    "unmapped_user_keys": [],
    "adjustments_made": ["Field 8: reduced font size from 12pt to 8pt"],
    "qa_feedback": ["Total Income: text overlaps adjacent field"],
    "errors": []
  },
  "errors": null,
  "error_message": null
}

Status values:

Poll every 5-10 seconds until status is completed or failed.

Webhook Notification (Optional)

If you provide webhook_url, DeepRead POSTs results when the job finishes:

Completed:

{
  "job_id": "<job_id>",
  "status": "completed",
  "created_at": "<ISO 8601 timestamp>",
  "completed_at": "<ISO 8601 timestamp>",
  "result": {
    "filled_form_url": "<signed URL to download filled PDF>",
    "fields_detected": 25,
    "fields_filled": 23,
    "fields_verified": 21,
    "fields_hil_flagged": 2,
    "report": { ... }
  }
}

Failed:

{
  "job_id": "<job_id>",
  "status": "failed",
  "created_at": "<ISO 8601 timestamp>",
  "completed_at": "<ISO 8601 timestamp>",
  "error": "Form fill timed out after 600s",
  "errors": ["Form fill timed out after 600s"]
}

How It Works (Under the Hood)

Upload PDF + JSON data
       │
       ▼
┌──────────────────────┐
│ 1. DETECT FIELDS     │  Vision AI scans every page, finds all fillable areas
│    (visual, not PDF   │  Returns: label, type, page, bounding box coordinates
│     form fields)      │
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│ 2. MAP DATA          │  AI semantically matches your JSON keys → form fields
│    "full_name" →     │  Transforms values: splits names, formats dates,
│    "Full Name" field  │  converts checkboxes, adds currency symbols
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│ 3. FILL FORM         │  Places text at visual coordinates on the PDF
│    coordinate-based   │  Handles: text, checkboxes, dropdowns
│    insertion          │
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│ 4. QA CHECK          │  Vision AI re-reads the filled form to verify:
│    visual verify      │  - Text is readable, not cut off
│                       │  - Positioned correctly, no overlaps
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│ 5. REPAIR (if needed)│  Auto-fixes: shrink font, adjust position, remap
│    per-field fixes    │  If repair fails → flag for human review (hil_flag)
└──────────┬───────────┘
           ▼
      Filled PDF + Report

Key insight: This is visual coordinate-based filling, not AcroForm-based. It works on any PDF — scanned paper forms, government PDFs with no editable fields, custom templates.

Usage Examples

Loan Application

curl -X POST https://api.deepread.tech/v1/form-fill \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@loan_application.pdf" \
  -F 'form_fields={
    "applicant_name": "Jane Doe",
    "date_of_birth": "03/15/1990",
    "ssn": "123-45-6789",
    "employer": "Acme Corp",
    "annual_income": "95000",
    "loan_amount": "350000",
    "property_address": "456 Oak Ave, Portland OR 97201",
    "loan_type": "30-Year Fixed"
  }'

Insurance Claim

curl -X POST https://api.deepread.tech/v1/form-fill \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@claim_form.pdf" \
  -F 'form_fields={
    "policy_number": "INS-2025-78901",
    "insured_name": "Jane Doe",
    "date_of_loss": "06/01/2025",
    "description": "Water damage to basement from pipe burst",
    "estimated_damage": "12500",
    "photos_attached": "true"
  }'

Government Form (W-4, I-9, etc.)

curl -X POST https://api.deepread.tech/v1/form-fill \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@w4_form.pdf" \
  -F 'form_fields={
    "first_name": "Jane",
    "last_name": "Doe",
    "ssn": "123-45-6789",
    "address": "123 Main St",
    "city": "Portland",
    "state": "OR",
    "zip": "97201",
    "filing_status": "Single",
    "multiple_jobs": "false"
  }'

Batch Processing (Same Template, Different Data)

import json
import os
import requests
import time

API_KEY = os.environ["DEEPREAD_API_KEY"]
FORM_TEMPLATE = "application.pdf"

applicants = [
    {"full_name": "Jane Doe", "email": "jane@example.com", "dob": "1990-03-15"},
    {"full_name": "John Smith", "email": "john@example.com", "dob": "1985-07-22"},
    {"full_name": "Alice Chen", "email": "alice@example.com", "dob": "1992-11-08"},
]

jobs = []
for i, applicant in enumerate(applicants):
    with open(FORM_TEMPLATE, "rb") as f:
        resp = requests.post(
            "https://api.deepread.tech/v1/form-fill",
            headers={"X-API-Key": API_KEY},
            files={"file": (FORM_TEMPLATE, f, "application/pdf")},
            data={
                "form_fields": json.dumps(applicant),
                "idempotency_key": f"batch-2025-06-{i}",
            },
        )
    job_id = resp.json()["id"]
    jobs.append(job_id)
    print(f"Submitted: {applicant['full_name']} → job {job_id}")

# Poll for results
for job_id in jobs:
    while True:
        result = requests.get(
            f"https://api.deepread.tech/v1/form-fill/{job_id}",
            headers={"X-API-Key": API_KEY},
        ).json()
        if result["status"] in ("completed", "failed"):
            print(f"Job {job_id}: {result['status']}")
            if result["status"] == "completed":
                print(f"  Download: {result['filled_form_url']}")
                print(f"  Fields: {result['fields_filled']}/{result['fields_detected']} filled, "
                      f"{result['fields_hil_flagged']} need review")
            break
        time.sleep(5)

Understanding the Report

fields_detected vs fields_filled vs fields_verified

Typical result: 90-95% of fields verified, 2-5% flagged for review.

HIL Flags (Human-in-the-Loop)

A field gets hil_flag: true when:

• Text overlaps an adjacent field
• Font had to be shrunk significantly
• Value doesn't visually match field expectations
• Repair attempts didn't fully resolve the issue

Each flagged field includes a reason explaining why review is needed.

Unmapped Keys

If your JSON has keys that don't match any form field, they appear in unmapped_user_keys. This means:

• The form doesn't have a matching field
• Or the field label is ambiguous

Idempotency

Prevent duplicate submissions with idempotency_key:

# First request
curl -X POST https://api.deepread.tech/v1/form-fill \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@form.pdf" \
  -F 'form_fields={"name": "Jane"}' \
  -F "idempotency_key=submission-abc-123"
# → {"id": "<job_id>", "status": "queued"}

# Retry (same key) — returns the same job, no duplicate
curl -X POST https://api.deepread.tech/v1/form-fill \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@form.pdf" \
  -F 'form_fields={"name": "Jane"}' \
  -F "idempotency_key=submission-abc-123"
# → {"id": "<same job_id as above>", "status": "queued"}  ← SAME JOB

When to Use This Skill

Use DeepRead Form Fill For:

• Loan/mortgage applications — fill 20+ page forms from CRM data
• Insurance claims — populate claim forms automatically
• Government forms — W-4, I-9, tax forms, permits, benefits applications
• Legal documents — contracts, agreements with field placeholders
• Onboarding packets — new hire paperwork from HR systems
• Batch processing — same template, hundreds of applicants

Don't Use For:

• Creating PDFs from scratch — this fills existing forms, doesn't generate new ones
• Real-time (<1 second) — processing takes 15-30 seconds (async)
• Non-PDF formats — PDF only (DOCX support coming soon)

Rate Limits & Pricing

Free Tier (No Credit Card)

• 2,000 pages/month
• Full feature access

Paid Plans

• PRO: 50,000 pages/month @ $99/mo
• SCALE: Custom volume pricing

Upgrade: https://www.deepread.tech/dashboard/billing?utm_source=clawdhub

Troubleshooting

Error: 400 "Only PDF files are supported"

Upload a .pdf file. Other formats are not yet supported.

Error: 400 "Invalid JSON in form_fields"

Check your JSON syntax. Must be a valid JSON object (not array):

✅ {"name": "Jane Doe", "dob": "1990-03-15"}
❌ ["name", "dob"]
❌ "just a string"

Error: 429 "Monthly page quota exceeded"

Upgrade to PRO or wait until next billing cycle.

Status: "failed" with "Vision model timeout"

The form is very complex or has many pages. Try splitting into smaller sections.

Fields not mapped correctly

Add more descriptive keys in your JSON. The AI uses your key names to match fields:

✅ {"applicant_full_name": "Jane Doe"}  — clear, matches form labels
❌ {"field1": "Jane Doe"}  — ambiguous, hard to map

Some fields flagged for review

This is expected for 2-5% of fields. Check report.fields for the reason on each flagged field.

Endpoints Used

Support

• Dashboard: https://www.deepread.tech/dashboard
• Issues: https://github.com/deepread-tech/deep-read-service/issues
• Email: hello@deepread.tech

BYOK — Bring Your Own Key

Connect your own OpenAI, Google, or OpenRouter API key via the dashboard. All form fill processing routes through YOUR provider account — zero DeepRead LLM costs, page quota skipped entirely.

Set it up: https://www.deepread.tech/dashboard/byok

Related DeepRead Skills

• deepread-ocr — Extract text and structured JSON from documents — clawhub install uday390/deepread-ocr
• deepread-form-fill — Fill any PDF form with AI vision (this skill) — clawhub install uday390/deepread-form-fill
• deepread-pii — Redact 14 types of PII from documents — clawhub install uday390/deepread-pii
• deepread-agent-setup — Authenticate via OAuth device flow — clawhub install uday390/deepread-agent-setup
• deepread-byok — Bring Your Own Key setup — clawhub install uday390/deepread-byok

Get started free: https://www.deepread.tech/dashboard/?utm_source=clawhub