Affinda — AI Document Processing Platform

Affinda extracts structured data from documents (invoices, resumes, receipts, contracts, and any custom document type) using machine learning. The API turns uploaded files into clean JSON. Over 250 million documents processed for 500+ organisations in 40 countries.

Full documentation: https://docs.affinda.com OpenAPI spec: https://api.affinda.com/static/v3/api_spec.yaml Support: support@affinda.com

Core Concepts

The workflow is: Upload -> Pre-process -> Split -> Classify -> Extract -> Validate -> Export.

API Basics

Base URLs

https://api.affinda.com

https://app.affinda.com

https://api.us1.affinda.com

https://app.us1.affinda.com

https://api.eu1.affinda.com

https://app.eu1.affinda.com

Use the base URL matching the region where the user's account was created.

Authentication

All requests require a Bearer token:

Authorization: Bearer <API_KEY>

API keys are per-user, managed at Settings -> API Keys in the Affinda dashboard. Up to 3 keys per user. Keys can have custom names and expiry dates. A key is only visible once at creation -- store it securely.

Rate Limits and File Constraints

• High-priority queue: 30 documents/minute (exceeding returns

  429

  )
• Low-priority queue: No submission limit (set

  lowPriority: true

  )
• Max file size: 20 MB (5 MB for resumes)
• Default page limit: 20 pages per document (can be increased on request)
• Supported formats: PDF, DOC, DOCX, XLSX, ODT, RTF, TXT, HTML, PNG, JPG, TIFF, JPEG

Client Libraries

Python (recommended)

pip install affinda

from pathlib import Path
from affinda import AffindaAPI, TokenCredential

credential = TokenCredential(token="YOUR_API_KEY")
client = AffindaAPI(credential=credential)

with Path("invoice.pdf").open("rb") as f:
    doc = client.create_document(file=f, workspace="YOUR_WORKSPACE_ID")

print(doc.data)  # Extracted JSON

GitHub: https://github.com/affinda/affinda-python PyPI: https://pypi.org/project/affinda/

TypeScript / JavaScript (recommended)

npm install @affinda/affinda

import { AffindaAPI, AffindaCredential } from "@affinda/affinda";
import * as fs from "fs";

const credential = new AffindaCredential("YOUR_API_KEY");
const client = new AffindaAPI(credential);

const doc = await client.createDocument({
  file: fs.createReadStream("invoice.pdf"),
  workspace: "YOUR_WORKSPACE_ID",
});

console.log(doc.data); // Extracted JSON

GitHub: https://github.com/affinda/affinda-typescript npm: https://www.npmjs.com/package/@affinda/affinda

Other Libraries

• .NET:

  dotnet add package Affinda.API

  -- GitHub
• Java: Maven repository -- GitHub

Note: The .NET and Java libraries may lag behind the Python and TypeScript libraries in feature parity.

Direct HTTP (cURL)

curl -X POST https://api.affinda.com/v3/documents \
  -H "Authorization: Bearer $AFFINDA_API_KEY" \
  -F "file=@invoice.pdf" \
  -F "workspace=YOUR_WORKSPACE_ID"

Structured Outputs (Type-Safe Responses)

This is the recommended approach for building robust integrations. Affinda can generate typed models from your document type configuration, giving you auto-completion, validation, and type safety.

Python -- Pydantic Models

Generate Pydantic v2 models that match your document type's field schema:

# Set your API key (or export AFFINDA_API_KEY)
python -m affinda generate_models --workspace-id=YOUR_WORKSPACE_ID

This creates a

./affinda_models/

.py

BaseModel

Use the generated models when calling the API:

from pathlib import Path
from affinda import AffindaAPI, TokenCredential
from affinda_models.invoice import Invoice  # Generated model

credential = TokenCredential(token="YOUR_API_KEY")
client = AffindaAPI(credential=credential)

with Path("invoice.pdf").open("rb") as f:
    doc = client.create_document(
        file=f,
        workspace="YOUR_WORKSPACE_ID",
        data_model=Invoice,  # Enables Pydantic validation
    )

# doc.parsed is a typed Invoice instance
print(doc.parsed.invoice_number)
print(doc.parsed.total_amount)

# doc.data is still available as raw JSON
print(doc.data)

