Candidate
A person on the ballot, with the contests they run in, how to reach them, campaign finance and where they stand on issues.
- Returned by
GET /v1/candidates,GET /v1/candidates/{id}- Found in
- Choice (
candidate) - Shapes
- The full record is in GET /v1/candidates/{id}. The shorter forms in GET /v1/candidates and a choice’s candidate leave some fields out; a field that isn’t in every form says where it is.
How it connects
- One candidate record per person: someone who runs in several elections has one
idand a contest entry for each. - Each contest entry names the choice the candidate appears as, its district and election, and the endorsements they received there.
issue_positionsare the same records asGET /v1/issue-positions?candidates={id}.
Good to know
nameis split fromfull_name, so a part isnullwhen the name has none.ids.fecandfinanceare for federal candidates only;ids.bioguideonly for people who have served in Congress.contactis filled from public sources (Wikidata, Open States, FEC filings, official candidate lists and the campaign’s own site) and is empty where we have nothing yet. Each detail’s source is incontact.sources.issue_positionsis empty where we have none yet. Positions are never inferred from party or endorsements.
Fields
| Field | Type | Meaning | Example |
|---|---|---|---|
id | integer | Candidate id. | 5 |
full_name | string | Full name. | Xavier Becerra |
name | object | The candidate’s name in parts, split from the full name. | — |
name.given | stringor null | Given (first) name. | Xavier |
name.middle | stringor null | Middle name(s) or initials. | Diaz |
name.family | stringor null | Family (last) name, with particles such as “de la” or “Van”. | Becerra |
name.suffix | stringor null | Jr., Sr., II, III, … | — |
name.nickname | stringor null | The name in quotes or parentheses on the ballot, e.g. “Bobby”. | Hov |
website_url | stringor nullURL | Campaign website. | — |
photo_url | stringor nullURL | A photo of the candidate. | — |
incumbent | booleanor null | Holds the seat now: true or false where we know, null where we don’t yet.Not in a choice’s candidate. | true |
ids | object | Ids in other public systems. | — |
ids.fec | stringor null | Federal Election Commission candidate id (U.S. House and Senate candidates). | H6CA11268 |
ids.bioguide | stringor null | Congressional Biographical Directory id (sitting members of Congress). | M001225 |
contact | object | How to reach the candidate: website and social accounts from Wikidata (CC0), an incumbent’s official contacts (Open States, CC0), the campaign committee’s address from its FEC filing, what official candidate lists and state campaign-finance filings publish, and what the campaign publishes on its own site, each with its source. Empty where we have nothing yet. | — |
contact.website | stringor nullURL | Website, from Wikidata or (for an incumbent) the official site. | https://www.conniechansf.com |
contact.email | stringor nullEmail address | Email: an incumbent’s official address, or what the campaign publishes. | info@conniechansf.com |
contact.phone | stringor null | Phone: an incumbent’s office phone, or what the campaign publishes. | (415) 340-0168 |
contact.mailing_address | stringor null | Campaign committee mailing address, from its FEC filing. | 330 N Brand Blvd Ste 700, Glendale, CA 91203 |
contact.social | object | Social accounts, from Wikidata, an incumbent’s official accounts, or the campaign’s own website. Only keys we found are present. | — |
contact.social.facebook | stringoptionalURL | Facebook page. | https://facebook.com/conniechansanfrancisco |
contact.social.x | stringoptionalURL | X (Twitter) account. | https://x.com/conniechansf |
contact.social.instagram | stringoptionalURL | Instagram account. | https://instagram.com/connie_chan_sf |
contact.social.youtube | stringoptionalURL | YouTube channel. | https://www.youtube.com/@ConnieChanSF |
contact.social.linkedin | stringoptionalURL | LinkedIn page. | https://www.linkedin.com/in/scott-wiener-936760 |
contact.social.tiktok | stringoptionalURL | TikTok account. | https://tiktok.com/@connie_chan |
contact.social.threads | stringoptionalURL | Threads account. | https://www.threads.net/@scott_wiener |
contact.social.bluesky | stringoptionalURL | Bluesky account. | https://bsky.app/profile/scottwiener.bsky.social |
contact.sources | array of object | Where each contact detail came from. | — |
contact.sources[].url | stringURL | Where we read it. | https://elections.cdn.sos.ca.gov/statewide-elections/2026-general/contact-list.pdf |
contact.sources[].kind | string | wikidata, open_states (the official contacts of an incumbent), fec_filing, official_filing (a state, county or city candidate list or campaign-finance filing) or campaign_website.wikidata, open_states, fec_filing, official_filing, campaign_website meanings | official_filing |
contact.sources[].read_on | stringYYYY-MM-DD | When we read it. | 2026-11-13 |
finance | array of object | FEC campaign finance totals, newest cycle first; empty for candidates without an FEC id.Only in GET /v1/candidates/{id}. | — |
finance[].cycle | integer | Two-year FEC cycle, by its last year: 2026 = 2025–2026.Only in GET /v1/candidates/{id}. | — |
finance[].committee_id | stringor null | Principal campaign committee’s FEC id.Only in GET /v1/candidates/{id}. | — |
finance[].receipts | number | Total receipts, dollars.Only in GET /v1/candidates/{id}. | — |
finance[].disbursements | number | Total disbursements, dollars.Only in GET /v1/candidates/{id}. | — |
finance[].cash_on_hand | number | Cash on hand at coverage_end, dollars.Only in GET /v1/candidates/{id}. | — |
finance[].debts | number | Debts owed by the campaign, dollars.Only in GET /v1/candidates/{id}. | — |
finance[].individual_contributions | numberor null | Contributions from individuals, dollars.Only in GET /v1/candidates/{id}. | — |
finance[].coverage_end | stringor nullYYYY-MM-DD | The date the totals run through.Only in GET /v1/candidates/{id}. | — |
finance[].source_url | stringURL | The FEC page for these totals.Only in GET /v1/candidates/{id}. | — |
contests | array of object | The contests they’re on that you can read, newest election first, each with the endorsements received.Not in a choice’s candidate. | — |
contests[].contest | object | The contest.Not in a choice’s candidate. | — |
contests[].contest.id | integer | Contest id.Not in a choice’s candidate. | 57 |
contests[].contest.title | string | Title as printed on the ballot.Not in a choice’s candidate. | Governor |
contests[].contest.kind | string | candidate or retention.candidate, measure, retention meaningsNot in a choice’s candidate. | candidate |
contests[].contest.vote_method | string | How votes are cast.plurality, multi_seat, ranked_choice, approval, yes_no meaningsNot in a choice’s candidate. | plurality |
contests[].contest.votes_allowed | integeror null | Vote for N.Not in a choice’s candidate. | 1 |
contests[].contest.ranks_allowed | integeror null | Ranked choice: how many choices a voter may rank.Not in a choice’s candidate. | — |
contests[].contest.office | objector null | The office the contest fills.Not in a choice’s candidate. | — |
contests[].contest.office.type | string | The office, normalized across states: us_representative, governor, state_senator, mayor, school_board, trial_court, sheriff, …51 values: meaningsNot in a choice’s candidate. | governor |
contests[].contest.office.level | string | Level of government the office belongs to (state courts are state, whatever district they sit in).federal, state, local meaningsNot in a choice’s candidate. | state |
contests[].contest.office.branch | string | Branch of government.executive, legislative, judicial meaningsNot in a choice’s candidate. | executive |
contests[].contest.race_type | stringor null | regular, special, recall or retention.regular, special, recall, retention meaningsNot in a choice’s candidate. | regular |
contests[].district | object | The district the contest is voted in.Not in a choice’s candidate. | — |
contests[].district.id | integer | District id.Not in a choice’s candidate. | 1 |
contests[].district.ocd_id | stringor null | Open Civic Data division id.Not in a choice’s candidate. | ocd-division/country:us/state:ca |
contests[].district.name | string | District name.Not in a choice’s candidate. | California |
contests[].district.level | string | Level of government.federal, state, county, city, school, special meaningsNot in a choice’s candidate. | state |
contests[].district.state | stringor nullTwo capital letters (USPS code) | USPS state code.Not in a choice’s candidate. | CA |
contests[].election | object | The contest’s election.Not in a choice’s candidate. | — |
contests[].election.id | integer | Election id.Not in a choice’s candidate. | 1 |
contests[].election.slug | string | Election slug.Not in a choice’s candidate. | ca-2026-11-03-general |
contests[].election.name | string | Election name.Not in a choice’s candidate. | California General Election |
contests[].election.date | stringYYYY-MM-DD | Election day.Not in a choice’s candidate. | 2026-11-03 |
contests[].choice | object | The line the candidate appears on in this contest.Not in a choice’s candidate. | — |
contests[].choice.id | integer | Choice id.Not in a choice’s candidate. | 13 |
contests[].choice.label | string | The name as printed.Not in a choice’s candidate. | Xavier Becerra |
contests[].choice.ballot_designation | stringor null | Occupation line printed under the name.Not in a choice’s candidate. | Voting Rights Attorney |
contests[].choice.withdrawn | boolean | Withdrew but still printed.Not in a choice’s candidate. | false |
contests[].choice.party | Partyor null | The party printed beside the name.Not in a choice’s candidate. | — |
contests[].choice.party_label | stringor null | The party text exactly as printed, where it differs.Not in a choice’s candidate. | — |
contests[].choice.result | objector null | The candidate’s votes and whether they won, once the contest has a result.Not in a choice’s candidate. | — |
contests[].choice.result.votes | integeror null | Votes for this choice. null only on a party-reported result, which names a winner without counts.Not in a choice’s candidate. | 8124241 |
contests[].choice.result.vote_pct | numberor null | Share of the contest’s votes, 0 to 100, as the source gives it (three decimals).Not in a choice’s candidate. | 65.728 |
contests[].choice.result.winner | booleanor null | true for a winner (for vote-for-N, each of the N), false for a choice that lost; null when not decided yet or not stated, such as a race headed to a runoff.Not in a choice’s candidate. | true |
contests[].result | Contest resultor null | The contest’s result, once a source has one.Not in a choice’s candidate. | — |
contests[].endorsement_count | integer | Endorsers who endorsed this candidate in this contest.Not in a choice’s candidate. | 50 |
contests[].endorsements | array of Endorsement | Every endorsement they received in this contest, by endorser name.Only in GET /v1/candidates/{id}. | — |
issue_positions | array of Issue position | Where they stand on common issues (GET /v1/issues), in issue order, each with its sources. Empty where we have none yet.Only in GET /v1/candidates/{id}. | — |