canonical: https://jentic.com/apis/openstates.org/openstates

# Open States API v3

Open States API v3 provides programmatic access to U.S. state legislative data, including bills, legislators, committees, events, and jurisdictions across all 50 states, the District of Columbia, and Puerto Rico. Agents can search bills by subject or session, retrieve legislator profiles with district information, and pull committee memberships and meeting events. Data is normalized across state legislatures so a single query pattern works for any jurisdiction. The API requires a free API key and is maintained by the Open States project, a civic-tech nonprofit effort.

## For AI agents

Search U.S. state bills, legislators, committees, and legislative events across all 50 states with normalized fields and jurisdiction filtering.

## Scope

Does not handle federal Congress data, voter registration, or campaign finance - use for U.S. state legislative data only.

## Capabilities

- Search state legislative bills by jurisdiction, session, subject, and sponsor
- Retrieve detailed bill records by Open States bill ID or jurisdiction-session-bill identifier
- Look up state legislators with district, party, chamber, and contact details
- Geolocate legislators serving a specific latitude and longitude using the people.geo endpoint
- List committees and their memberships for any state legislature
- Pull upcoming and historical legislative events and hearings

## Use cases

### Civic Bill Tracking Dashboard

Build a dashboard that tracks legislation across multiple U.S. states by subject area. The /bills endpoint accepts jurisdiction, session, subject, and updated_since filters so a daily job can surface only bills with recent action. Each result includes sponsors, action history, and links to the canonical state record. Coverage spans all 50 states, DC, and Puerto Rico with a unified schema.

Example prompt: Search /bills for jurisdiction=ca, session=20232024, subject=Housing, and return the 10 most recently updated bills with their sponsors and last action date

### Legislator Lookup by Address

Provide constituents with a way to identify their state legislators from a geographic point. The /people.geo endpoint accepts lat and lng query parameters and returns the legislators whose districts contain that coordinate. This supports voter education tools, advocacy platforms, and constituent communication apps without requiring district shapefile management on the client side.

Example prompt: Call GET /people.geo with lat=37.7749 and lng=-122.4194 and return the names, parties, and chambers of legislators serving that point

### Committee Membership Research

Researchers and journalists studying state policy can pull committee structures and memberships using /committees and /committees/{committee_id}. Results include the committee chamber, parent committee, subjects, and current member roster with role and party data. Combine with /people for full legislator profiles and /events for committee meeting schedules.

Example prompt: List all committees for jurisdiction=ny via GET /committees and fetch the full membership for the Finance committee

### AI Agent Civic Research Assistant

An AI agent answering questions about U.S. state legislation can use Open States v3 through Jentic to search bills, fetch legislator records, and pull event schedules without scraping individual statehouse websites. Jentic resolves the agent's natural-language query into the right /bills, /people, or /events call, supplies the API key from the vault, and returns structured JSON the agent can summarize.

Example prompt: Through Jentic, search 'state bills about renewable energy in Texas' and return the top 5 bills with their summaries and current status

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /bills | Search state bills with jurisdiction, session, and subject filters |
| GET | /bills/ocd-bill/{openstates_bill_id} | Retrieve a bill by its Open States bill ID |
| GET | /people | Search state legislators by name or jurisdiction |
| GET | /people.geo | Find legislators serving a given lat/lng |
| GET | /committees | List committees for a jurisdiction |
| GET | /events | List legislative events and hearings |
| GET | /jurisdictions | List supported state and territorial jurisdictions |

## Key resources

- **Bills** — Search and retrieve state legislative bills by jurisdiction, session, subject, sponsor, or Open States bill ID.
- **People** — Search legislators by name, jurisdiction, or district; geolocate legislators by lat/lng.
- **Jurisdictions** — List supported state and territory jurisdictions and inspect their legislative session structure.
- **Committees** — List committees for a jurisdiction and fetch member rosters.
- **Events** — Retrieve legislative hearings, floor sessions, and committee meetings with date filters.

## Why Jentic

- **Setup:** Wiring the Open States API by hand means sending your key on every request and building the query parameters for bills, people, committees, and events across U.S. state legislatures yourself. Through Jentic you install once, import the Open States API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** You limit the agent to the operations it needs, such as searching bills or looking up legislators by geography. This surface is read-only state legislative data, so you choose which of the bills, people, committees, and events operations the agent may call.
- **Credential handling:** Your Open States API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find state bills about housing' or 'look up legislators for an address', and Jentic returns the matching Open States operation with its parameter schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Congress.gov API** — Federal U.S. Congress data - bills, members, committees, and votes at the federal level.
- **Nominatim Geocoding API** — Geocode street addresses to lat/lng so /people.geo can resolve them to a legislator.
- **ClinicalTrials.gov API** — Different domain (clinical trials), similar government open-data shape - relevant when the user wants public-record lookup rather than legislative data.

## FAQ

### What authentication does the Open States API v3 use?

Open States v3 uses an API key passed in the X-API-Key header. Keys are free after registration at openstates.org/accounts/signup. Through Jentic, the key is stored encrypted in the vault and injected at request time, so the agent never sees the raw value.

### Can I look up a legislator by street address with the Open States API v3?

Not by raw address - the API exposes /people.geo which takes lat and lng. Geocode the address first with a service like Nominatim or Google Geocoding, then pass the coordinates to /people.geo to get matching state legislators.

### What are the rate limits for the Open States API v3?

Open States enforces free-tier rate limits documented at docs.openstates.org. Higher request volumes require a paid plan from the Open States project. The /metrics endpoint exposes server-side request statistics.

### How do I search for bills about a specific topic with the Open States API v3 through Jentic?

Search Jentic for 'search state bills by subject', load the GET /bills schema, and execute with parameters like jurisdiction, session, and subject. Jentic returns matching results without you needing to read the Open States docs first.

### Does the Open States API v3 cover federal Congress?

No - Open States covers only U.S. state and territorial legislatures (50 states, DC, Puerto Rico). For federal bills and members of Congress, use the Congress.gov API. Open States can be used alongside Congress.gov in the same workflow.

### How current is the data in the Open States API v3?

Bill and legislator records are updated regularly from each state's official legislative system. The bill objects include updated_at timestamps so you can poll for changes since your last sync.

### Can I limit what my agent is allowed to do with the Open States API?

Yes. Because Jentic One is self-hosted, you run your own instance and your own rules decide which Open States operations and credentials the agent may use. Since this surface is read-only state legislative data, you choose whether the agent can reach the bills, people, committees, or events operations, so you can allow bill search and legislator geo lookups while withholding the rest. The agent can only call the operations you have granted it.