Handling validation errors gracefully:

with Path("invoice.pdf").open("rb") as f:
    doc = client.create_document(
        file=f,
        workspace="YOUR_WORKSPACE_ID",
        data_model=Invoice,
        ignore_validation_errors=True,  # Don't raise on schema mismatch
    )

if doc.parsed:
    print(doc.parsed.invoice_number)  # Type-safe access
else:
    print("Validation failed, falling back to raw data")
    print(doc.data)

CLI options:

python -m affinda generate_models --workspace-id=ID        # All types in a workspace
python -m affinda generate_models --document-type-id=ID    # Single document type
python -m affinda generate_models --organization-id=ID     # All types in an org
python -m affinda generate_models --output-dir=./my_models # Custom output path
python -m affinda generate_models --help                   # All options

TypeScript -- Generated Interfaces

Generate TypeScript interfaces that match your document type's field schema:

# Set your API key (or export AFFINDA_API_KEY)
npm exec affinda-generate-interfaces -- --workspace-id=YOUR_WORKSPACE_ID

This creates an

./affinda-interfaces/

.ts

Use the generated interfaces for type-safe access:

import { AffindaAPI, AffindaCredential } from "@affinda/affinda";
import * as fs from "fs";
import { Invoice } from "./affinda-interfaces/Invoice";

const credential = new AffindaCredential("YOUR_API_KEY");
const client = new AffindaAPI(credential);

const doc = await client.createDocument({
  file: fs.createReadStream("invoice.pdf"),
  workspace: "YOUR_WORKSPACE_ID",
});

const parsed = doc.data as Invoice;
console.log(parsed.invoiceNumber);  // Type-safe access
console.log(parsed.totalAmount);

CLI options:

npm exec affinda-generate-interfaces -- --workspace-id=ID       # All types in workspace
npm exec affinda-generate-interfaces -- --document-type-id=ID   # Single document type
npm exec affinda-generate-interfaces -- --output-dir=./types    # Custom output path
npm exec affinda-generate-interfaces -- --help                  # All options

Why Use Structured Outputs?

• Type safety: Catch field name typos and type mismatches at compile/lint time
• Auto-completion: IDE support for all extracted fields
• Validation: Pydantic automatically validates the API response structure
• Schema-driven: Models stay in sync with your document type configuration -- regenerate after schema changes
• Documentation as code: The generated models serve as living documentation of your extraction schema

Document Upload Options

There are three patterns for submitting documents and retrieving results:

1. Synchronous (simplest)

Upload and block until parsing completes. The response contains the extracted data.

doc = client.create_document(file=f, workspace="WORKSPACE_ID")
# wait defaults to True -- blocks until ready
print(doc.data)

Best for: Interactive apps, low volume, quick prototyping. Limitation: Can timeout on large or complex documents.

2. Asynchronous with Polling

Upload with

wait=false

GET /documents/{id}

ready

true

doc = client.create_document(file=f, workspace="WORKSPACE_ID", wait=False)
# doc.data is empty -- poll until ready
doc = client.get_document(doc.meta.identifier)

Best for: Batch processing, large documents, high volume.

3. Asynchronous with Webhooks (recommended for production)

Upload the document, then receive a webhook notification when processing completes. This is the most efficient pattern for production systems.

# 1. Upload
doc = client.create_document(file=f, workspace="WORKSPACE_ID", wait=False)

# 2. Receive webhook at your endpoint when ready
# 3. Fetch full data
doc = client.get_document(identifier_from_webhook)

Best for: Real-time workflows, event-driven architectures, production systems.

See the Webhooks section below for setup details.

Upload Parameters

file

url

url

file

workspace

documentType

wait

true

false

customIdentifier

expiryTime

rejectDuplicates

lowPriority

compact

wait=true

deleteAfterParse

wait=true

enableValidationTool

false

Response Structure

Each extracted field in the response includes metadata:

raw

parsed

confidence

classificationConfidence

textExtractionConfidence

isVerified

isClientVerified

isAutoVerified

rectangle

pageIndex

Document-level metadata includes

ready

failed

language

pages

isOcrd

ocrConfidence

reviewUrl

isConfirmed

isRejected

isArchived

errorCode

errorDetail

Full metadata reference: https://docs.affinda.com/reference/metadata

