Quickstart

Get a key, extract your first document, and receive structured data with per-cell confidence — in under 60 seconds.

1. Get a key

Go to app.talonic.com/settings/api-keys and create an API key. Production keys start with tlnc_live_, sandbox keys with tlnc_test_.

Set it as an environment variable:

export TALONIC_API_KEY="tlnc_live_abc123def456"

2. First extraction (60 seconds)

Send any document to POST /v1/extract. No schema required — Talonic discovers every field automatically (Mode 1).

curl -X POST https://api.talonic.com/v1/extract \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -F "file=@invoice.pdf"

Response (200 for ≤5 pages, 202 async with poll_url for larger documents):

{
  "extraction_id": "ext_9f2a...",
  "document_id": "doc_4b1c...",
  "fields": {
    "vendor_name": {
      "value": "GETEC AG",
      "confidence": 0.97,
      "phase": 1,
      "source": { "page": 1, "region": "top-right" }
    },
    "total_amount": {
      "value": 14250.00,
      "confidence": 0.94,
      "phase": 2,
      "source": { "page": 2, "region": "bottom-table" }
    },
    "due_date": {
      "value": "2026-06-15",
      "confidence": 0.91,
      "phase": 1,
      "source": { "page": 1, "region": "header" }
    }
  }
}

3. Pick your mode

Mode 1 — Extract everything

No schema. AI discovers every field. Best for prototyping or unknown document types. This is what you just ran above.

Mode 2 — Extract a defined shape

Pass a schema to get exactly the fields you need. Three formats accepted: JSON Schema, simplified fields, or a flat key-type map.

curl -X POST https://api.talonic.com/v1/extract \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -F "file=@invoice.pdf" \
  -F 'schema={"vendor_name":"string","total_amount":"number","due_date":"date"}'

Mode 3 — Query without re-extracting

Documents already ingested? Query the Field Registry directly. Zero AI calls, zero re-extraction.

curl -X POST https://api.talonic.com/v1/documents/filter \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "fieldId": "vendor_name", "operator": "contains", "value": "GETEC" }
    ],
    "limit": 10
  }'

Read more about the three modes.

4. Receive results

Sync: Documents ≤5 pages return a 200 with the full result in the response body.

Async: Larger documents return 202 with a poll_url. Or set up a webhook to receive results automatically:

curl -X POST https://api.talonic.com/v1/webhooks \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhook",
    "events": ["extraction.completed"]
  }'

5. Track cost

Every sync response includes cost headers:

X-Talonic-Cost-Credits: 150
X-Talonic-Cost-EUR: 0.15
X-Talonic-Balance-Credits: 4850

Check balance and runway programmatically:

curl https://api.talonic.com/v1/credits/balance \
  -H "Authorization: Bearer $TALONIC_API_KEY"

6. What's next