Provenance

Every calculation carries a record object describing what produced it. It is present both on creation and on retrieval, so the two bodies are the same document.

{
  "id": "01HX9B2KM3V4W5X6Y7Z8A9B0CD",
  "record": {
    "stored": true,
    "rule_fingerprint": "sha256:b90834cebdc4224c3...",
    "engine_version": "9f2c1ab",
    "schema_version": 1,
    "content_digest": "sha256:41d0ae9f77b2c518...",
    "batch_id": null,
    "supersedes_id": null,
    "metadata": { "run": "nomina-2026-09-q1" }
  }
}

Field	What it is
`stored`	Always `true`. A calculation that could not be stored is not returned at all
`rule_fingerprint`	SHA-256 of the rule file that produced these amounts
`engine_version`	Build of the calculation engine, as a git SHA
`schema_version`	Shape of this stored response. An old record is returned in the shape it was written in, never upgraded in place
`content_digest`	SHA-256 over the canonical form of this response
`batch_id`	The batch this row belonged to, if any
`supersedes_id`	The calculation this one replaces, if it is a correction
`metadata`	Your own labels, echoed back

Why a fingerprint and not a version label

A version label is written by one person and forgotten by the next. Under the single label version: "2026.1", four different contents of rules/MX/2026/ordinario.yml have shipped — and five for Colombia, seven for Chile, five for Argentina. At least two of those changes moved amounts. A label that four different rule sets have shared is not an identity. The fingerprint is the SHA-256 of the rule file itself, so two calculations carrying the same fingerprint ran against byte-identical rules. That is a claim you can check.

Verifying a calculation later

Keep the content_digest you received. Fetch the calculation any time afterwards and compare: if the digests match, what you are being handed now is what you were handed then.

import httpx

original_digest = "sha256:41d0ae9f77b2c518..."  # kept from the original response

fetched = httpx.get(
    "https://api.clevis.dev/v1/payroll/calculations/01HX9B2KM3V4W5X6Y7Z8A9B0CD",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
).json()

assert fetched["record"]["content_digest"] == original_digest

const originalDigest = "sha256:41d0ae9f77b2c518..."; // kept from the original response

const fetched = await fetch(
  "https://api.clevis.dev/v1/payroll/calculations/01HX9B2KM3V4W5X6Y7Z8A9B0CD",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
).then((r) => r.json());

console.assert(fetched.record.content_digest === originalDigest);

Labelling calculations with metadata

options.metadata accepts up to 20 keys, values up to 500 characters. Use it for a payroll run id, a cost centre, a "test" marker — anything you will want to filter or recognise later. It is echoed back in record.metadata.

{
  "country": "CO",
  "scheme": "ordinario",
  "year": 2026,
  "options": {
    "metadata": {
      "run": "nomina-2026-09-q1",
      "cost_center": "ops-bogota"
    }
  }
}

Never put personal data in metadata. It is stored verbatim.

What provenance does not give you

Provenance lets you prove which rules ran. It does not let you re-run them.

Get Started

Countries

Calculations

Payouts

Guides

Why a fingerprint and not a version label

Verifying a calculation later

Labelling calculations with metadata

What provenance does not give you

​Why a fingerprint and not a version label

​Verifying a calculation later

​Labelling calculations with metadata

​What provenance does not give you

Why a fingerprint and not a version label

Verifying a calculation later

Labelling calculations with metadata

What provenance does not give you