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)
- 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
CODEBLOCK0
Save your API key:
CODEBLOCK1
Quick Start
Fill a Form (3 lines)
CODEBLOCK2
API Reference
POST /v1/form-fill — Submit a Form for Filling
Authentication: X-API-Key header (required)
Content-Type: INLINECODE2
Parameters:
| Field | Type | Required | Description |
|---|
| INLINECODE3 | File | Yes | PDF form to fill |
| INLINECODE4 |
JSON string | Yes |
{"field_name": "value"} — your data |
|
webhook_url | String | No | URL to receive results when done |
|
idempotency_key | String | No | Prevent duplicate submissions |
|
url_expires_in | Integer | No | Signed URL expiry in seconds (default: 604800 = 7 days, min: 3600, max: 604800) |
Example:
CODEBLOCK3
Response (immediate):
CODEBLOCK4
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
CODEBLOCK5
Response when completed:
CODEBLOCK6
Status values:
| Status | Meaning |
|---|
| INLINECODE10 | Waiting for processing |
| INLINECODE11 |
AI is filling the form |
|
completed | Done — download from
filled_form_url |
|
failed | Something went wrong — check
error_message |
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:
CODEBLOCK7
Failed:
CODEBLOCK8
How It Works (Under the Hood)
CODEBLOCK9
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
CODEBLOCK10
Insurance Claim
CODEBLOCK11
Government Form (W-4, I-9, etc.)
CODEBLOCK12
Batch Processing (Same Template, Different Data)
CODEBLOCK13
Understanding the Report
fieldsdetected vs fieldsfilled vs fields_verified
| Metric | What it means |
|---|
| INLINECODE19 | Total form fields AI found on the PDF |
| INLINECODE20 |
Fields where your data was placed |
|
fields_verified | Fields that passed visual QA (text readable, positioned correctly) |
|
fields_hil_flagged | Fields needing human review (AI couldn't fully verify) |
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:
CODEBLOCK14
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):
CODEBLOCK15
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:
CODEBLOCK16
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
| Endpoint | Method | Auth | Purpose |
|---|
| INLINECODE30 | POST | API Key | Submit form + data |
| INLINECODE31 |
GET | API Key | Poll for status + results |
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 — INLINECODE32
- deepread-form-fill — Fill any PDF form with AI vision (this skill) — INLINECODE33
- deepread-pii — Redact 14 types of PII from documents — INLINECODE34
- deepread-agent-setup — Authenticate via OAuth device flow — INLINECODE35
- deepread-byok — Bring Your Own Key setup — INLINECODE36
Get started free: https://www.deepread.tech/dashboard/?utm_source=clawhub
DeepRead 表单填写 — 基于AI的PDF表单填写API
上传任意PDF表单 + 您的JSON数据。AI检测字段、映射数据、填写表单、质检结果，并返回可下载的已填写PDF。
适用于任何PDF — 扫描纸质表单、政府PDF、自定义模板。无需AcroForm字段。
此技能的功能
您提供：
- 1. 空白PDF表单（上传）
- JSON格式的数据（例如 {full_name: 张三, dob: 1990-03-15}）
DeepRead返回：
- - 已填写PDF，您的数据被放置在正确字段中
- 质量报告，显示已填写、已验证和需要人工审核的内容
无需字段映射、坐标或配置。 AI自动判断数据应放置的位置。
设置
获取API密钥
bash
注册（免费 — 每月2,000页，无需信用卡）
https://www.deepread.tech/dashboard/?utm_source=clawdhub
保存您的API密钥：
bash
export DEEPREADAPIKEY=skliveyourkeyhere
快速开始
填写表单（3行代码）
bash
1. 提交表单 + 数据
curl -X POST https://api.deepread.tech/v1/form-fill \
-H X-API-Key: $DEEPREAD
APIKEY \
-F file=@application.pdf \
-F form
fields={fullname: 张三, date
ofbirth: 03/15/1990, address: 北京市朝阳区123号}
响应（即时）：
{id: , status: queued}
2. 轮询结果（使用步骤1中的id）
curl https://api.deepread.tech/v1/form-fill/
\
-H X-API-Key: $DEEPREADAPIKEY
3. 从响应中的filledformurl下载已填写的PDF
API参考
POST /v1/form-fill — 提交表单进行填写
认证： X-API-Key 请求头（必需）
Content-Type： multipart/form-data
参数：
| 字段 | 类型 | 必需 | 描述 |
|---|
| file | 文件 | 是 | 要填写的PDF表单 |
| formfields |
JSON字符串 | 是 | {fieldname: value} — 您的数据 |
| webhook_url | 字符串 | 否 | 完成时接收结果的URL |
| idempotency_key | 字符串 | 否 | 防止重复提交 |
| urlexpiresin | 整数 | 否 | 签名URL过期时间（秒，默认：604800 = 7天，最小：3600，最大：604800） |
示例：
bash
curl -X POST https://api.deepread.tech/v1/form-fill \
-H X-API-Key: $DEEPREADAPIKEY \
-F file=@tax_form.pdf \
-F form_fields={
taxpayer_name: 张三,
ssn: 123-45-6789,
filing_status: 单身,
total_income: 85000,
tax_year: 2025
} \
-F webhook_url=https://your-app.com/webhooks/form-fill
响应（即时）：
json
{
id: ,
status: queued
}
处理是异步的 — 轮询GET端点或使用webhook。
GET /v1/form-fill/{job_id} — 获取任务状态和结果
认证： X-API-Key 请求头（必需）
速率限制： 每60秒20次请求
bash
curl https://api.deepread.tech/v1/form-fill/ \
-H X-API-Key: $DEEPREADAPIKEY
完成时的响应：
json
{
id: ,
status: completed,
filename: taxform.pdf,
created_at: 2025-06-15T10:00:00Z,
completed_at: 2025-06-15T10:00:18Z,
filledformurl: https://storage.deepread.tech/form_fill/.../filled.pdf,
fields_detected: 25,
fields_filled: 23,
fields_verified: 21,
fieldshilflagged: 2,
duration_seconds: 18.3,
report: {
summary: {
fields_detected: 25,
fields_filled: 23,
fields_verified: 21,
fieldshilflagged: 2,
mappings_created: 23,
unmapped_keys: 0,
adjustments_made: 3
},
fields: [
{
field_index: 0,
label: 纳税人姓名,
field_type: text,
page: 1,
value: 张三,
hil_flag: false,
verified: true
},
{
field_index: 8,
label: 总收入,
field_type: text,
page: 2,
value: 85000,
hil_flag: true,
verified: false,
reason: 文本与相邻字段重叠
}
],
mappings: [
{
userkey: taxpayername,
field_index: 0,
valuetofill: 张三,
confidence: 0.95
}
],
unmappeduserkeys: [],
adjustments_made: [字段8：字号从12pt减小到8pt],
qa_feedback: [总收入：文本与相邻字段重叠],
errors: []
},
errors: null,
error_message: null
}
状态值：
AI正在填写表单 |
| completed | 完成 — 从 filledformurl 下载 |
| failed | 出现问题 — 检查 error_message |
每5-10秒轮询一次，直到状态变为 completed 或 failed。
Webhook通知（可选）
如果您提供 webhook_url，DeepRead会在任务完成时POST结果：
完成时：
json
{
jobid: id>,
status: completed,
created_at: ,
completed_at: ,
result: {
filledformurl: <下载已填写PDF的签名URL>,
fields_detected: 25,
fields_filled: 23,
fields_verified: 21,
fieldshilflagged: 2,
report: { ... }
}
}
失败时：
json
{
jobid: id>,
status: failed,
created_at: ,
completed_at: ,
error: 表单填写在600秒后超时,
errors: [表单填写在600秒后超时]
}
工作原理（底层机制）
上传PDF + JSON数据
│
▼
┌──────────────────────┐
│ 1. 检测字段 │ 视觉AI扫描每一页，找到所有可填写区域
│ （视觉检测，非PDF │ 返回：标签、类型、页码、边界框坐标
│ 表单字段） │
└──────────┬───────────┘
▼
┌──────────────────────┐
│ 2. 映射数据 │ AI语义匹配您的JSON键 → 表单字段
│ full_name → │ 转换值：拆分姓名、格式化日期、
│ 全名 字段 │ 转换复选框、添加货币符号
└──────────┬───────────┘
▼
┌──────────────────────┐
│ 3. 填写表单 │ 在PDF上的视觉坐标位置放置文本
│ 基于坐标的插入 │ 处理：文本、复选框、下拉菜单
└──────────┬───────────┘
▼
┌──────────────────────┐
│ 4. 质量检查 │ 视觉AI重新读取已填写的表单以验证：
│ 视觉验证 │ - 文本可读，未被截断
│ │ - 位置正确，无重叠