Webhooks

Affinda uses RESTHooks -- webhook subscriptions managed via REST API. Webhooks can be scoped to an organization or workspace.

Available Events

document.parse.completed

document.parse.succeeded

document.parse.failed

document.validate.completed

document.classify.completed

document.classify.succeeded

document.classify.failed

document.rejected

Setup Flow

1. Subscribe --

   POST /v3/resthook_subscriptions

   with

   targetUrl

   ,

   event

   , and

   organization

   (or

   workspace

   ).
2. Confirm -- Affinda sends a

   POST

   to your

   targetUrl

   with an

   X-Hook-Secret

   header. Respond with

   200

   , then call

   POST /v3/resthook_subscriptions/activate

   with that secret.
3. Receive -- Affinda sends webhook payloads to your endpoint. Respond

   200

   to acknowledge.

Signature Verification

Enable payload signing via Organization Settings -> Webhook Signature Key. Incoming webhooks include an

X-Hook-Signature

<timestamp>.<signature>

import hmac, hashlib, json, time

def verify_webhook(request, sig_key: bytes) -> bool:
    sig_header = request.headers["X-Hook-Signature"]
    timestamp, sig_received = sig_header.split(".")
    sig_calculated = hmac.new(sig_key, msg=request.body, digestmod=hashlib.sha256).hexdigest()

    sig_ok = hmac.compare_digest(sig_received, sig_calculated)
    body = json.loads(request.body)
    time_ok = (time.time() - body["timestamp"]) < 600  # 10 min window
    return sig_ok and time_ok

Webhook Payload

The payload contains document metadata (not the full parsed data). Use the

identifier

{
  "id": "e3bd1942-...",
  "event": "document.parse.completed",
  "timestamp": 1665637107,
  "payload": {
    "identifier": "abcdXYZ",
    "ready": true,
    "failed": false,
    "fileName": "invoice.pdf",
    "workspace": { "identifier": "...", "name": "..." }
  }
}

Retry Behavior

• 200

  -- Success, delivery confirmed

• 410

  -- Subscription auto-deleted (endpoint "gone")
• Other 4xx/5xx -- Retried with exponential backoff for ~1 day

Full webhook docs: https://docs.affinda.com/reference/webhooks

Embedded Validation UI

Affinda provides a human-in-the-loop validation interface that can be embedded in your application via iframe. Each document response includes a

reviewUrl

Implementation pattern:

1. Store only the Affinda document

   identifier

   in your system
2. When a user needs to review, fetch a fresh

   reviewUrl

   via

   GET /documents/{id}

3. Embed the URL in an iframe
4. Do not persist the URL -- treat it as ephemeral

The UI supports custom theming (colors, fonts, border radius) in embedded mode. Contact Affinda to configure.

Full embedded docs: https://docs.affinda.com/reference/embedded

Key API Methods

Documents

/v3/documents

/v3/documents/{id}

/v3/documents/{id}

/v3/documents/{id}

/v3/documents

/v3/documents/{id}/redacted

Workspaces

/v3/workspaces

/v3/workspaces

/v3/workspaces/{id}

/v3/workspaces/{id}

/v3/workspaces/{id}

Annotations

/v3/annotations

/v3/annotations

/v3/annotations/{id}

/v3/annotations/batch_create

/v3/annotations/batch_update

/v3/annotations/batch_delete

Webhooks

/v3/resthook_subscriptions

/v3/resthook_subscriptions/activate

/v3/resthook_subscriptions

/v3/resthook_subscriptions/{id}

/v3/resthook_subscriptions/{id}

Full API reference: https://docs.affinda.com/reference/getting-started OpenAPI spec: https://api.affinda.com/static/v3/api_spec.yaml

Common Integration Patterns

Affinda supports six integration workflow patterns depending on where validation logic lives and where exceptions are handled:

document.parse.completed

document.parse.completed

document.validate.completed

document.validate.completed

document.parse.completed

document.validate.completed

document.validate.completed

For most new integrations, W1 or W2 is the simplest starting point. W6 provides the most automation with human-in-the-loop for exceptions.

Full solution design guide: https://docs.affinda.com/academy/solution-design

Common Errors

duplicate_document_error

no_text_found

file_corrupted

file_too_large

