Form Fill

Fill PDF forms with AI-powered field detection.

Enterprise plans. A request from another plan is refused with 402 naming the plan that has it — the same body as every plan-gated feature (documented under the status codes in the OCR reference).

POST /v1/form-fill

Upload a PDF form and field data for AI-powered filling.

Endpoint

POST https://api.deepread.tech/v1/form-fill

Authentication

Include your API key in the X-API-Key header:

X-API-Key: YOUR_API_KEY

Request

Headers

Request Body (Multipart)

Example Request

curl -X POST https://api.deepread.tech/v1/form-fill \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@application_form.pdf" \
  -F 'form_fields={"full_name": "John Doe", "date_of_birth": "1990-01-15", "ssn": "123-45-6789", "address": "123 Main St", "city": "New York", "state": "NY", "zip": "10001"}' \
  -F "webhook_url=https://your-app.com/webhooks/form-fill"

Response

Success Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

Response Fields

Status Codes

GET /v1/form-fill/{job_id}

Retrieve the status and results of a form fill job.

Endpoint

GET https://api.deepread.tech/v1/form-fill/{job_id}

Authentication

X-API-Key: YOUR_API_KEY

Path Parameters

Example Request

curl https://api.deepread.tech/v1/form-fill/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: $DEEPREAD_API_KEY"

Response

Success Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "file_name": "application_form.pdf",
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:08Z",
  "filled_form_url": "https://storage.deepread.tech/filled/abc123.pdf",
  "fields_detected": 12,
  "fields_filled": 10,
  "fields_verified": 10,
  "fields_hil_flagged": 0,
  "duration_seconds": 8.5,
  "report": { ... },
  "errors": []
}

Response Fields

Status Codes

Idempotency

Use the idempotency_key parameter to prevent duplicate form fills:

curl -X POST https://api.deepread.tech/v1/form-fill \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@application_form.pdf" \
  -F 'form_fields={"full_name": "John Doe"}' \
  -F "idempotency_key=user-123-form-456-2024-01-15"

If a job with the same idempotency key already exists, the API returns the existing job instead of creating a new one.

Webhooks

When you provide a webhook_url, DeepRead sends a POST request when the job completes:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:08Z",
  "result": {
    "filled_form_url": "https://storage.deepread.tech/filled/abc123.pdf",
    "fields_detected": 12,
    "fields_filled": 10,
    "fields_verified": 10,
    "fields_hil_flagged": 0,
    "report": { ... }
  }
}

For failed jobs:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "created_at": "2024-01-15T10:30:00Z",
  "error": "Unable to detect form fields in document",
  "errors": ["..."]
}

Rate Limits

Limits are per plan. Past a limit the request is refused with 429 and a Retry-After header saying when to try again.

A form-fill job counts its pages towards the account's pages in flight (16 on Free, 200 on Standard, 500 on Enterprise), shared with OCR and PII redaction jobs. No document over 2,000 pages or 500 MB is accepted on any plan (413).

Response headers include:

• X-RateLimit-Limit: Maximum requests per period
• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: Unix timestamp when limit resets