--- title: "GET /v1/candidates/search/" method: GET path: "/v1/candidates/search/" tags: ["candidate"] --- # GET /v1/candidates/search/ `GET /v1/candidates/search/` ## Request - Base URL: `https://api.open.fec.gov` (the document declares no server; this is the origin it was published from) - URL: `https://api.open.fec.gov/v1/candidates/search/` - Auth: API key in header `X-Api-Key` and API key in query parameter `api_key` and API key in query parameter `api_key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Fetch basic information about candidates and their principal committees. Each result reflects a unique FEC candidate ID. That ID is assigned to the candidate for a particular office sought. If a candidate runs for the same office over time, that ID stays the same. If the same person runs for multiple offices — for example, a House candidate runs for a Senate office — that candidate will get a unique ID for each office. The candidate endpoints primarily use data from FEC registration [Form 1](https://www.fec.gov/pdf/forms/fecfrm1.pdf) for committee information and [Form 2](https://www.fec.gov/pdf/forms/fecfrm2.pdf) for candidate information. ## Query parameters - `page` integer - `per_page` integer - `q` string[] - `candidate_id` string[] - `min_first_file_date` string - `max_first_file_date` string - `is_active_candidate` boolean - `cycle` integer[] - `election_year` integer[] - `office` string[] - `state` string[] - `party` string[] - `year` string - `district` string[] - `candidate_status` string[] - `incumbent_challenge` string[] - `federal_funds_flag` boolean - `has_raised_funds` boolean - `name` string[] - `sort` string - `sort_hide_null` boolean - `sort_null_only` boolean - `sort_nulls_last` boolean - `api_key` string ## Response `default` Default response - CandidateSearchPage - `pagination` OffsetInfo - `count` integer - `is_count_exact` boolean - `page` integer - `pages` integer - `per_page` integer - `results` CandidateSearch[] - `active_through` integer, nullable: Last year a candidate was active. This field is specific to the candidate_id so if the same person runs for another office, there may be a different record for them. - `candidate_id` string, nullable: A unique identifier assigned to each candidate registered with the FEC. If a person runs for several offices, that person will have separate candidate IDs for each office. First character indicates office - [P]residential, [H]ouse, [S]enate]. Second character is the last digit of the two-year period the ID was created. Third and fourth is the candidate state. Presidential IDs don't have state. Fifth and sixth is the district when the candidate first ran. This does not change if the candidate/member's district changes during re-districting. Presidential IDs don't have districts. The rest is sequence. - `candidate_inactive` boolean, nullable: Candidates who are actively seeking office. If no value is specified, all candidates are returned. When True is specified, only active candidates are returned. When False is specified, only inactive candidates are returned. - `candidate_status` string, nullable: One-letter code explaining if the candidate is: - C present candidate - F future candidate - N not yet a candidate - P prior candidate - `cycles` integer[], nullable: Two-year election cycle in which a candidate runs for office. Calculated from Form 2. The cycle begins with an odd year and is named for its ending, even year. This cycle follows the traditional house election cycle and subdivides the presidential and Senate elections into comparable two-year blocks. To retrieve data for the entire four years of a presidential term or six years of a senatorial term, you will need the `election_full` flag. - `district` string, nullable: Two-digit US House distirict of the office the candidate is running for. Presidential, Senate and House at-large candidates will have District 00. - `district_number` integer, nullable: Two-digit US House distirict of the office the candidate is running for. Presidential, Senate and House at-large candidates will have District 00. - `election_districts` string[], nullable: Two-digit US House distirict of the office the candidate is running for. Presidential, Senate and House at-large candidates will have District 00. - `election_years` integer[], nullable: Years in which a candidate ran for office. - `federal_funds_flag` boolean - `first_file_date` string, date, nullable: The day the FEC received the candidate's first filing. This is a F2 candidate registration. - `has_raised_funds` boolean - `inactive_election_years` integer[], nullable: inactive years - `incumbent_challenge` string, nullable: One-letter code ('I', 'C', 'O') explaining if the candidate is an incumbent, a challenger, or if the seat is open. - `incumbent_challenge_full` string, nullable: Explains if the candidate is an incumbent, a challenger, or if the seat is open. - `last_f2_date` string, date, nullable: The day the FEC received the candidate's most recent Form 2 - `last_file_date` string, date, nullable: The day the FEC received the candidate's most recent filing - `load_date` string, date-time, nullable: Date the information was loaded into the FEC systems. This can be affected by reseting systems and other factors, refer to receipt_date for the day that the FEC received the paper or electronic document. Keep in mind that paper filings take more time to process and there can be a lag between load_date and receipt_date. This field can be helpful to identify paper records that have been processed recently. - `name` string, nullable: Name of candidate running for office - `office` string, nullable: Federal office candidate runs for: H, S or P - `office_full` string, nullable: Federal office candidate runs for: House, Senate or presidential - `party` string, nullable: Three-letter code for the party affiliated with a candidate or committee. For example, DEM for Democratic Party and REP for Republican Party. - `party_full` string, nullable: Party affiliated with a candidate or committee - `principal_committees` PrincipalCommittee[] - `affiliated_committee_name` string, nullable: Affiliated committee or connected organization - `candidate_ids` string[], nullable: A unique identifier assigned to each candidate registered with the FEC. If a person runs for several offices, that person will have separate candidate IDs for each office. First character indicates office - [P]residential, [H]ouse, [S]enate]. Second character is the last digit of the two-year period the ID was created. Third and fourth is the candidate state. Presidential IDs don't have state. Fifth and sixth is the district when the candidate first ran. This does not change if the candidate/member's district changes during re-districting. Presidential IDs don't have districts. The rest is sequence. - `committee_id` string, required: A unique identifier assigned to each committee or filer registered with the FEC. In general a committee id begins with the letter C which is followed by eight digits. - `committee_type` string, nullable: The one-letter type code of the organization: - C communication cost - D delegate - E electioneering communication - H house - I independent expenditure filer (not a committee) - N PAC - nonqualified - O independent expenditure-only (super PACs) - P presidential - Q PAC - qualified - S senate - U single candidate independent expenditure - V PAC with non-contribution account, nonqualified - W PAC with non-contribution account, qualified - X party, nonqualified - Y party, qualified - Z national party non-federal account - `committee_type_full` string, nullable: The one-letter type code of the organization: - C communication cost - D delegate - E electioneering communication - H house - I independent expenditure filer (not a committee) - N PAC - nonqualified - O independent expenditure-only (super PACs) - P presidential - Q PAC - qualified - S senate - U single candidate independent expenditure - V PAC with non-contribution account, nonqualified - W PAC with non-contribution account, qualified - X party, nonqualified - Y party, qualified - Z national party non-federal account - `cycles` integer[], nullable: A two year election cycle that the committee was active- (after original registration date but before expiration date in Form 1s) The cycle begins with an odd year and is named for its ending, even year. - `designated_agent_city` string, nullable: Designated agent city - `designated_agent_first_name` string, nullable: Designated agent first name - `designated_agent_last_name` string, nullable: Designated agent last name - `designated_agent_middle_name` string, nullable: Designated agent middle name - `designated_agent_name` string, nullable: Designated agent name - `designated_agent_phone_number` string, nullable: Designated agent phone number - `designated_agent_prefix` string, nullable: Designated agent prefix - `designated_agent_state` string, nullable: Designated agent state - `designated_agent_street1` string, nullable: Designated agent street1 - `designated_agent_street2` string, nullable: Designated agent street2 - `designated_agent_suffix` string, nullable: Designated agent suffix - `designated_agent_title` string, nullable: Designated agent title - `designated_agent_zip` string, nullable: Designated agent zip - `designation` string, nullable: The one-letter designation code of the organization: - A authorized by a candidate - J joint fundraising committee - P principal campaign committee of a candidate - U unauthorized - B lobbyist/registrant PAC - D leadership PAC - `designation_full` string, nullable: The one-letter designation code of the organization: - A authorized by a candidate - J joint fundraising committee - P principal campaign committee of a candidate - U unauthorized - B lobbyist/registrant PAC - D leadership PAC - `filing_frequency` string, nullable: The one-letter code of the filing frequency: - A Administratively terminated - D Debt - M Monthly filer - Q Quarterly filer - T Terminated - W Waived - `first_f1_date` string, date, nullable: The day the FEC received the committee's first Form 1 - `first_file_date` string, date, nullable: The day the FEC received the committee's first filing. This is usually a Form 1 committee registration. - `last_f1_date` string, date, nullable: The day the FEC received the committee's most recent Form 1 - `last_file_date` string, date, nullable: The day the FEC received the committee's most recent filing - `name` string, nullable: The name of the committee. If a committee changes its name, the most recent name will be shown. Committee names are not unique. Use committee_id for looking up records. - `organization_type` string, nullable: The one-letter code for the kind for organization: - C corporation - L labor organization - M membership organization - T trade association - V cooperative - W corporation without capital stock - H host committee - I inaugural committee - `organization_type_full` string, nullable: The one-letter code for the kind for organization: - C corporation - L labor organization - M membership organization - T trade association - V cooperative - W corporation without capital stock - H host committee - I inaugural committee - `party` string, nullable: Three-letter code for the party affiliated with a candidate or committee. For example, DEM for Democratic Party and REP for Republican Party. - `party_full` string, nullable: Three-letter code for the party affiliated with a candidate or committee. For example, DEM for Democratic Party and REP for Republican Party. - `state` string, nullable: State of the committee's address as filed on the Form 1 - `treasurer_name` string, nullable: Name of the Committee's treasurer. If multiple treasurers for the committee, the most recent treasurer will be shown. - `state` string, nullable: US state or territory where a candidate runs for office --- [API](https://skmtc.dev/fec/apis/openfec.md) - [All operations](https://skmtc.dev/fec/apis/openfec/llms.txt) - [OpenAPI document](https://skmtc.dev/fec/apis/openfec/revisions/d2eb3171e225?raw)