API reference

Ballot races (elections, contests and their choices), endorsers and endorsements across the U.S., what chosen endorsers recommend in each race, and a stream of endorsement changes. Address and geography lookups (the ballot at an address, districts and boundaries, representatives by location) have been retired.

Base URL: https://api.endorsedby.org
Authentication: Authorization: Bearer <your key> on every request
OpenAPI: openapi.json (version 1.0.0, OpenAPI 3.1.0)

GET/v1/statesStates

200: Every state
400: An error
401: An error
403: An error
429: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/states"

GET/v1/electionsElections

Parameter	In	Type	Description
`states`	query	string	USPS codes. Comma-separated; any of them matches.
`types`	query	string	general, primary, special, special_primary, runoff, consolidated. Comma-separated; any of them matches.
`upcoming`	query	boolean
`from`	query	string, date	Elections on or after this date.
`to`	query	string, date	Elections on or before this date.
`lang`	query	string, one of en, es, default en	es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise.
`limit`	query	integer, 1…500
`cursor`	query	string	next_cursor from the previous page.

200: A page of elections, with voting rules (all-mail, ranked choice, fusion, runoff dates) in details
400: An error
401: An error
403: An error
429: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/elections"

GET/v1/endorser-categoriesKinds of endorser (labor, newspaper, …)

Parameter	In	Type	Description
`lang`	query	string, one of en, es, default en	es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise.

200: Every category
400: An error
401: An error
403: An error
429: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/endorser-categories"

GET/v1/endorsersEndorsers

Parameter	In	Type	Description
`categories`	query	string	Category slugs. Comma-separated; any of them matches.
`states`	query	string	Home states, or national. Comma-separated; any of them matches.
`elections`	query	string	Only endorsers with endorsements in these elections. Comma-separated; any of them matches.
`q`	query	string	Name contains.
`lang`	query	string, one of en, es, default en	es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise.
`limit`	query	integer, 1…500
`cursor`	query	string	next_cursor from the previous page.

200: A page of endorsers
400: An error
401: An error
403: An error
429: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/endorsers"

GET/v1/endorsers/{slug}One endorser, with the elections they’ve endorsed in

Parameter	In	Type	Description
`slug`required	path	string
`lang`	query	string, one of en, es, default en	es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise.

200: The endorser
400: An error
401: An error
403: An error
429: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/endorsers/{slug}"

GET/v1/contestsContests with their choices and voting rules

Parameter	In	Type	Description
`elections`	query	string	Election slugs. Comma-separated; any of them matches.
`states`	query	string	USPS codes. Comma-separated; any of them matches.
`levels`	query	string	District levels. Comma-separated; any of them matches.
`contest_kinds`	query	string	candidate, measure, retention. Comma-separated; any of them matches.
`districts`	query	string	OCD division ids. Comma-separated; any of them matches.
`upcoming`	query	boolean
`lang`	query	string, one of en, es, default en	es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise.
`limit`	query	integer, 1…500
`cursor`	query	string	next_cursor from the previous page.

200: A page of contests
400: An error
401: An error
403: An error
429: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/contests"

GET/v1/contests/{id}One contest with every endorser’s position

Parameter	In	Type	Description
`id`required	path	integer
`categories`	query	string	Only these endorser categories. Comma-separated; any of them matches.
`endorsers`	query	string	Only these endorsers. Comma-separated; any of them matches.
`endorser_states`	query	string	Endorsers based in these states, or "national". Comma-separated; any of them matches.
`lang`	query	string, one of en, es, default en	es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise.

200: The contest
400: An error
401: An error
403: An error
429: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/contests/{id}"

GET/v1/endorsementsEndorsements, one per endorser and choice

Parameter	In	Type	Description
`categories`	query	string	Endorser category slugs. Comma-separated; any of them matches.
`endorsers`	query	string	Endorser slugs. Comma-separated; any of them matches.
`endorser_states`	query	string	Endorsers’ home states (USPS codes), or national. Comma-separated; any of them matches.
`states`	query	string	States the contests are voted in. Comma-separated; any of them matches.
`elections`	query	string	Election slugs. Comma-separated; any of them matches.
`contest_kinds`	query	string	candidate, measure, retention. Comma-separated; any of them matches.
`levels`	query	string	District levels: federal, state, county, city, school, special. Comma-separated; any of them matches.
`contest`	query	integer
`upcoming`	query	boolean
`lang`	query	string, one of en, es, default en	es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise.
`limit`	query	integer, 1…500
`cursor`	query	string	next_cursor from the previous page.

200: A page of endorsements
400: An error
401: An error
403: An error
429: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/endorsements"

GET/v1/recommendationsWhat chosen endorsers recommend in each contest, grouped by election

Choose the contests with state (a state’s upcoming contests), election or contest; a state is required unless an election or contest is given. Address and location lookups (location, address, zip, city, county, lat, lng) have been retired and are refused with 400.

Parameter	In	Type	Description
`state`	query	string	USPS code of the state the contests are voted in (comma-separated for several). Required unless election or contest is given; on its own it covers upcoming elections.
`election`	query	string	Election slugs, past or upcoming. Comma-separated; any of them matches.
`contest`	query	string	Contest ids. Comma-separated; any of them matches.
`subscription`	query	string	A saved subscription (id or name) choosing the endorsers; its states, elections, contest kinds and levels narrow the contests too.
`categories`	query	string	Endorser categories. Comma-separated; any of them matches.
`endorsers`	query	string	Endorser slugs. Comma-separated; any of them matches.
`endorser_states`	query	string	Endorsers based in these states, or "national". Comma-separated; any of them matches.
`levels`	query	string	District levels. Comma-separated; any of them matches.
`contest_kinds`	query	string	candidate, measure, retention. Comma-separated; any of them matches.
`only_endorsed`	query	boolean	Leave out contests none of the chosen endorsers took a position in.
`lang`	query	string, one of en, es, default en	es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise.

