Quickstart

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

1. Get a key

Go to app.talonic.com/settings/api-keys and create an API key. Every key starts with tlnc_; the full secret is shown once, when you create it.

Set it as an environment variable:

export TALONIC_API_KEY="tlnc_0123456789abcdef0123456789abcdef"

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": "d1a2b3c4-5678-9abc-def0-1234567890ab",
  "request_id": "req_x7y8z9a0b1c2d3e4",
  "status": "complete",
  "document": {
    "id": "3f8c1d2e-9a4b-4c5d-8e6f-7a0b1c2d3e4f",
    "filename": "invoice.pdf",
    "pages": 2,
    "type_detected": "Invoice",
    "language_detected": "de"
  },
  "data": {
    "vendor_name": "Steinbach Energie AG",
    "total_amount": 14250.00,
    "due_date": "2026-06-15"
  },
  "schema": { "source": "auto" },
  "confidence": {
    "overall": 0.94,
    "fields": {
      "vendor_name": 0.97,
      "total_amount": 0.94,
      "due_date": 0.91
    }
  },
  "processing": {
    "duration_ms": 3420,
    "pages_processed": 2,
    "region": "eu-west"
  }
}

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": "Steinbach" }
    ],
    "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