Reference

Provenance and confidence

Every value in the graph can name the document it came from and how much we trust it, which is what lets you defend a number to your own customers.

How an assertion is recorded

Whenever anything writes a field it also writes a provenance row pointing at the source document, and nothing enters the graph uncited, including hand-curated data.

GET /v1/candidacies/{slug}/provenance

{
  "slug": "candidacy:az-us-house-03-2026-general-jane-doe",
  "fields": [
    {
      "field": "filing_status",
      "value": "qualified",
      "extracted_value": "QUALIFIED",
      "extraction_method": "structured-feed",
      "source_status": "authoritative",
      "confidence": 0.95,
      "artifact": {
        "slug": "artifact:az-sos-candidate-list-2026-08-20",
        "name": "Arizona Secretary of State 2026 candidate list",
        "url": "https://azsos.gov/…",
        "retrieved_at": "2026-08-20T06:02:11Z",
        "content_hash": "sha256:9f2c…"
      }
    }
  ]
}

The extracted_value field holds the raw text the source actually gave us alongside the value we normalised it to, while extraction_method records how it was obtained, whether from a structured feed, a parsed document or assisted research. If you disagree with a normalisation you can see exactly what it came from, and if you distrust a method you can filter it out entirely. Each document also carries a checksum of the bytes we retrieved, so you can confirm the source has not changed underneath a claim since we read it.

Reading confidence

Confidence describes the source rather than guessing about the world, so pick a floor that matches your risk tolerance and apply it everywhere.

Score	Origin	Typical use
1.00	Hand-curated against primary sources	Anything
0.95	Official structured feed from a state, the FEC or the Census	Anything
0.90	Authoritative registry, name-matched	Anything
0.85	Derived from our own product data	Display, with review for high-stakes use
0.70	Extracted from a published filing list	Display, review before outbound contact
0.60	Machine research against cited web sources	Leads and discovery, not assertions of record

Filtering by trust

MATCH (c:Candidacy)
WHERE c.confidence >= 0.85 AND c.status <> 'disputed'
RETURN c.slug, c.name

Time travel

Assertions are superseded rather than overwritten, with valid_from and valid_to bounding the window each one held for while created_at and updated_at record when we knew it. That lets you ask two genuinely different questions, namely what was true on a past date and what we believed on a past date. Auditing a decision your system made last quarter requires the second of those, and almost no election data source can answer it.

As-of queries

GET /v1/contests?state=AZ&as_of=2026-03-01

Disputes are visible rather than hidden. When two sources contradict each other and neither is more authoritative, the node is marked disputed and both provenance rows are kept, leaving the judgement to you rather than quietly picking a side.