Election Candidate Reports
|
|
|
|
Description
Five types of candidate reports are available:
-
U.S. House candidates
-
U.S. Senate candidates
-
Gubernatorial candidates
-
Candidates running for President in each state
-
A combined report that includes candidates for all of these offices
Candidates are organized by state in each report. In the Presidential report, a candidate appear multiple times because their ballot status can vary from state to state.
Data Elements
|
|
|
|
These reports are also available in JSON, with the XML version of the report returned by default when you follow the direct link to the report from the report list (for more information, see Election Reports). For brevity, report examples in the online documentation are provided in XML. JSON property names match the names of the XML elements. |
|
|
|
|
NoteThis table describes the XML elements used in the Candidate reports.
|
XML Element |
Description |
|
OfficeCandidates[ByState]year |
The tag used for this report; for example, USHouseCandidates2026, USSenateCandidates2026, GovernorCandidates2026, NationalCandidates2026. |
|
lastupdated |
The date when the report was last updated. |
|
CandidateInformation |
Contains information about the candidate. |
|
StateNumber |
The state ID that corresponds with race data. |
|
State |
The two-character state postal code. |
|
OfficeID |
The unique office type ID associated with race data: P (President), G (Governor), S (U.S. Senate) or H (U.S. House). |
|
Office |
The name of the office the candidate is running for (President, Governor, U.S. Senate or U.S. House). |
|
Senate_Class |
(For current U.S. Senators only) The Senate class to which the senator belongs; for example, Class II. |
|
Seat |
(For U.S. House candidates only) The district number. |
|
Primary_Caucus_Date |
(For Presidential candidates only) The date of the state primary or caucus event in MM/DD/YYYY format. |
|
State_Primary_Date |
(For other candidates) The date of the state primary event in MM/DD/YYYY format. |
|
Runoff_Date |
(For U.S. House/Senate runoff and potential runoff candidates only) The runoff election date in MM/DD/YYYY format. |
|
Special_Primary_Date |
The special primary date, where applicable, in MM/DD/YYYY format. |
|
Special_General_Date |
The special general election date, where applicable, in MM/DD/YYYY format. |
|
Special_Runoff_Date |
The special runoff election date, where applicable, in MM/DD/YYYY format. |
|
PolID |
The unique National Politician ID across all states and races. Before 2026, this was the NPID field. |
|
Party |
The candidate's party affiliation, listed as an abbreviation (for example, Dem, GOP, Lib). |
|
Candidate_Name |
The candidate's full name, including nicknames or suffixes; for example, Charles "Wally" Coppock or Joe Edwards Collins, III. |
|
First_Name |
The candidate's first name. |
|
Last_Name |
The candidate's last name. |
|
UncontestedPrimary |
Indicates whether the candidate is uncontested in the primary (Yes/No). |
|
UncontestedGE |
Indicates whether the candidate is uncontested in the general election (Yes/No). |
|
FilingStartDate |
The filing start date in MM/DD/YYYY format. |
|
FilingDeadline |
The filing deadline date in MM/DD/YYYY format. |
|
Status |
Indicates the candidate’s status; for example, whether they are on the ballot, qualified for the general election, lost the primary or are in a runoff. |
|
Incumbent |
Indicates that the candidate is an incumbent. Possible value is yes. |
|
Incumbent_Running |
(For incumbents only) Indicates whether the incumbent is running for re-election. Possible values are yes and no. |
|
Dropout_Date |
(For Presidential candidates only) The date when the candidate drops out or suspends their campaign. |
|
Notes |
Any special notes provided about the candidate. |
Examples
Example: U.S. Senate Candidate Report
This XML example shows a partial 2026 U.S. Senate Candidates report.
Example: U.S. House Candidate Report
This XML example shows a partial 2026 U.S. House Candidate report.