Trigger Package Run

Trigger a matching package run via API: score extracted rows keyed by document type against a package config and get the aggregated verdict synchronously.

Trigger a package run. You supply the extracted rows grouped by document type and the package config to score them against. The engine feeds each document type's rows through that type's matching config, then aggregates the per-type results into a single package verdict. Execution is inline and synchronous, so the returned run is already terminal.

The input_documents field is a map keyed by document type. Each value is an array of input rows for that type, and each row carries the document_id it came from, the extraction_row_id, and the values to score against reference data. The keys must line up with the document_types in the referenced package config.

The run status aggregates the document-type results. passed means the package satisfied its pass criteria. failed means a hard miss: a required type absent, unmatched, or below the min_confidence floor, or a supplied expected type that did not match. review means the package needs a human look without failing — an expected type was missing from the input, or a review-grade match occurred where the criteria allow it. error means execution itself failed; the run row is still persisted with its error message. Each entry in document_results reports its own status, confidence, and whether the document was found.

Two per-type details matter when reading document_results. The entry's status reflects the best row of that type (with several invoices, one good match carries the slot), while confidence is the average best-candidate confidence across the type's rows, rounded to three decimals — so a slot can read "matched" with a modest confidence when weaker siblings drag the average down. And matching_run_id is always null: package execution scores the rows inline rather than minting standalone /v1/matching runs, so the per-type audit trail lives entirely in this run's document_results.

Response

curl -X POST https://api.talonic.com/v1/matching/packages/runs \
  -H "Authorization: Bearer tlnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d @package-run.json

{
  "package_config_id": "4f2a9c1e-8b3d-47e6-9a05-c7d1e2f3a4b5",
  "input_documents": {
    "invoice": [
      {
        "document_id": "b8b00d51-eecc-49b3-affc-89fee95b9518",
        "extraction_row_id": "row_1",
        "values": { "booking_reference": "ABC1234567", "total": 4250.0 }
      }
    ],
    "delivery_note": [
      {
        "document_id": "c9a11e62-fdd0-4a21-b00d-9a0e81f6c2d3",
        "extraction_row_id": "row_1",
        "values": { "booking_reference": "ABC1234567", "carrier": "Acme Freight" }
      }
    ]
  }
}

{
  "id": "8d7e6f50-4c3b-42a1-b0e9-d8c7b6a59483",
  "package_config_id": "4f2a9c1e-8b3d-47e6-9a05-c7d1e2f3a4b5",
  "status": "passed",
  "document_results": [
    {
      "document_type": "invoice",
      "matching_config_id": "1a2b3c4d-5e6f-4781-92a3-b4c5d6e7f809",
      "matching_run_id": null,
      "presence": "required",
      "document_found": true,
      "status": "matched",
      "confidence": 0.934
    },
    {
      "document_type": "delivery_note",
      "matching_config_id": "2b3c4d5e-6f70-4192-a3b4-c5d6e7f8091a",
      "matching_run_id": null,
      "presence": "expected",
      "document_found": true,
      "status": "matched",
      "confidence": 0.881
    }
  ],
  "input_documents": {
    "invoice": ["b8b00d51-eecc-49b3-affc-89fee95b9518"],
    "delivery_note": ["c9a11e62-fdd0-4a21-b00d-9a0e81f6c2d3"]
  },
  "error": null,
  "created_at": "2024-09-14T10:40:00.000Z",
  "completed_at": "2024-09-14T10:40:03.000Z",
  "links": {
    "self": "/v1/matching/packages/runs/8d7e6f50-4c3b-42a1-b0e9-d8c7b6a59483",
    "config": "/v1/matching/packages/configs/4f2a9c1e-8b3d-47e6-9a05-c7d1e2f3a4b5"
  }
}

Read the package verdict from status, then drill into document_results to see which type drove it. A no_match on a required type fails the package, a review on an expected type routes to review when the config allows it, and a skipped entry means no document of that type was supplied for an optional slot. A slot whose per-type matching config no longer exists reports no_match with error: "Matching config not found" instead of failing the whole call, so a stale slot degrades that type rather than erroring the run.

Errors