Customer Overlays

Define your own document types and field concepts as a versioned Customer Overlay on the Ontology. List and create overlays, then author and publish them.

The Ontology is the document-type taxonomy the platform classifies against: a Talonic-maintained base plus, per organization, an optional Customer Overlay. A Customer Overlay (the customer-ontologies API resource) is a versioned container of custom document types and field concepts specific to your domain. You define the doctypes you care about (a "Lieferschein", a "Rahmenvertrag") and the fields that matter on them, anchor each doctype to a type in the Talonic base, and publish. Publishing projects your authored fields and doctypes into the field registry and the classifier, so extraction and classification start recognizing your vocabulary.

Overlays are versioned with a draft/publish lifecycle. Editing a published overlay auto-forks a new draft, so the published overlay your pipelines read never changes underneath them mid-run. The overlay is additive: an empty or unpublished overlay leaves capture and classification byte-identical to the Talonic-base-only path, so adopting overlays never regresses existing behavior. An organization can run several overlays at once — the classifier and capture read one merged view of every published overlay, so you can split vocabulary by department (a "Logistics" overlay beside a "Contracts" overlay) without them interfering.

The projection is concrete and inspectable: published fields become field-registry rows that are pinned (protected from registry cleanup and outlier grooming) with source: customer_ontology, and published doctypes become document types the classifier assigns on a customer axis that runs alongside the always-on Talonic axis. You can verify both sides through the API — [GET /v1/fields](list-fields) shows the pinned rows, and the [overlay preview endpoint](customer-ontology-mappings) shows exactly the custom doctypes the classifier applies.

curl -s -X POST https://api.talonic.com/v1/customer-ontologies \
  -H "Authorization: Bearer tlnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Logistics","description":"Delivery + freight doctypes"}'

{
  "id": "75feea55-70ef-4fac-92f6-73ef8e7556c1",
  "version": {
    "id": "7c48bade-35ba-4745-95ba-5523728a95be",
    "ontology_id": "75feea55-70ef-4fac-92f6-73ef8e7556c1",
    "version": 1,
    "status": "draft",
    "doctypes": [],
    "fields": [],
    "dirty": true,
    "published_at": null,
    "created_at": "2026-08-29T11:33:31.689Z"
  }
}

Create returns the overlay id together with the full empty draft version row — note that version is an object, not a number. Keep the id; every other overlay call is addressed by it. The list read summarizes each overlay with latest_version as a plain version number and a published_count, so a dashboard can render lifecycle state without fetching each overlay's detail.

A typical adoption path: create an overlay (or [import one top-down](import-customer-ontology)), author its doctypes and fields with PATCH /v1/customer-ontologies/:id, use the [mapping endpoints](customer-ontology-mappings) to anchor each doctype to a type in the Talonic base, then [publish](publish-customer-ontology). From that point, newly ingested documents can classify under your custom doctypes and extraction targets your authored fields. Documents processed before the publish are not retroactively re-classified — the overlay applies from publish time forward.