canonical: https://jentic.com/apis/affinda.com/affinda

# Affinda API

Jentic publishes the only available OpenAPI specification for Affinda API, keeping it validated and agent-ready. Affinda is a document-AI platform that extracts structured data from resumes, invoices, receipts, IDs, and other document types and supports recruiter-facing resume search, job-description search, and skill-and-occupation taxonomies. Version 3 of the API exposes 140 endpoints covering document upload and parsing, workspaces and document types, validation results, mapping data sources, tags and annotations, webhook subscriptions, and dedicated resume and job-description search engines. Authentication uses a bearer token issued from the Affinda dashboard.

## For AI agents

Parse resumes, invoices, and other documents, manage extracted data, and run resume and job-description search across 140 Affinda v3 endpoints.

## Scope

Does not handle e-signature, document storage as a primary file system, or candidate outreach - use for document parsing, validation, and resume/job search only.

## Capabilities

- Upload documents to Affinda and retrieve structured extraction results
- Manage workspaces, document types, and per-type JSON schemas
- Run resume search with filters, embeddings, and match scoring
- Search job descriptions and match them against indexed resumes
- Maintain mapping data sources to normalise values across documents
- Manage tags, annotations, and validation results on parsed documents
- Subscribe to resthook webhooks to receive parsed-document notifications

## Use cases

### Resume Parsing for Recruiting Workflows

Replace manual resume entry with structured extraction. POST /v3/documents uploads a resume and Affinda returns parsed fields - name, contact, work history, education, skills - using an extraction schema you control via /v3/document_types. Combined with the resume_search endpoints, recruiters can index parsed resumes and rank them against requirements without leaving their ATS.

Example prompt: Call POST /v3/documents with a resume file and document_type=resume and return the parsed name, email, and most recent role

### Resume and Job-Description Search

Build a recruiter-facing search engine on top of parsed documents. POST /v3/resume_search ranks candidates against a query, /v3/resume_search/match scores a specific resume against a job, /v3/job_description_search runs the inverse, and /resume_search/suggestion_skill and /suggestion_job_title surface taxonomy-aware hints. Useful for ATS vendors and talent platforms that want production-grade matching without training their own embeddings.

Example prompt: Call POST /v3/resume_search with skills=['python','aws'] and location='Berlin' and return the top 20 ranked candidates with match scores

### Invoice and Receipt Extraction

Extract structured line items, totals, taxes, and vendor data from invoices and receipts using the same /v3/documents endpoint with the appropriate document_type. The /v3/validation_results endpoints let an operator confirm or correct extracted fields, and /v3/document_types/{identifier}/json_schema returns the schema being applied so finance systems can map fields one-for-one.

Example prompt: Call POST /v3/documents with an invoice PDF, then call GET /v3/validation_results?document={id} to retrieve the extracted line items

### AI Agent Document Pipeline

Give an AI agent a single document-AI tool that handles parsing, search, and tagging. Through Jentic, the agent searches by intent for the right Affinda v3 operation, loads the schema, and executes with the bearer token isolated in the vault. The agent can chain extraction, validation, and downstream CRM updates without bespoke integration code.

Example prompt: Search Jentic for 'parse a resume document', load the /v3/documents schema, and execute with the file payload and document_type=resume

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v3/documents | Upload a document for parsing |
| GET | /v3/documents/{identifier} | Retrieve a parsed document |
| POST | /v3/resume_search | Search the resume index against a query |
| GET | /v3/resume_search/match | Score a resume against a job description |
| POST | /v3/job_description_search | Search job descriptions against indexed resumes |
| GET | /v3/document_types/{identifier}/json_schema | Return the JSON schema applied for a document type |
| POST | /v3/resthook_subscriptions | Create a webhook subscription for document events |

## Key resources

- **Documents** — Upload documents and retrieve parsed extraction results
- **Document Types** — Manage extraction schemas and per-type JSON schemas
- **Workspaces** — Group documents by project, with usage and membership endpoints
- **Validation Results** — Confirm or correct extracted fields per document
- **Data Sources** — Mapping data sources for value normalisation
- **Tags** — Apply and remove tags on documents in batches
- **Annotations** — Manage annotations on parsed documents
- **Search & Match** — Resume search, job-description search, embed, match, and suggestions
- **Webhooks** — Resthook subscriptions for document and validation events
- **Index** — Manage search indexes for documents

## Why Jentic

- **Setup:** Wiring the Affinda API by hand means learning its bearer auth and picking the right operation from a large v3 surface spanning document parsing, resume search, and webhooks. Through Jentic you install once, import the Affinda API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Affinda puts the document identifier in the URL path (/v3/documents/{identifier}), so a rule can pin the agent to reading a specific document, while creation and search take their input in the body. You choose which operations are in the allowed set, so resthook subscriptions are not included unless you add them.
- **Credential handling:** Your Affinda bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'parse a resume document', and Jentic returns the matching v3 operation with its multipart or JSON schema so the agent picks the document endpoint without browsing the reference docs.

## Related APIs

- **Mindee** — Document parsing API focused on invoices, receipts, IDs, and forms
- **Rossum** — AP-focused document AI for invoice extraction and validation
- **Veryfi** — Receipt and invoice OCR with mobile capture SDKs
- **Lever** — ATS that consumes parsed candidate data from document parsers

## FAQ

### Why is there no official OpenAPI spec for the Affinda API?

Affinda publishes interactive docs but does not distribute a downloadable OpenAPI 3 specification. Jentic generates and maintains this spec so that AI agents and developers can call Affinda API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Affinda API use?

Affinda uses an HTTP bearer token; pass Authorization: Bearer <token> on every request with a token issued from the Affinda dashboard. Through Jentic the token is stored in the vault and injected at execution time.

### Which regions does the Affinda API serve?

Affinda runs three regional instances - AUS/Global at https://api.affinda.com, US at https://api.us1.affinda.com, and EU at https://api.eu1.affinda.com. Use the URL that matches the region your account was provisioned in to keep documents inside that data boundary.

### Can I parse resumes and invoices with the same Affinda API?

Yes. POST /v3/documents handles every document type - the document_type parameter selects the extraction schema, and /v3/document_types lists the schemas available to your account. The same endpoint returns resumes, invoices, receipts, IDs, or any custom type.

### What are the rate limits for the Affinda API?

Affinda applies per-tier credit and concurrency limits but does not declare specific numbers in the spec. Check your plan in the Affinda dashboard and watch for HTTP 429 responses; Jentic surfaces them so agents can back off.

### How do I run a resume search through Jentic?

Run pip install jentic, search Jentic with 'search resumes by skills and location', load the /v3/resume_search schema, and execute with the criteria in the request body. Jentic injects the bearer token at execution time.

### Can I limit what my agent is allowed to do with the Affinda API?

Yes. Because you run Jentic One yourself, your own rules decide which Affinda operations and credentials the agent can use, and you pick exactly which endpoints are in the allowed set. Since Affinda puts the document identifier in the URL path at /v3/documents/{identifier}, a rule can pin the agent to reading a specific parsed document, while creation and resume or job-description search take their input in the request body. Operations you leave out stay unavailable, so the agent cannot create /v3/resthook_subscriptions webhooks unless you add that operation to its allowed set.