Trigger Package Run

Trigger a matching package run: score extracted rows keyed by document type against a package config and return 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 required type missed or fell below the confidence floor, review means an expected type was soft-missed under a config that allows review, and error means execution itself failed. Each entry in document_results reports its own status, confidence, and whether the document was found.

Response

{
  "package_config_id": "pkg_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "input_documents": {
    "invoice": [
      {
        "document_id": "doc_uuid_1",
        "extraction_row_id": "row_1",
        "values": { "booking_reference": "ABC1234567", "total": 4250.0 }
      }
    ],
    "delivery_note": [
      {
        "document_id": "doc_uuid_2",
        "extraction_row_id": "row_1",
        "values": { "booking_reference": "ABC1234567", "carrier": "Acme Freight" }
      }
    ]
  }
}

{
  "id": "run_b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "package_config_id": "pkg_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "passed",
  "document_results": [
    {
      "document_type": "invoice",
      "matching_config_id": "mc_uuid_1",
      "matching_run_id": "mr_uuid_1",
      "presence": "required",
      "document_found": true,
      "status": "matched",
      "confidence": 0.93
    },
    {
      "document_type": "delivery_note",
      "matching_config_id": "mc_uuid_2",
      "matching_run_id": "mr_uuid_2",
      "presence": "expected",
      "document_found": true,
      "status": "matched",
      "confidence": 0.88
    }
  ],
  "input_documents": {
    "invoice": ["doc_uuid_1"],
    "delivery_note": ["doc_uuid_2"]
  },
  "error": null,
  "created_at": "2024-09-14T10:40:00.000Z",
  "completed_at": "2024-09-14T10:40:03.000Z",
  "links": {
    "self": "/v1/matching/packages/runs/run_b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "config": "/v1/matching/packages/configs/pkg_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

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. The matching_run_id on each entry links back to the underlying single-document matching run for that type.

Errors