Open specification · CC BY 4.0
Receipt Format v1
A receipt is a dated, source-linked, reproducible record of what official sources printed for one name and its official keys. This page is the specification any auditor, software vendor or agency can implement and test against. It is not a product; the reference implementation is /screening.
Version 1.0 · published · published 2026-06-01 · CC BY 4.0 — anyone may implement, cite or extend it; attribution to the specification, not to any product
Schema: https://alphacovenantholdings.com/api/spec/receipt/v1/schema.json
Conformance endpoint: POST https://alphacovenantholdings.com/api/spec/receipt/v1/conform with { "receipt": {...} }
Conformance levels — A: schema valid + hash matches + absence rule + verdict rule. B: A + linkage rule on every edge + provenance on every file check.
The six rules
- Hash rule
- Take the receipt exactly as served in JSON (dates already ISO-8601 strings), remove the sha256 field, serialise with keys sorted, default separators (', ' and ': '), non-ASCII escaped (Python json.dumps(obj, sort_keys=True)), UTF-8 encode, SHA-256. The `receipt_registry` field added after issue is not part of the hashed receipt.
- Matching rule
- A row is on a receipt only if the source printed the exact official key supplied (UEI, NPI, EIN, CIK, CCN, registry number) or the exact printed name after whitespace collapse and case folding. No fuzzy, phonetic, partial or owner/affiliate matching.
- Absence rule
- A source that was not read is listed in did_not_answer and its check carries state 'did_not_answer' and count null. 'No record' may only be stated for a source that answered.
- Verdict rule
- A conforming receipt contains no score, rating, risk label, clearance, compliance badge, signal, anomaly or fraud statement. Sources' own published ratings may be printed if attributed to the source.
- Linkage rule
- Every crosswalk edge cites the one official row that prints both identifiers together. Edges are never derived from name similarity, shared address, ownership or co-occurrence.
- Provenance rule
- Every file-based check names the file, its SHA-256, its row count and read time; every API-based check names the endpoint's publisher and the read time; rescued or third-party-hosted copies state the custody chain and the originating publisher's current record.
Fields
| Field | Required | Meaning |
|---|---|---|
| name | yes | the name exactly as the requester supplied it |
| uei | no | ^[A-Z0-9]{12}$ |
| npi | no | ^[0-9]{10}$ |
| ein | no | ^[0-9]{2}-[0-9]{7}$ |
| cik | no | ^[0-9]{1,10}$ |
| ccn | no | ^[0-9A-Z]{6,10}$ |
| checked_at | yes | UTC read time of the receipt |
| method | yes | versioned method string; must state exact-key / exact-printed-name matching and that nothing is inferred |
| what_this_is | no | |
| duty | no | |
| reference | no | requester-supplied award/PIID/invoice reference bound into the hash, printed and never interpreted |
| checks | yes | |
| did_not_answer | yes | ids of every check or block that was not read; a receipt with an empty list read everything it names |
| crosswalk | no | identifier edges; each edge must come from one official row that prints both values; no name-based or inferred linkage |
| source_integrity | no | |
| identity | no | |
| sha256 | yes | SHA-256 of canonical JSON (sorted keys, str() for non-JSON values, UTF-8) of the receipt without this field |
Each item of checks carries: id — stable check identifier (leie, sam, ofac, state_medicaid, usaspending, fac, ocr, echo, csl, fda, irs, sec); source — the official file or API read, named as its publisher names it; state — ok = the source answered; did_not_answer = the source was not read and nothing stands in for it; summary — one sentence of source facts; never a verdict; count — rows the source printed for the exact key or exact printed name; null when not read; file — file metadata when a file was read: a key ending in sha256 with the 64-hex digest (at any depth), rows, fetched_at, source url; entries — the source's rows as printed, at most ten; official_lookup — where a reader repeats the check at the publisher; matched_by — 'exact key' names the key (UEI, NPI, EIN, CIK, CCN) or 'exact printed name'
Check a receipt
Paste the JSON of any receipt (ours or another implementer's). The check validates the schema, recomputes the hash, and applies the absence, verdict, linkage and provenance rules. Nothing is stored.
Related: Verification Integrity Standard · Receipt Registry · Corrections ledger · Methodology