Getting Started

Everything you need to start using the OCPF Public API.

On This Page
Base URL Authentication Response Format Pagination Common Workflows Data Export Endpoint Categories Rate Limits & Usage

Base URL

All API requests should be made to:

https://api.ocpf.us

For example, to search report items:

GET https://api.ocpf.us/search/items?name=Smith

Authentication

No authentication is required. All data served by the OCPF Public API is public record. There are no API keys, tokens, or sign-up steps — just start making requests.

Response Format

All responses are JSON with the following conventions:

  • Property names use camelCase (e.g., firstName, reportItemType)
  • Dates are ISO 8601 strings (e.g., "2024-03-15T00:00:00")
  • Null values are included in responses (not omitted)
  • Content-Type is application/json

Pagination

List and search endpoints support pagination with these query parameters:

Parameter Type Description
pageSize integer Number of results per page (default varies by endpoint)
currentIndex integer Page number, 1-based
withSummary boolean Set to true to include a summary object with total counts

When withSummary=true, the response includes:

{ "summary": { "count": 25, // items returned in this page "total": 1430 // total matching results }, "items": [ ... ] }

Common Workflows

1. Find a Filer

Search for candidate committees by name, then get full details using the CPF ID.

Step 1: Search for filers named "Smith" among candidate type ("C"):

# Search for candidate filers curl "https://api.ocpf.us/filers/listings/C?searchPhrase=smith"

Response (truncated):

[ { "cpfId": 15432, "filerName": "Smith, John A.", "office": "State Representative", "district": "5th Middlesex" }, ... ]

Step 2: Get full filer details using the CPF ID:

# Get filer details curl "https://api.ocpf.us/filer/15432"

2. Search Contributions

Find all contributions from donors named "Jones" during 2024:

# Search report items by donor name and date range curl "https://api.ocpf.us/search/items?name=Jones&startDate=2024-01-01&endDate=2024-12-31&withSummary=true"

Or in JavaScript:

const params = new URLSearchParams({ name: 'Jones', startDate: '2024-01-01', endDate: '2024-12-31', pageSize: '25', withSummary: 'true' }); const response = await fetch( `https://api.ocpf.us/search/items?${params}` ); const data = await response.json(); console.log(`Found ${data.summary.total} contributions`); data.items.forEach(item => { console.log(`${item.firstName} ${item.lastName}: $${item.amount}`); });

3. Get Reports for a Filer

Retrieve the list of report types filed by a filer, then get the individual reports.

Step 1: Get available report types for the filer:

# Get report types for CPF ID 15432 curl "https://api.ocpf.us/reports/baseReportTypes/15432"

Response:

[ { "baseReportTypeId": 101, "reportType": "Year-End Report" }, { "baseReportTypeId": 102, "reportType": "Pre-Election Report" }, ... ]

Step 2: Get the list of filed reports for a specific type:

# Get Year-End Reports for the filer curl "https://api.ocpf.us/reports/reportList/15432?baseReportTypeId=101"

Data Export

Several search endpoints support exporting results in different formats. Use the export-specific endpoints to download data as:

  • Text — tab-delimited text files
  • Excel — .xlsx spreadsheet files
  • PDF — formatted PDF reports

The export endpoints mirror the search parameters:

  • search/textOutput — tab-delimited text
  • search/excelOutput — Excel spreadsheet
  • search/pdfOutput — PDF report

See the API Reference for full parameter details.

Endpoint Categories

Category Description Example Endpoints
Filers Search and look up registered filers filers/listings/{category}, filer/{cpfId}
Reports Campaign finance filings and report details reports/reportList/{cpfId}, report/pdf/{reportId}
Search Search contributions, expenditures, and other report items search/items, search/textOutput
Elections Election chart data and aggregate totals chartData/electionChart, chartData/monthly
Legal Laws, guidance letters, agency actions, and nonfiler lists legal/law/{section}, legal/gls, legal/nonfilers
Municipal Town-level campaign finance data municipalities, municipalityList/options
Content News, events, filing deadlines, newsletters, and forms news/recent, filingDeadlines, forms/all
Reference Lookup values for offices, districts, and filing schedules filingSchedules/{year}, municipalityList/options

See the full interactive documentation at the API Reference.

Rate Limits & Usage

There are no formal rate limits at this time. However, please be respectful of shared resources:

  • Add reasonable delays between bulk requests
  • Use pagination instead of requesting very large result sets
  • Cache results on your end when possible
  • If you plan to make a large number of requests, consider reaching out to ocpf.us first

API key support for rate limiting may be introduced in a future update.

Ready to explore?

Open the interactive API Reference to try out endpoints directly in your browser, or head back to the Developer Portal home page.