invalid_file_type

no_parsing_credits

password_protected

document_classification_failed

capacity_exceeded

parse_terminated

Full error reference: https://docs.affinda.com/error-glossary

Documentation Map

Use this index to find detailed information on specific topics. Each link goes to the full documentation page.

Affinda Academy (Tutorials)

• Getting Started -- Core concepts: organizations, workspaces, document types, statuses, and the processing workflow.
• Creating a New Model -- Step-by-step guide to creating extraction models from scratch.
• Improving Accuracy -- Strategies for 99%+ accuracy via model memory, field prompts, and OCR settings.
• User Validation of Extracted Data -- How to validate and correct extractions in the Affinda UI.
• Table Editor -- Grid and freeform modes for validating table extractions.
• Reviewing Splitting & Classification -- How to correct document splitting and classification.
• Schema Design Best Practices -- Field configuration trade-offs, advanced options, and schema design guidance.
• Straight-Through Processing -- Data mapping, validation rules, and auto-confirmation for full automation.
• Integration Workflows -- Six workflow patterns (W1-W6) for different integration scenarios.
• Integration Agent -- No-code integrations using AI agent and Pipedream.

Configuration Guide

Overview & Workflow:

• Workflow -- End-to-end document processing pipeline stages.
• Glossary -- Platform terminology definitions.
• Document Status -- For Review, Confirmed, Archived, Rejected states.

Ingestion & Pre-Processing:

• Ingestion -- Upload methods: manual, email, API.
• Email Upload -- Email-to-workspace document ingestion.
• Pre-Processing -- Automated cleaning before extraction.
• OCR -- OCR modes: Skip, Auto-detect, Partial, Full.
• Duplicates -- Duplicate detection and rejection.

Splitting, Classification & Extraction:

• Splitting -- Auto-separate multi-document files.
• Classification -- Auto-categorize documents by type.
• Field Configuration -- Field names, types, and settings.
• Standard Fields -- Text, numbers, dates, location, phone, URL types.
• Groups & Tables -- Repeating structures and line items.
• Picklists & Data Sources -- Controlled vocabularies and master data matching.
• Checkboxes -- Label and true/false checkbox extraction.
• Image Fields -- Signature, headshot, and seal extraction.
• Model Memory -- RAG-based learning from validated documents.

Validation & Export:

• Machine Validation -- Automated validation overview.
• Validation Rules -- Natural-language business rule creation.
• Confidence -- Confidence scoring and thresholds.
• User Validation -- Human review interface.
• Data Export -- JSON, XML, CSV export options.
• Redaction -- PDF redaction of sensitive data.
• User Management -- Roles and permissions.

API Reference

• Quick Start -- First API call walkthrough with code examples.
• Authentication -- API key management and rotation.
• Upload Options -- Sync, async polling, and webhook patterns.
• Metadata -- Field-level and document-level metadata reference.
• Limits -- Rate limits, file size limits, page limits.
• Webhooks -- Webhook setup, events, signature verification.
• Embedded Mode -- Embedding validation UI via iframe.
• Client Libraries -- Python, JavaScript, .NET, Java SDKs.
• Structured Outputs (Pydantic) -- Generate Python Pydantic models from document types.
• TypeScript Interfaces -- Generate TypeScript interfaces from document types.

Resume Parsing Guide

• Getting Started -- Resume parsing product overview and workspace setup.
• Integration -- Resume parser API integration with code examples.
• Credits -- Per-document credit system for resume parsing.
• Data Extracted -- All fields extracted from resumes with sample JSON.
• Taxonomies -- Skills, job titles, and occupation standardization.
• Resume Redactor -- Automated PII redaction for unbiased hiring.
• Resume Summary -- AI-generated candidate summaries.
• Job Description Parser -- Structured extraction from job descriptions.
• Search & Match -- Candidate/job matching with scoring and search UI.

Additional Resources

• Error Glossary -- Error codes and resolutions.
• FAQs -- Common questions on capabilities, configuration, and troubleshooting.
• Billing -- Credits, pricing, and payment.
• Data Retention -- Document deletion and expiry policies.
• Deployment & Data Residency -- Regional servers and enterprise options.
• Product Updates -- Changelog and release notes.
• Status -- Service availability dashboard.