The Campaign Finance API

The Campaign Finance API is now run by ProPublica and will no longer be available through developer.nytimes.com starting on May 1st, 2016.

Checkout the new docs at https://propublica.github.io/campaign-finance-api-docs/ and email apihelp@propublica.org for a new API key.

If you have any questions, please email us at code@nytimes.com.

With the Campaign Finance API, you can retrieve data from United States Federal Election Commission filings.

Note: In this document, curly braces { } indicate required variables. Square brackets [ ] indicate optional parameters or placeholders.

The Campaign Finance API at a Glance
Base URI	`api.nytimes.com/svc/elections/us/{version}/finances`
Scope	Candidate and committee data: 1980–present (even-numbered years) - Committee contributions: 1987/88–present (even-numbered years) Congressional summary financial data: 2000–present (even-numbered years) Presidential data: 2008–present (even-numbered years) Electronic filings: 2001–present (even-numbered years) Paper filings: 1999–present (even-numbered years) Independent Expenditures: 2009–present
HTTP method	GET
Response formats	JSON (`.json`), XML (`.xml`, default)
Quick links	Requests \| Responses \| Examples \| Errors

To use the Campaign Finance API, you must sign up for an API key. Usage is limited to 5000 requests per day (rate limits are subject to change).

Please read and agree to the API Terms of Use, the Supplemental Terms of Use for the Campaign Finance API and the Attribution Guidelines before you proceed.

About Federal Election Commission Data

The New York Times Campaign Finance databases are updated twice daily (electronic filings are updated every 15 minutes). For general information about FEC data, visit the FEC Web site.

The data returned by the Campaign Finance API is subject to the official sale and use restrictions set by the Federal Election Commission. By accessing this data via the Times API, you understand and acknowledge that you are using the data subject to all applicable local, state and federal law, including the FEC restrictions.

Requests

The Campaign Finance service uses a RESTful style. Request types fall into nine categories:

Candidates	Committees
Candidate Search Candidate Details Candidate Leaders by Category State Candidates New Candidates	Committee Search Committee Details New Committees Committee Contributions Committee Contributions to a Candidate Committee Filings Leadership Committees

Presidential Campaigns	Electronic Filings
Presidential Candidate Totals Presidential Candidate Details Presidential State/ZIP Totals	Electronic Filing Search Electronic Filings by Date Electronic Filing Form Types Electronic Filings by Type Presidential Filing Summary Recent Amendments

Electioneering Communications	Individual Contributions
Recent Communications Communications by Committee Communications by Date	Contributions by Presidential Filing Contributions by Committee Contributions by Candidate

Independent Expenditures	Late Contributions to Candidates
Recent Independent Expenditures Independent Expenditures by Date Committee Independent Expenditures Independent Expenditures That Support or Oppose a Candidate Presidential Independent Expenditures Independent Expenditure-Only Committees Race Totals Race Total for a Committee	Today's Late Contributions Late Contributions to a Candidate Late Contributions to a Committee Late Contributions by Date
Lobbyist Bundlers
Lobbyist Bundlers to a Committee

For general tips on creating a request URI, see Constructing a Request. For details about the data returned by each request type, see Responses.

Common Parameters

These parameters are used in all request types. See below for URI structures and additional parameters for each type of request.

Name and Description	Required?	Value and Notes
`version` The API version	Yes	`v3` (in URI path) The current version is `v3`. Support for version 2 ended in February 2011. (Version 1 is for internal use only.)
`campaign-cycle`	Yes	`YYYY` (in URI path) An even-numbered year Presidential data: `2008`–present Congressional data: `2000`–present
`api-key` Your registered API key	Yes	Alphanumeric (in query string) For more information, see Requesting a Key.
`response-format` Sets the representation data format	No	`.json \| .xml` (extension) To return JSON, add the `.json` extension to your request URI. XML is the default format; you do not need to add the `.xml` extension to get an XML response.
`callback` JSONP callback function	No	Callback function name (in query string) As of February 2011, the Campaign Finance API supports JSONP requests. Simply add your callback function to the query string.

