Affinda’s Document AI API turns any incoming document — from invoices and résumés to passports and bills of lading — into clean, structured JSON you can drop straight into your workflow. Behind the scenes our models have already processed more than 250 million documents for 500 + organisations in 40 countries; the API is the thin, dependable interface that lets your own code tap that capability.
Design principles
- Few moving parts – A small set of REST resources (
/documents
,/document_types
,/workspaces
) covers the vast majority of use‑cases. - Works straight away, yet customisable – Upload a PDF and retrieve JSON in a single call, or fine‑tune behaviour with model versions, human‑in‑the‑loop validation and post‑processing rules.
- Document‑agnostic by design – The same endpoint handles an invoice today and a payslip tomorrow; just swap the document type ID, not your integration.
- Observability built‑in – Every response carries processing timestamps and confidence scores; webhook signatures let you verify payloads.
- Secure at scale – ISO‑27001 compliant, API keys scoped per user, with regional endpoints to keep data where you need it.
Core primitives
Primitive | Purpose |
---|---|
Document | The file you upload (PDF, image, DOCX, etc.) plus its extracted data and metadata. |
Document Type | A model configuration that defines how a specific kind of document (invoice, résumé, passport, custom layout, …) is parsed. |
Workspace | Logical container that groups documents, permissions and webhook settings. |
With just these three concepts you can automate everything from accounts‑payable to talent acquisition.
Prerequisites
Before you make your first API call you’ll need to:
- Create an Affinda account and log in to the dashboard.
- Generate an API key (Settings → API Keys).
- Configure a document type (A step‑by‑step guide to these tasks can be found in the Getting Started section of the docs)
- Retrieve the workspace identifier (Workspace -> Workflow -> Integrations).
.
Parse your first document
# 1. Set your API key (found in the Affinda dashboard)
export AFFINDA_API_KEY="aff_562..."
# 2. Upload a document and wait for processing to finish
curl -X POST https://api.affinda.com/v3/documents \
-H "Authorization: Bearer $AFFINDA_API_KEY" \
-F "file=@sample_invoice.pdf" \
-F "workspace=YOUR_WORKSPACE_IDENTIFIER"
# !pip install affinda
from pathlib import Path
from affinda import AffindaAPI, TokenCredential
API_KEY = "YOUR_API_KEY" # replace with your actual key
WORKSPACE_ID = "YOUR_WORKSPACE_IDENTIFIER" # e.g. "vBAdDBer"
FILE_PATH = Path("resume.pdf") # path to the résumé you want to parse
# Set up the client
credential = TokenCredential(token=API_KEY)
client = AffindaAPI(credential=credential)
# Upload the document and wait until processing finishes
with FILE_PATH.open("rb") as f:
doc = client.create_document(
file=f,
workspace=WORKSPACE_ID,
)
# Access parsed data
print(doc.data)
import { AffindaAPI, AffindaCredential } from "@affinda/affinda";
import * as fs from "fs";
const credential = new AffindaCredential("YOUR_API_KEY");
const client = new AffindaAPI(credential);
const file = fs.createReadStream("resume.pdf");
client
.createDocument({
file,
workspace: "YOUR_WORKSPACE_IDENTIFIER",
})
.then(doc => {
console.log("Parsed data:", doc.data);
})
.catch(err => console.error("Error:", err));
Pydantic models
Generating Pydantic models
Users of our Python client library can generate pydantic models to help with validating and consuming the API response in a type-safe way.
Use the generate_models
command to auto-generate pydantic models from your document type configuration.
For example, this will generate pydantic models for your Recruitment workspace:
# Assuming your Recruitment workspace ID is rLERIsHk
python -m affinda generate_models --workspace-id=rLERIsHk
You will be prompted for your API key, unless you already have the AFFINDA_API_KEY
environment variable set.
The generated pydantic model(s) will be in ./affinda_models
by default.
For the list of options available, run:
python -m affinda generate_models --help
Example of using the generated pydantic models
from pathlib import Path
from affinda import AffindaAPI, TokenCredential
from affinda_models.resume_parser import ResumeParser
API_KEY = "YOUR_API_KEY" # replace with your actual key
WORKSPACE_ID = "YOUR_WORKSPACE_IDENTIFIER" # e.g. "vBAdDBer"
FILE_PATH = Path("resume.pdf") # path to the résumé you want to parse
# Set up the client
credential = TokenCredential(token=API_KEY)
client = AffindaAPI(credential=credential)
# This will raise `pydantic_core.ValidationError` if the API response
# does not validate against ResumeParser
with FILE_PATH.open("rb") as f:
doc = client.create_document(
file=f,
workspace=WORKSPACE_ID,
data_model=ResumeParser,
)
# Access parsed data
print(doc.parsed) # This is a ResumeParser instance
print(doc.data) # This is the raw JSON response
# This will NOT raise `pydantic_core.ValidationError` if the API response
# does not validate against ResumeParser.
# Instead `parsed` will be None if the API response is not compatible.
with FILE_PATH.open("rb") as f:
doc = client.create_document(
file=f,
workspace=WORKSPACE_ID,
data_model=ResumeParser,
ignore_validation_errors=True,
)
if doc.parsed:
print("API response is valid.")
print(doc.parsed)
else:
print("API response is invalid.")
print(doc.data) # The raw JSON response is still available
Typescript interfaces
Generating Typescript interfaces
Users of our Typescript client library can generate typescript interfaces to help with consuming the API response in a type-safe way.
Use the affinda-generate-interfaces
command to auto-generate typescript interfaces from your document type configuration.
For example, this will generate typescript interfaces for your Recruitment workspace:
# Assuming your Recruitment workspace ID is "rLERIsHk"
npm exec affinda-generate-interfaces -- --workspace-id=rLERIsHk
You will be prompted for your API key, unless you already have the AFFINDA_API_KEY
environment variable set.
The generated typescript interfaces will be in ./affinda-interfaces
by default.
For the list of options available, run:
npm exec affinda-generate-interfaces -- --help