200: The scope, the endorsers, and each election’s contests with their choices, backers and recommendation
400: An error
401: An error
403: An error
429: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/recommendations"

GET/v1/officeholdersPeople in office now, with party, term and contact details, by state, office, level or seat

Parameter	In	Type	Description
`states`	query	string	USPS codes. Comma-separated; any of them matches.
`offices`	query	string	us_senator, us_representative, governor, lieutenant_governor, attorney_general, secretary_of_state, chief_election_officer, treasurer, auditor, state_senator, state_representative, state_legislator, city_council. Comma-separated; any of them matches.
`levels`	query	string	federal, state, city. Comma-separated; any of them matches.
`districts`	query	string	OCD division ids of the seats. Comma-separated; any of them matches.
`q`	query	string	Name contains.
`lang`	query	string, one of en, es, default en	es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise.
`limit`	query	integer, 1…500
`cursor`	query	string	next_cursor from the previous page.

200: A page of officeholders
400: An error
401: An error
403: An error
429: An error
503: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/officeholders"

GET/v1/officeholders/{id}One officeholder by person_id, with every seat they hold

Parameter	In	Type	Description
`id`required	path	string, uuid
`lang`	query	string, one of en, es, default en	es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise.

200: The officeholder
400: An error
401: An error
403: An error
429: An error
503: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/officeholders/{id}"

GET/v1/coverageWhat the API has for each state

Parameter	In	Type	Description
`upcoming`	query	boolean, default true	Count only upcoming elections (default true).

200: Elections, contests, measures, endorsers and endorsements per state, and when they last changed
400: An error
401: An error
403: An error
429: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/coverage"

GET/v1/eventsEndorsement changes after a cursor (polling)

Parameter	In	Type	Description
`subscription`	query	string	A saved subscription’s id or name (instead of filter parameters).
`categories`	query	string	Endorser category slugs. Comma-separated; any of them matches.
`endorsers`	query	string	Endorser slugs. Comma-separated; any of them matches.
`endorser_states`	query	string	Endorsers’ home states (USPS codes), or national. Comma-separated; any of them matches.
`states`	query	string	States the contests are voted in. Comma-separated; any of them matches.
`elections`	query	string	Election slugs. Comma-separated; any of them matches.
`contest_kinds`	query	string	candidate, measure, retention. Comma-separated; any of them matches.
`levels`	query	string	District levels: federal, state, county, city, school, special. Comma-separated; any of them matches.
`types`	query	string	created, updated, deleted. Comma-separated; any of them matches.
`cursor`	query	string	Resume after this position (next_cursor, or an SSE event id).
`from`	query	string, one of latest, earliest, default latest
`since`	query	string, date-time	Start at changes from this time (ISO 8601), within the stream’s retention.
`limit`	query	integer, …1000
`wait`	query	integer, …25	Seconds to wait for a change (long polling).

200: Events and the next cursor
400: An error
401: An error
403: An error
410: An error
429: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/events"

GET/v1/streamEndorsement changes as Server-Sent Events

Parameter	In	Type	Description
`subscription`	query	string	A saved subscription’s id or name (instead of filter parameters).
`categories`	query	string	Endorser category slugs. Comma-separated; any of them matches.
`endorsers`	query	string	Endorser slugs. Comma-separated; any of them matches.
`endorser_states`	query	string	Endorsers’ home states (USPS codes), or national. Comma-separated; any of them matches.
`states`	query	string	States the contests are voted in. Comma-separated; any of them matches.
`elections`	query	string	Election slugs. Comma-separated; any of them matches.
`contest_kinds`	query	string	candidate, measure, retention. Comma-separated; any of them matches.
`levels`	query	string	District levels: federal, state, county, city, school, special. Comma-separated; any of them matches.
`types`	query	string	created, updated, deleted. Comma-separated; any of them matches.
`cursor`	query	string	Resume after this position (next_cursor, or an SSE event id).
`from`	query	string, one of latest, earliest, default latest
`since`	query	string, date-time	Start at changes from this time (ISO 8601), within the stream’s retention.

200: text/event-stream: ready, endorsement, checkpoint and reconnect events
400: An error
401: An error
403: An error
410: An error
429: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/stream"

GET/v1/subscriptionsSaved subscriptions

200: Every subscription
400: An error
401: An error
403: An error
429: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/subscriptions"

POST/v1/subscriptionsSave a subscription

201: Created
400: An error
401: An error
403: An error
429: An error

GET/v1/subscriptions/{id}One subscription

Parameter	In	Type	Description
`id`required	path	integer

200: The subscription
400: An error
401: An error
403: An error
429: An error

curl -H "Authorization: Bearer $BALLOTDATA_KEY" \
  "https://api.endorsedby.org/v1/subscriptions/{id}"

PUT/v1/subscriptions/{id}Replace a subscription

Parameter	In	Type	Description
`id`required	path	integer

200: Saved
400: An error
401: An error
403: An error
429: An error

DELETE/v1/subscriptions/{id}Delete a subscription

Parameter	In	Type	Description
`id`required	path	integer

204: Deleted
400: An error
401: An error
403: An error
429: An error