Candidates

Candidate Search

To search for Congressional and presidential candidates by last name, use the following URI structure:

api.nytimes.com/svc/elections/us/{version}/finances/{campaign-cycle}/candidates/search[.response-format]?query={lname}&api-key={your-API-key}[&callback={callback-function}]

Required Parameters

With the exception of api-key, these parameters are specified in the URI path. Add your api-key as a name-value pair in a query string.

Name and Description	Value and Notes
`version`	See Common Parameters.
`campaign-cycle`	See Common Parameters.
`lname`	The candidate last name or partial last name Examples: `Greene` `Robin` (retrieves both Robin and Robinson)
`api-key`	See Common Parameters.

Optional Parameters

Name and Description	Value and Notes
`response-format`	See Common Parameters.
`callback`	See Common Parameters.

Next Steps:
Responses | Data Returned | Examples | Top of this section | Full list of requests

Candidate Details

To retrieve campaign finance details for a particular candidate (presidential or Congressional), use the following URI structure:

api.nytimes.com/svc/elections/us/{version}/finances/{campaign-cycle}/candidates/{fec-id}[.response-format]?api-key={your-API-key}[&callback={callback-function}]

See also the Presidential Candidate Details request.

Required Parameters

With the exception of api-key, these parameters are specified in the URI path. Add your api-key as a name-value pair in a query string.

Name and Description	Value and Notes
`version`	See Common Parameters.
`campaign-cycle`	See Common Parameters.
`fec-id`	String: `P \| H \| S` + 8 characters (P = President; H = House; S = Senate) The FEC assigns a unique ID to each candidate. Note that this request type uses the candidate ID, not the committee ID used in the Presidential Candidate Details request type. To find a candidate's official FEC ID, use a candidate search request or the FEC web site.
`api-key`	See Common Parameters.

Optional Parameters

Name and Description	Value and Notes
`response-format`	See Common Parameters.
`callback`	See Common Parameters.

Next Steps:
Responses | Data Returned | Examples | Top of this section | Full list of requests

Candidate Leaders by Category

To retrieve the top 20 candidates in a specific category (such as contribution total or debts owed), use the following URI structure:

api.nytimes.com/svc/elections/us/{version}/finances/{campaign-cycle}/candidates/leaders/{category}[.response-format]?api-key={your-API-key}[&callback={callback-function}]

Required Parameters

With the exception of api-key, these parameters are specified in the URI path. Add your api-key as a name-value pair in a query string.

Name and Description	Value and Notes
`version`	See Common Parameters.
`campaign-cycle`	See Common Parameters.
`category`	Specify one of these categories: Candidate Loan `candidate-loan` Contribution Total `contribution-total` Debts Owed `debts-owed` Disbursements Total `disbursements-total` End Cash `end-cash` Individual Total `individual-total` PAC Total `pac-total` Receipts Total `receipts-total` Refund Total `refund-total`
`api-key`	See Common Parameters.

Optional Parameters

Name and Description	Value and Notes
`response-format`	See Common Parameters.
`callback`	See Common Parameters.

Next Steps:
Responses | Data Returned | Examples | Top of this section | Full list of requests

State Candidates

To retrieve House and Senate candidates for a particular state (and optional chamber and district), use the following URI structure:

api.nytimes.com/svc/elections/us/{version}/finances/{campaign-cycle}/seats/{state}[/chamber][/district][.response-format]?api-key={your-API-key}[&callback={callback-function}]

Required Parameters

With the exception of api-key, these parameters are specified in the URI path. Add your api-key as a name-value pair in a query string.

Name and Description	Value and Notes
`version`	See Common Parameters.
`campaign-cycle`	See Common Parameters.
`state`	Two-letter state abbreviation
`api-key`	See Common Parameters.

