BallotReady Officeholder Data FAQ

Beyond tracking 100,000+ open seats and candidates in the 2025 election cycle, we've also refreshed our comprehensive dataset of current officeholders at all levels of government.

As constituents overwhelm lawmakers with concerns about rapid government changes nationwide, your organization needs a reliable database of elected officials' contact information.

Here’s what’s included in our package :

✅ 300,000+ individual officeholder records

✅ Contact info (email & phone)

✅ Mailing addresses

✅ Official websites & social media links

✅ Party affiliation

✅ Easy-to-use identifiers (state, government level, position category, term, etc.)

*Our research refresh on up to date contact information for current officeholders is currently ongoing.

---

Frequently Asked Questions

• What is the structure of the data in the API?

  Our current API structure is available in our developer documentation.

• How are new incumbents linked to existing offices?

  Offices are Position objects and individuals are represented as a Person object in the API.  When a person is elected into a position, we create an OfficeHolder object that ties them to that position.  Each OfficeHolder record has startAt and endAt values that indicate when the person’s term in that position starts and ends.  For convenience, the officeHolders query also has an isCurrent filter that allows for only showing officeholder records that represent people actively in office at the time of execution.

• How are representatives linked to the districts they represent in the data?

  Representatives are linked to districts they represent using our geospatial data. BallotReady has prioritized collecting over 10,000 unique shapefiles not available via the Census to ensure accurate district and subdistrict boundaries for downballot positions.

  Users can link officeholders to districts using the officeHolders query in our API.  Most queries, including officeHolders, offer a LocationFilter that can be used to list officeHolders specific to a particular geography by filtering on an address, point (latitude/longitude pair), or zip code.  

  We do not currently expose OCD IDs in our API but we have added exposing OCD IDs in the API to our roadmap for this next cycle of development work thanks to feedback from partners.

• What additional information is provided about the office (contact info, website, address, social profiles)?

  The OfficeHolder object documentation contains a comprehensive, updated list of fields available.

  Relevant information about the position tied to an officeholder that does not change with each new holder is located on Position objects which are connected to OfficeHolder objects.

  The Position object documentation contains a comprehensive, updated list of fields available.

• What additional information is provided about the representative (campaign contact info, website, personal socials?)

  The Person object documentation contains a comprehensive, updated list of fields available.

• What is the turnaround time post-election for updating incumbent data?

  Our Election Results coverage allows us to update federal races within one week of the election. State-level races may take 1-2 weeks and county and municipal races can take three weeks.

  In some races, these results will be updated much sooner than these benchmarks while others that are initially deemed “too-close-to-call” or which fail to provide timely official election results may take longer. Official contact information for winning officeholders is refreshed on a regular cadence.

• How does BallotReady keep clients apprised of meaningful changes to the structure and availability of data in the API?

  Our documentation is always programmatically updated to reflect the currently available API structure. Furthermore, Customer Success representatives will reach out to API customers with updates pertaining to the API when we introduce important new features.  We did this recently when we introduced the address lookup to the LocationFilter.

• As a user of the API, how can I know when particular fields in the API have or have not been updated?

  Most objects have updatedAt fields that indicate when they were last updated.  This will always be a reliable way to determine when any individual object was last updated.

  Alternatively, several queries, like elections, have top-level filters that can be used to limit returned records to only those that have been updated relative to a provided date and time.  

• What is the level of coverage?

  Our mission is to make local data accessible all the way downballot.

  We cover positions at the federal, state, municipal, and local level down to school board positions. You can find more information on our exact coverage and Tier system here. Our coverage calendar is the most up-to-date place to look for this information.

• How can we test the data and API?

  BallotReady offers free API keys for three weeks of testing. If you are interested in exploring our API or have further questions around our data, reach out and we will get you set up with a test key by tomorrow.