Overview

Using the Campaign Finance API, you can retrieve data from United States Federal Election Commission filings and other sources. The API, which originated at The New York Times in 2008, covers summary information for candidates and committees, as well as certain types of itemized data. This document describes the requests that users can make of the API and the responses that it returns.

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

Get an API Key

You can sign up to request an API key at ProPublica’s Data Store.

Scope of Data

  • Candidate and committee data: 1980–present
  • Committee contributions: 1987/88–present
  • Congressional summary financial data: 2000–present (even-numbered years)
  • Presidential campaign data: 2008–present (even-numbered years)
  • Electronic filings: 2001–present
  • Paper filings: 1999–present
  • Independent Expenditures: 2009–present
  • 48-hour notices of contributions/loans received: 2010-present
  • Lobbyist bundler data: 2012-present

The ProPublica Campaign Finance database is updated daily (electronic filings are updated every 15 minutes). For general information about FEC data, visit the FEC Web site.

Usage constitutes agreement to Terms of Use, described below. 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 ProPublica API, you understand and acknowledge that you are using the data subject to all applicable local, state and federal law, including the FEC restrictions.

Terms of Use

Use of this API is available under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 United States license. Commercial users may be subject to additional use fees. To request permission for any commercial use, please fill out the API key request form.

All users are required to abide by the following terms of use for data provided by the API:

  1. You can’t republish the raw data in its entirety, or otherwise distribute the data (in whole or in part) on a stand-alone basis.
  2. You can’t change the data except to update or correct it.
  3. Unless authorized, you can’t charge people money to look at the data, or sell advertising specifically against it. (It may be used on advertising-supported websites or on paid-access sites that provide other content, benefits and/or services.)
  4. You can’t sub-license or resell the data to others.
  5. If you use the data for publication, you must cite ProPublica.
  6. We do not guarantee the accuracy or completeness of the data. You acknowledge that the data may contain errors and omissions.
  7. We are not obligated to update the data, but in the event we do, you are solely responsible for checking our site for any updates.
  8. You will indemnify, hold harmless, and defend ProPublica from and against any claims arising out of your use of the data.

Authentication

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). The API key must be included in all API requests to the server, set as a header:

X-API-Key: PROPUBLICA_API_KEY

To authorize, use this code:

With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "X-API-Key: PROPUBLICA_API_KEY"

Make sure to replace PROPUBLICA_API_KEY with your API key.

Requests

The Campaign Finance API uses a RESTful style. See individual methods below for permitted requests. The API only accepts GET requests. All requests begin with:

https://api.propublica.org/campaign-finance/{version}/

The current version is v1.

Common Parameters

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

  • version The API version (in URI path). The current version is v1.
  • cycle An even-numbered year between 1996 and 2016 (in URI path). The current cycle in 2018.
  • format The format of the response (.json or xml) added to the end of the request.

The following parameters are optional:

  • callback JSONP callback function (in query string).
  • offset The first 20 results are shown by default for most requests. To page through the results, set offset to the appropriate multiple of 20. Date-based responses return all relevant results.

Responses

The API provides JSON and XML responses for every type of request, and supports JSONP callbacks. Responses that are not date-based or containing aggregate totals return the first 20 results; pagination is available via an offset query string parameter using multiples of 20.

Errors

The ProPublica Campaign Finance API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is improperly configured
401 Unauthorized – Your API key is wrong or missing
403 Forbidden – Your request is not allowed
404 Not Found – Your request worked, but did not find a response
405 Method Not Allowed – You tried to access a response with an invalid method
406 Not Acceptable – You requested a format that isn’t json or xml
429 Too Many Requests – You’ve made too many requests.
500 Internal Server Error – We had a problem with our server. Try again later, and let us know what you requested at [email protected].
503 Service Unavailable – We’re temporarily offline for maintenance or because of another issue. Please try again later.

Data Sources

The data returned by the Campaign finance API is compiled from the Federal Election Commission. Information about external services used by candidates and committees, such as social media accounts and official websites, are gathered by ProPublica and the United States project.

Data Update Schedules

FEC electronic filing data is updated every 15 minutes. Summary FEC data is updated daily.