Optional Parameters

Name and Description	Value and Notes
`chamber`	`house \| senate`
`district` (House requests only)	House of Representatives district number Specify the district number; for "at large" districts (Alaska, Delaware, Montana, North Dakota, South Dakota, Vermont and Wyoming), specify the number `1`. If you do not specify a district, all House candidates for `state` will be returned. If you specify a district in a Senate request, it will be ignored.
`response-format`	See Common Parameters.
`callback`	See Common Parameters.

Next Steps:
Responses | Data Returned | Examples | Top of this section | Full list of requests

New Candidates

To retrieve the 20 most recently added candidates, use the following URI structure:

api.nytimes.com/svc/elections/us/{version}/finances/{campaign-cycle}/candidates/new[.response-format]?api-key={your-API-key}[&callback={callback-function}]

Required Parameters

With the exception of api-key, these parameters are specified in the URI path. Add your api-key as a name-value pair in a query string.

Name and Description	Value and Notes
`version`	See Common Parameters.
`campaign-cycle`	See Common Parameters. Note: Only the current campaign cycle is supported.
`api-key`	See Common Parameters.

Optional Parameters

Name and Description	Value and Notes
`response-format`	See Common Parameters.
`callback`	See Common Parameters.

Next Steps:
Responses | Data Returned | Examples | Top of this section | Full list of requests

Committees

Committee Search

To search for a political committee by full or partial name, use the following URI structure:

api.nytimes.com/svc/elections/us/{version}/finances/{campaign-cycle}/committees/search[.response-format]?query={name}&api-key={your-API-key}[&callback={callback-function}]

Required Parameters

With the exception of api-key, these parameters are specified in the URI path. Add your api-key as a name-value pair in a query string.

Name and Description	Value and Notes
`version`	See Common Parameters.
`campaign-cycle`	See Common Parameters.
`name`	The committee name or partial name Examples: `medicare` `viacom`
`api-key`	See Common Parameters.

Optional Parameters

Name and Description	Value and Notes
`response-format`	See Common Parameters.
`callback`	See Common Parameters.

Next Steps:
Responses | Data Returned | Examples | Top of this section | Full list of requests

Committee Details

To get details about a committee by FEC ID, use the following URI structure:

api.nytimes.com/svc/elections/us/{version}/finances/{campaign-cycle}/committees/{fec-id}[.response-format]?api-key={your-API-key}[&callback={callback-function}]

Required Parameters

With the exception of api-key, these parameters are specified in the URI path. Add your api-key as a name-value pair in a query string.

Name and Description	Value and Notes
`version`	See Common Parameters.
`campaign-cycle`	See Common Parameters.
`fec-id`	String: `C` + 8 digits The FEC assigns a unique ID to each committee. To find a committee's official FEC ID, use a committee search request or the FEC web site.
`api-key`	See Common Parameters.

Optional Parameters

Name and Description	Value and Notes
`response-format`	See Common Parameters.
`callback`	See Common Parameters.

Next Steps:
Responses | Data Returned | Examples | Top of this section | Full list of requests

New Committees

To retrieve the 20 most recently added committees, use the following URI structure:

api.nytimes.com/svc/elections/us/{version}/finances/{campaign-cycle}/committees/new[.response-format]?api-key={your-API-key}[&callback={callback-function}]

Required Parameters

With the exception of api-key, these parameters are specified in the URI path. Add your api-key as a name-value pair in a query string.

Name and Description	Value and Notes
`version`	See Common Parameters.
`campaign-cycle`	See Common Parameters. Note: Only the current campaign cycle is supported.
`api-key`	See Common Parameters.

Optional Parameters

Name and Description	Value and Notes
`response-format`	See Common Parameters.
`callback`	See Common Parameters.

Next Steps:
Responses | Data Returned | Examples | Top of this section | Full list of requests

Committee Contributions

To retrieve all available data about a particular committee's