openfec-guide

Scope

Use OpenFEC for federal campaign-finance research and FEC legal records. Near-real-time e-filing data is outside this server's scope; do not use an empty result to rule out a newly filed report.

Identifiers

• Resolve a candidate's name with openfec_search_candidates. Carry the returned candidate ID and race geography into the investigation.
• Resolve the cycle's principal campaign committee from that candidate's openfec_lookup_elections search row: candidate_pcc_id identifies the committee and candidate_pcc_name names it. Page the race until the candidate is found.
• Use openfec_search_committees to resolve a PAC by name or discover a candidate's related committees. Keep each returned committee ID attached to its own records.
• For legal detail, take no and document_type from openfec_search_legal. openfec_get_legal_document accepts the plural form of that document type; do not substitute a committee ID or infer a case number from the search text.

Gates

1. Establish historical affiliation before attributing money. A committee's designation is current even when a committee search is cycle-filtered. Do not use a current principal designation as proof of the principal committee for a past race; use the race's candidate row.
2. Match reporting scope before comparing amounts. Carry the requested cycle through financial calls and inspect search_criteria and coverage dates. Race totals and aggregated independent expenditures can cover a full election period; choose the period the question requires before comparing them with cycle-scoped transactions. Label unequal coverage rather than presenting it as a like-for-like comparison.
3. Use reported totals for financial summaries. Start with candidate or committee totals rather than treating a page of transactions as total receipts or spending. A totals lookup with no record can mean no filing for the selected cycle, not an unknown committee.
4. Preserve committee boundaries. Candidate totals do not include every leadership PAC or joint fundraising committee associated with that candidate. Retrieve related committees' own totals and report them separately.
5. Check the selected mode before narrowing a question. Aggregate modes do not support every itemized filter. If the question depends on a donor, payee, date, or amount filter that only itemized mode supports, use itemized records rather than dropping the filter to obtain an aggregate.
6. Establish coverage before claiming completeness or absence. Follow the response's continuation mechanism. A short page can be bounded by the server; an empty page can be an exhausted position in a nonempty result set. Restart an itemized search when changing its filters instead of reusing its cursor. Treat counts marked approximate as estimates.
7. Read the legal record before characterizing its outcome. Search results summarize documents, dispositions, and votes. Fetch detail and retrieve any relevant withheld arrays before reporting the record complete. Legal search is full-text rather than entity-linked: no name match does not establish that a committee has no cases.