Ground Truth Entries

List, add, or delete ground truth entries with the /v1/quality/ground-truth entries endpoints. Each entry pairs a document with its verified field values.

Ground truth entries are the individual verified data points inside a ground truth dataset: each entry pairs a document_id with the expected_data a correct extraction should produce for that document. Use the entries endpoints to list, add, and delete them, building the gold standard that benchmark runs score extraction accuracy against.

The typical workflow is: extract a set of representative documents, manually verify the correct value for each schema field, then POST one entry per document. When a benchmark runs, it compares the extracted value for each field against the matching key in expected_data and reports per-field accuracy. Fetch candidate document ids from [GET /v1/documents](list-documents) — document_id must be an existing document in your workspace, not an arbitrary identifier.

expected_data is deliberately free-form JSON: any shape is accepted at write time, so you can store nested structures or extra keys for your own bookkeeping. Only keys that match your schema's field names participate in benchmark comparison; everything else is carried along untouched. notes is a free-text field for reviewer context — ambiguities, edge cases, or why a particular value was chosen — and is returned verbatim on every read.

The entries list is returned in full, oldest-first, with no pagination parameters — datasets are expected to hold tens to low hundreds of entries, not millions. Reads are filtered by document visibility: entries whose documents are hidden from your API key's minting user by source IAM rules are omitted. Writes require the write scope; the dataset itself is always tenant-checked first, so a foreign datasetId returns 404 before any entry is touched.

Response (List entries)

{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "document_id": "doc_abc123",
      "expected_data": {
        "vendor_name": "Acme Corp",
        "total_amount": 14250.00,
        "invoice_number": "INV-2024-0847"
      },
      "notes": null,
      "created_at": "2024-09-05T12:00:00.000Z"
    }
  ]
}

curl -X POST https://api.talonic.com/v1/quality/ground-truth/a1b2c3d4-e5f6-7890-abcd-ef1234567890/entries \
  -H "Authorization: Bearer tlnc_..." \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "b8b00d51-eecc-49b3-affc-89fee95b9518",
    "expected_data": {
      "vendor_name": "Acme Corp",
      "total_amount": 14250.00,
      "invoice_number": "INV-2024-0847"
    },
    "notes": "Verified against the signed original"
  }'

Response (Add entry)

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "document_id": "doc_abc123",
  "expected_data": {
    "vendor_name": "Acme Corp",
    "total_amount": 14250.00,
    "invoice_number": "INV-2024-0847"
  },
  "notes": null,
  "created_at": "2024-09-05T12:00:00.000Z"
}

Response (Delete entry)

{ "deleted": true }

Errors