Extraction Flow

Use review_decision_managed to select the workflow. False or absent preserves your existing legacy endpoints, booleans, and review behavior. True uses explicit review states, terminal cancellation, and read-only decisions. For managed documents, missing or unknown state stops processing. See the state dispatcher.

Complete Extraction Workflow

Understanding the full extraction lifecycle helps you build robust automation pipelines. Here’s how documents flow through the system:

Phase 1: Document Upload

Upload Files

Submit documents via POST /upload. You may send multiple files form fields in one request.

import requests

response = requests.post(
    "https://api.documind.cloud/api/v1/upload",
    headers={"X-API-Key": "your_api_key"},
    files=[
        ("files", open("invoice1.pdf", "rb")),
        ("files", open("invoice2.pdf", "rb"))
    ]
)
document_ids = response.json()
# Returns: ["uuid1", "uuid2"]

Credit Impact: No credits charged for upload Storage: No public retention SLA is exposed by the backend

Receive Document IDs

Store the returned UUIDs for extraction requests.

# Map filenames to IDs for tracking
doc_mapping = {
    "invoice1.pdf": document_ids[0],
    "invoice2.pdf": document_ids[1]
}

Phase 2: Schema Definition

Choose one of three approaches:

Predefined Schema (UI Only)
Custom Schema
Generated Schema

Use the Documind UI to access built-in templates for common document types like invoices, receipts, forms, etc.Navigate to: Dashboard → Schemas → Templates

✓ Fastest setup ✓ Proven accuracy ✗ Not available via API (use UI or define custom schema)

Define your own schema for unique documents:

schema = {
    "named_entities": {
        "policy_number": {
            "type": "string",
            "description": "Insurance policy number"
        },
        "coverage_amount": {
            "type": "number",
            "description": "Total coverage in USD"
        }
    },
    "required": ["policy_number"]
}

✓ Fully customizable ✓ Matches your exact needs ✗ Requires domain knowledge

Auto-generate schema from a sample document or description:Option 1: Generate from Sample Document (Recommended)

import requests

# Upload sample document
with open("sample_policy.pdf", "rb") as f:
    response = requests.post(
        "https://api.documind.cloud/api/v1/upload",
        headers={"X-API-Key": "your_api_key"},
        files={"files": f}
    )
sample_id = response.json()[0]

# Generate schema from sample
response = requests.post(
    f"https://api.documind.cloud/api/v1/schema/{sample_id}",
    headers={"X-API-Key": "your_api_key"}
)
schema = response.json()["schema"]

Option 2: Generate from Description

response = requests.post(
    "https://api.documind.cloud/api/v1/generate-dynamic-schema/",
    headers={"X-API-Key": "your_api_key", "Content-Type": "application/json"},
    json={
        "schema_name": "insurance_policy",
        "schema_description": "Extract policy number, coverage amount, policyholder name, and effective dates"
    }
)
schema = response.json()

Both methods are available in the UI (Dashboard → Schemas → Generate) and via API

✓ Quick start ✓ AI-generated from your documents ✗ May need refinement

Phase 3: Data Extraction

Configure extraction mode based on requirements:

Mode Selection Decision Tree

Start
  ├─ Need confidence scores? ──No──> Basic Extraction
  │                                   (2-6 credits/page)
  │
  └─ Yes
      ├─ Scanned/Image documents? ──Yes──> VLM Extraction
      │                                     (10 credits/page)
      │
      └─ No (Native PDF/Text)
          └─ Critical accuracy needed? ──Yes──> Advanced Extraction
                                                  (15 credits/page)

Basic Extraction Example

import requests

response = requests.post(
    f"https://api.documind.cloud/api/v1/extract/{document_id}",
    headers={"X-API-Key": "your_api_key", "Content-Type": "application/json"},
    json={
        "schema": schema,
        "model": "google-gemini-2.5-flash",  # or "qwen-3-vl"
        "prompt": "Extract all invoice fields accurately"
    }
)
result = response.json()

# Confirm stored state with poll_for_review before downstream processing.

Advanced Extraction Example

import requests

