> ## Documentation Index
> Fetch the complete documentation index at: https://docs.affinda.com/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.affinda.com/feedback

```json
{
  "path": "/reference/getting-started",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# API quick start guide

> Quick start for the Affinda API: create an API key, upload your first document, retrieve extracted data, and integrate the response into your application.

<Note>
  Affinda's Integration Agent helps teams quickly integrate with 1,000s of systems. See our [Tutorial: Creating your integration using our AI agent](/academy/integration-agent) for a comprehensive step-by-step guide.
</Note>

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.

## Relevant tutorials

<CardGroup cols={2}>
  <Card title="Solution Design" href="/academy/solution-design">
    Click here to learn about common integration workflows for different use cases and requirements.
  </Card>

  <Card title="Building your integration using the Affinda Integration Agent" href="/academy/integration-agent">
    Click here to learn about connecting Affinda to your system with our no-code integrations agent.
  </Card>
</CardGroup>

## AI Agent Integration Resource

To assist with creating integrations to the Affinda Platform, we've published a comprehensive integration resource designed specifically for AI coding agents (Cursor, Claude, Copilot, etc.)

This single markdown file contains everything an agent needs to build an Affinda integration end-to-end: API basics, authentication, Python & TypeScript clients, structured outputs, webhooks, upload patterns, common errors, and a full map of our documentation

**Two ways to use it:**

* **Direct link:** Ask your agent to read [https://docs.affinda.com/skill.md](https://docs.affinda.com/skill.md) before starting your integration
* **Persistent skill:** Install with `npx skills add affinda/skills` so your agent always has access

This resource enables you to build a working integration without jumping across multiple documentation pages

## 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 certified, SOC 2 compliant, API keys scoped per user, with regional endpoints to keep data where you need it.

<Tip>
  See our [Tutorial: Solution Design ](/academy/solution-design)to learn more about common integration workflows for different use cases and requirements.
</Tip>

## 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 the extraction of structured data from any document type.

## Prerequisites

Before you make your first API call, you'll need to:

1. **Create an Affinda account** and log in to the dashboard.
2. **Generate an API key** (*Settings* → *API Keys*).
3. **Configure a document type** (See our step-by-step tutorial on [Creating a New Model](/academy/model-creation)).
4. **Retrieve the workspace identifier** (*Workspace* → *Workflow* → *Integrations*).

For volume limits and plan tiers, see [Affinda's pricing plans](https://www.affinda.com/pricing-plans).

## Parse your first document

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
  ```

  ```python Python theme={null}
  # !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)
  ```

  ```javascript Node.js theme={null}
  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));
  ```
</CodeGroup>