API

Public, versioned endpoints for candidate, race, office, jurisdiction, county source, and metadata records. The public API is designed for neutral client use across web, Apple, and future Android surfaces.

OpenAPI JSON

Public Contract

Public responses omit address fields, raw source payloads, source snapshots, and admin notes.
Candidate and race DTOs are platform-neutral for web, Apple, and future Android clients.
County-source records take public precedence over matching state-source county records.
Displayed party/status values may use field-level attribution from a matched lower-priority official source when the primary public filing omits that field.
UNKNOWN party/status/jurisdiction enum values mean the displayed public source did not provide the field and no matched official source supplied it; clients should label these as not listed by source or source unavailable.
WRITE_IN is exposed through ballotDesignation, not party affiliation, and only when an official source supplies a write-in/WRI value.
Routine API consumers should pull after the published refresh window.
Public candidate, race, office, jurisdiction, county, and metadata endpoints remain free public surfaces.
Paid API access, if added later, must not change candidate visibility, ordering, attribution, or public search access.

Freshness

Use /api/v1/metadata/data-refresh to read the current refresh policy, latest ingestion timestamps, and recommended consumer pull time. Routine pulls should run after 7:15 AM Eastern Time.

Source Precedence

County Supervisor of Elections records are primary for county-level filings when a confirmed county record matches a state county record. State records remain primary for state and federal races.

Candidate Name Search

The candidates q parameter searches public candidate names by normalized tokens, so first-last, last-first, and partial-token searches can match the same source-backed candidate row.

Source-Missing Fields

UNKNOWN party, status, or jurisdiction values should be displayed as not listed by source or source unavailable. Do not treat them as no party affiliation, nonpartisan race, write-in, withdrawn, or any other value unless an official source supplies that field. Official write-in/WRI values appear as ballotDesignation=WRITE_IN, separate from party affiliation. UNKNOWN office type remains an operator review issue because it can misplace races.

Privacy Boundary

Public DTOs intentionally omit address fields, suppressed address flags, raw source payloads, source snapshots, admin notes, and private review metadata.

Neutrality

The public API does not expose paid placement, sponsored ranking, candidate boost, paid verification, endorsements, ideology matching, donations, messaging, comments, or social features.

Example Queries

Examples use public endpoints and include pagination where list results are returned.

County candidate search

/api/v1/candidates?jurisdictionLevel=COUNTY&county=Orange&page=1&pageSize=25

Candidate name search

/api/v1/candidates?q=Akin%20Greyson&page=1&pageSize=25

County race list

/api/v1/races?jurisdictionLevel=COUNTY&county=Orange&page=1&pageSize=25

Office-name race search

/api/v1/races?office=School%20Board&page=1&pageSize=25

Refresh metadata

/api/v1/metadata/data-refresh

Search Parameters

Blank parameters are treated as omitted. County filters scope results to county-level records.

Candidate Search /api/v1/candidates

q
electionYear
officeType
officeId
office
county
party
status
sourceType
jurisdictionLevel
sort
direction
page
pageSize

Race Search /api/v1/races

electionYear
county
officeType
office
jurisdictionLevel
page
pageSize

Endpoint Reference

Method	Path	Purpose
GET	/api/v1/candidates	Paginated public candidate filing search.
GET	/api/v1/candidates/{id}	One public candidate filing profile.
GET	/api/v1/races	Paginated public race list with public candidate counts.
GET	/api/v1/races/{id}	One public race with attached public candidate filings.
GET	/api/v1/offices	Public offices with at least one public filing.
GET	/api/v1/jurisdictions	Public jurisdictions with at least one public filing.
GET	/api/v1/counties	County source mapping, freshness, and public filing counts.
GET	/api/v1/metadata/data-refresh	Published refresh schedule and latest ingestion metadata.
GET	/api/v1/metadata/election-years	Election years available in public records.
GET	/api/v1/metadata/statuses	Supported normalized candidate statuses.
GET	/api/v1/metadata/office-types	Supported public office type filters.