response = requests.post(
    f"https://api.documind.cloud/api/v1/extract/{document_id}",
    headers={"X-API-Key": "your_api_key", "Content-Type": "application/json"},
    json={
        "schema": schema,
        # Advanced mode - no model or extraction_mode specified
        "review_threshold": 85,
        "prompt": "Extract invoice with high accuracy"
    }
)
result = response.json()

# Includes confidence scores
# Some required fields below threshold
print("⚠️  Needs human review")
# Proceed to Phase 4

Credit Usage: Credits deducted per page × model cost

Phase 4: Review Workflow

Copy poll_for_review from Polling for Reviews into a local review_polling.py module in your integration. Copy the imports and function definition only; keep the module-level usage demonstration in your caller. This is customer code, not an installed SDK. Synchronous extraction responses do not include technical status; the helper reads stored state.

from review_polling import poll_for_review
outcome = poll_for_review(document_id, api_key)
if outcome["outcome"] == "continue":
    process_document(outcome["results"])
elif outcome["outcome"] == "cancel":
    cancel_downstream_work_item(document_id)
elif outcome["outcome"] == "legacy_policy":
    apply_existing_legacy_policy(document_id)
else:
    alert_review_team(document_id)

Phase 5: Data Processing

Process the final data in your automation:

def process_invoice_data(data):
    """Process extracted/reviewed invoice data."""

    # Validate required fields
    assert "invoice_number" in data
    assert "total_amount" in data

    # Update your system
    create_accounting_record(
        invoice_number=data["invoice_number"],
        amount=data["total_amount"],
        vendor=data.get("vendor_name"),
        line_items=data.get("line_items", [])
    )

    # Archive original document
    archive_document(data["document_id"])

    return True

Complete Example

Complete upload, schema definition, and extraction as shown above. Then use the tested helper in Phase 4. Keep cancellation, legacy policy, and timeout separate from successful data processing. For batch and concurrent work, see Automation Pipeline.

Troubleshooting

Upload Fails

Problem: 500 Internal Server Error on uploadSolutions:

Verify file is not corrupted
Retry with a smaller request if infrastructure rejects the upload size
Ensure file format is supported
Retry with exponential backoff

Extraction Timeout

Problem: Extraction takes too long or times outSolutions:

Switch to Basic mode for faster processing
Reduce document page count
Simplify schema (fewer fields)
Contact support if issue persists

All Extractions Need Review

Problem: Review threshold too strictSolutions:

Lower review_threshold from 85 to 75
Mark fewer fields as required
Improve schema descriptions
Use Basic mode if reviews aren’t needed

Reviews Never Complete

Problem: Polling times out waiting for reviewSolutions:

Increase timeout to match your review SLA
Implement email notifications to reviewers
Check review queue isn’t backlogged
Consider async processing instead of blocking

Next Steps

Upload Documents

Detailed upload endpoint documentation

Extract Data

Complete extraction API reference

Polling Pattern

Robust polling implementation guide

Automation Patterns

Production-ready automation examples

Getting Started

Extraction Workflow

Review Workflow

Data Endpoints

Integration Patterns

Complete Extraction Workflow

Phase 1: Document Upload

Phase 2: Schema Definition

Phase 3: Data Extraction

Mode Selection Decision Tree

Basic Extraction Example

Advanced Extraction Example

Phase 4: Review Workflow

Phase 5: Data Processing

Complete Example

Troubleshooting

Next Steps

Upload Documents

Extract Data

Polling Pattern

Automation Patterns

​Complete Extraction Workflow

​Phase 1: Document Upload

​Phase 2: Schema Definition

​Phase 3: Data Extraction

​Mode Selection Decision Tree

​Basic Extraction Example

​Advanced Extraction Example

​Phase 4: Review Workflow

​Phase 5: Data Processing

​Complete Example

​Troubleshooting

​Next Steps

Upload Documents

Extract Data

Polling Pattern

Automation Patterns

Complete Extraction Workflow

Phase 1: Document Upload

Phase 2: Schema Definition

Phase 3: Data Extraction

Mode Selection Decision Tree

Basic Extraction Example

Advanced Extraction Example

Phase 4: Review Workflow

Phase 5: Data Processing

Complete Example

Troubleshooting

Next Steps