Import an Overlay

Import a complete Customer Overlay top-down: doctypes and fields in one call, optionally published immediately. Blank anchors auto-map to Talonic types.

Import is the fast path for standing up an overlay from a definition you already have. You post the whole thing — name, doctypes, and fields — in one call, and optionally publish it immediately with publish: true. Any doctype you leave without a maps_to anchor is auto-mapped to the best-matching Talonic type by embedding similarity before it is saved, so you do not have to hand-anchor every doctype.

Import matches the overlay by name: if no overlay with the posted name exists, one is created; if one exists, its draft is replaced with the posted definition. That makes the call idempotent authoring, not a merge — the posted doctypes and fields become the draft wholesale, and anything you omit is gone from the draft. Keep your overlay definition in version control and re-import it on change, the same way you would apply configuration as code. Renaming the overlay in your definition therefore creates a second overlay rather than renaming the first — rename via PATCH /v1/customer-ontologies/:id instead.

Each doctype carries a key (max 128 chars), a name (max 256), an optional category, an optional description, classification signals, and the maps_to Talonic anchor. signals is an object, not a bare list: { "keywords": [...], "filename_patterns": [...] } — keywords bias classification toward the doctype when they appear in the document, filename patterns match on the ingested filename. Each field carries a key plus optional canonical_name, display_name, data_type, description, synonyms, a doctype_scope (a doctype key, or null/empty/* for a global field applied to every document), required, format, enum_values, and examples.

The response is the same shape as [GET /v1/customer-ontologies/:id](get-customer-ontology): the overlay header with latest_version embedded as a full version object, so you can confirm in one round trip what was saved and — when you passed publish: true — that status is published and each field has its derived english_key.

curl -s -X POST https://api.talonic.com/v1/customer-ontologies/import \
  -H "Authorization: Bearer tlnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Logistics",
    "description": "Delivery + freight doctypes",
    "publish": true,
    "doctypes": [
      {
        "key": "delivery_note",
        "name": "Lieferschein",
        "category": "logistics",
        "signals": { "keywords": ["Lieferschein", "Warenausgang"] }
      }
    ],
    "fields": [
      { "key": "delivery_date", "display_name": "Delivery Date", "data_type": "date", "doctype_scope": "delivery_note" }
    ]
  }'

{
  "id": "75feea55-70ef-4fac-92f6-73ef8e7556c1",
  "name": "Logistics",
  "description": "Delivery + freight doctypes",
  "status": "published",
  "current_version_id": "7c48bade-35ba-4745-95ba-5523728a95be",
  "created_at": "2026-08-29T11:33:31.689Z",
  "updated_at": "2026-08-29T11:33:41.428Z",
  "latest_version": {
    "id": "7c48bade-35ba-4745-95ba-5523728a95be",
    "version": 1,
    "status": "published",
    "doctypes": [
      {
        "key": "delivery_note",
        "name": "Lieferschein",
        "maps_to": "delivery_note",
        "signals": { "keywords": ["Lieferschein", "Warenausgang"] },
        "category": "logistics"
      }
    ],
    "fields": [
      {
        "key": "delivery_date",
        "data_type": "date",
        "display_name": "Delivery Date",
        "doctype_scope": "delivery_note",
        "english_key": "delivery_date",
        "english_key_src": "delivery_date",
        "english_key_via": "llm"
      }
    ],
    "dirty": false,
    "published_at": "2026-08-29T11:33:41.428Z",
    "created_at": "2026-08-29T11:33:31.689Z"
  }
}