> ## 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.

# 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>
  The Affinda Agent helps teams quickly integrate with 1,000s of systems. See our [Tutorial: Creating your integration with the Affinda Agent](/handbook/agent-integrations) 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 with the Affinda Agent" href="/handbook/agent-integrations">
    Click here to learn about connecting Affinda to your system with our no-code integrations built using the Affinda 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*).

<Note>
  API base URL

  Use the base URL for the region where you created your account:

  * **AU (Global):** `https://api.affinda.com`
  * **US:** `https://api.us1.affinda.com`
  * **EU:** `https://api.eu1.affinda.com`

  Your API key only works against the instance where it was generated. If you're unsure, check the URL of the app you signed into.
</Note>

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..."
  export AFFINDA_API_BASE="https://api.affinda.com"   # AU (Global). Use https://api.us1.affinda.com for US or https://api.eu1.affinda.com for EU.

  # 2. Upload a document and wait for processing to finish
  curl -X POST $AFFINDA_API_BASE/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 file you want to parse

  # Use the base URL for your region:
  #   AU (Global): https://api.affinda.com
  #   US:          https://api.us1.affinda.com
  #   EU:          https://api.eu1.affinda.com
  API_BASE = "https://api.affinda.com"

  # Set up the client
  credential = TokenCredential(token=API_KEY)
  client = AffindaAPI(credential=credential, endpoint=API_BASE)

  # 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";

  // Use the base URL for your region:
  //   AU (Global): https://api.affinda.com
  //   US:          https://api.us1.affinda.com
  //   EU:          https://api.eu1.affinda.com
  const API_BASE = "https://api.affinda.com";

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

  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>