Open Inputs and Enrichment

Fill the gaps of a price model with sourced values: set a contract value with its quote, enrich from contract documents, and record how an open input is filled.

A price model is rarely complete after extraction. A value may be printed in an annex, a quantity may be agreed in an offer, an index may be missing for a month. The contract workbook turns each gap into an open input: a question with the ways to answer it. Four routes close those gaps, and none of them invents a number. A contract value is set only together with a quote that occurs in the contract document and prints the value; an enrichment answer counts only when its quote occurs in the document it names; a decision about how an input will be filled never fills a number.

Open inputs are listed in the open array of the workbook (GET /v1/price-baseline/models/{id}/sheets). Each has a stable key (value:<document>:<name>, index:<series> or invoice), a kind (contract_value, index_value, quantity, profile or invoice), the question, and the options that answer it: enter_contract_value, enter_published, from_invoice, request, upload_invoice or assume. An input marked optional improves the result but nothing is missing without it.

curl -X POST "https://api.talonic.com/v1/price-baseline/models/7b1f0a52-3c9d-4e08-a6d4-51c2e8f7b3a9/values" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variable": "AP0", "value": 6.42, "quote": "Der Basis-Arbeitspreis AP0 betraegt 6,42 ct/kWh."}'

Use enrich when a model was corrected by hand and only lacks its identity (contract number, customer, site) and its agreed quantities. It leaves formulas and values alone. The route returns the enriched model with status 201 and answers 502 with a retryable error when the extraction model is unavailable.

curl -X POST "https://api.talonic.com/v1/price-baseline/models/7b1f0a52-3c9d-4e08-a6d4-51c2e8f7b3a9/enrich-documents" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true, "year": 2025}'

{
  "data": {
    "contract_key": "4711",
    "dry_run": true,
    "wanted": 2,
    "documents": [
      { "id": "D1", "filename": "Waermeliefervertrag_4711.pdf" },
      { "id": "D2", "filename": "Angebot_4711_Anlage.pdf" }
    ],
    "values": [
      {
        "item": "I1",
        "kind": "quantity",
        "label": "Vereinbarte Waermemenge",
        "target": "Q",
        "value": 1850000,
        "unit": "kWh",
        "document": "Angebot_4711_Anlage.pdf",
        "document_id": "5e92c8a1-0b37-4d6f-a1c4-7f3d8b2e6091",
        "quote": "Jahreswaermebedarf 1.850.000 kWh",
        "verified": true,
        "applied": false
      }
    ],
    "applied": 0
  }
}

A value counts only when its quote occurs in the document the answer names and prints it, and it never replaces a verified value. With dry_run nothing is saved, so the report shows exactly which values would be written. An answer with verified: false carries a problem that says why the quote failed.

curl -X POST "https://api.talonic.com/v1/price-baseline/models/7b1f0a52-3c9d-4e08-a6d4-51c2e8f7b3a9/decide" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "index:destatis.erdgas.boerse", "choice": "request", "note": "Ask the supplier for the March value."}'