Quick Start

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