API reference

List states

GET /v1/states

Every state, D.C. and territory, with its USPS and FIPS codes. Use the codes in states= filters.

Returns

200 Every state.

• dataarray of State

  Every item.

  3 fields

  • codestring

    USPS state code.

  • fipsstring

    Two-digit FIPS code.

  • namestring

    Full name.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 429 Over a rate limit. Wait Retry-After seconds.

List elections

GET /v1/elections

Elections, with their voting rules in details (all-mail, ranked choice, fusion, runoff dates) and how many contests and endorsements each has. Use an election’s slug to ask for its contests or endorsements.

Query parameters

• statescomma-separated strings

  USPS codes.

  Example CA
• typescomma-separated strings

  Kinds of election.

  One of general, primary, special, special_primary, runoff, consolidated.Example general
• upcomingboolean

  Only elections from yesterday on.

  Default false.
• fromstring (date)

  Elections on or after this date.

  Example 2026-11-01
• tostring (date)

  Elections on or before this date.

  Example 2026-12-31
• langstring

  es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise. Names are never translated.

  One of en, es.Default en.
• limitinteger

  Results per page, 1–500.

  Default 100.1 to 500.
• cursorstring

  The next_cursor from the previous page.

Returns

200 A page of elections, by id.

• dataarray of ElectionSummary

  This page.

  12 fields

  • idinteger

    Election id.

  • slugstring

    Election slug, used in elections= filters: <state>-<date>-<type>.

  • namestring

    Election name.

  • short_namestring or null

    Shorter name.

  • datestring (date)

    Election day.

  • statestring or null

    State; null for a multi-state election.

  • typestring

    Kind of election.

    One of general, primary, special, special_primary, runoff, consolidated.
  • primary_systemstring or null

    How the state runs primaries.

    One of none, closed, semi_closed, open, top_two, nonpartisan.
  • info_urlstring (uri) or null

    Official election page.

  • detailsobject

    Voting rules for the election. Only keys that apply are present.

    11 fields

    • all_mailboolean

      Every voter is mailed a ballot.

    • ranked_choiceboolean

      Some contests in this election use ranked choice voting.

    • fusion_votingboolean

      Candidates can appear on more than one party’s line (New York, Connecticut).

    • partisan_primaryboolean

      A party primary.

    • primarystring

      Which primary, where a state holds several.

    • consolidated_withstring

      Elections held on the same ballot.

    • runoff_datestring (date)

      Date of a runoff, if one is needed.

    • runoff_election_datestring (date)

      Date of the runoff election.

    • top_two_primary_datestring (date)

      Date of the top-two primary that chose these candidates.

    • louisiana_open_primaryboolean

      Louisiana’s open (jungle) primary.

    • notestring

      Anything else voters should know.

  • contest_countinteger

    Contests on the ballot.

  • endorsement_countinteger

    Endorsements in those contests.

• next_cursorstring or null

  Pass as cursor= for the next page; null on the last page.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 429 Over a rate limit. Wait Retry-After seconds.

Coverage by state

GET /v1/coverage

What the API has for each state: elections, contests, measures, endorsers and endorsements, and when they last changed. Handy for deciding what to sync.

Query parameters

• upcomingboolean

  Count only upcoming elections.

  Default true.

Returns

200 One row per state.

• dataarray of Coverage

  Every item.

  11 fields

  • statestring

    USPS state code.

  • namestring

    State name.

  • election_countinteger

    Elections.

  • contest_countinteger

    Contests.

  • measure_countinteger

    Of those, ballot measures.

  • endorser_countinteger

    Endorsers with endorsements here.

  • endorsement_countinteger

    Endorsements.

  • endorsed_contest_countinteger

    Contests with at least one endorsement.

  • first_electionstring (date) or null

    Earliest election.

  • last_electionstring (date) or null

    Latest election.

  • updated_atstring (date-time) or null

    When a contest or endorsement last changed.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 429 Over a rate limit. Wait Retry-After seconds.

List contests

GET /v1/contests

The races on the ballot, each with its district, its election, its voting rules and every choice in ballot order. Filter by election, state, level, kind or district. To see who endorsed whom, use GET /v1/contests/{id} or /v1/endorsements.

Query parameters

• electionscomma-separated strings

  Election slugs.

  Example ca-2026-11-03-general
• statescomma-separated strings

  States the contests are voted in (USPS codes).

  Example CA
• levelscomma-separated strings

  District levels.

  One of federal, state, county, city, school, special.Example county,city
• contest_kindscomma-separated strings

  Contest kinds.

  One of candidate, measure, retention.Example measure
• districtscomma-separated strings

  OCD division ids of the districts.

  Example ocd-division/country:us/state:ca/county:san_francisco
• upcomingboolean

  Only elections from yesterday on.

  Default false.
• langstring

  es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise. Names are never translated.

  One of en, es.Default en.
• limitinteger

  Results per page, 1–200.

  Default 50.1 to 200.
• cursorstring

  The next_cursor from the previous page.

Returns

200 A page of contests, by id.

• dataarray of Contest

  This page.

  16 fields

  • idinteger

    Contest id.

  • titlestring

    Title as printed on the ballot.

  • short_titlestring or null

    Shorter title.

  • kindstring

    candidate (an office), measure (a proposition) or retention (keep a judge?).

    One of candidate, measure, retention.
  • vote_methodstring

    How votes are cast: plurality (vote for one), multi_seat (vote for up to votes_allowed), ranked_choice (rank up to ranks_allowed), approval, or yes_no.

    One of plurality, multi_seat, ranked_choice, approval, yes_no.
  • votes_allowedinteger or null

    How many choices a voter may mark (vote for N).

  • ranks_allowedinteger or null

    Ranked choice: how many choices a voter may rank.

  • measure_codestring or null

    The measure’s letter or number: “K”, “Prop 1”.

  • descriptionstring or null

    Measure text or question, where the ballot prints one.

  • ballot_orderinteger or null

    Position on the printed ballot.

  • partyParty or null

    For a party primary, the party.

    3 fields

    • slugstring

      Party slug.

    • namestring

      Party name.

    • abbreviationstring or null

      Short form as printed, e.g. DEM.

  • detailsobject

    Facts about the contest. Only keys that apply are present.

    16 fields

    • uncontestedboolean

      Only one candidate is running.

    • nonpartisanboolean

      Candidates appear without a party.

    • measure_typestring

      bond, charter_amendment, initiative, referendum, tax, …

    • vote_requiredstring

      Share of the vote needed to pass, e.g. "2/3" or "55%".

    • majority_requiredboolean

      A candidate needs a majority to win outright (else a runoff).

    • amountnumber

      Dollar amount of a bond or tax measure.

    • termstring

      Length of the term, e.g. "4 years".

    • short_termboolean

      The seat is for the remainder of an unexpired term.

    • justicestring

      The judge or justice a retention question is about.

    • runoff_datestring (date)

      Date of a runoff, if one is needed.

    • stagestring

      Stage of a multi-round contest.

    • elected_at_largeboolean

      Elected by the whole jurisdiction, not by district.

    • none_of_theseboolean

      The ballot offers “None of these candidates” (Nevada).

    • primary_nominatingboolean

      The primary nominates a party’s candidate.

    • winnersinteger

      Number of winners, where it differs from votes_allowed.

    • ref_typestring

      Kind of referendum.

  • source_urlstring (uri) or null

    The official source the contest was loaded from.

  • districtDistrict

    The district a contest is voted in.

    6 fields

    • idinteger

      District id. Matches an officeholder’s district_id.

    • ocd_idstring or null

      Open Civic Data division id, used in districts= filters.

    • namestring

      District name.

    • levelstring

      Level of government.

      One of federal, state, county, city, school, special.
    • typestring

      Kind of district: statewide, congressional, state_upper, state_lower, county, council, school, …

    • statestring or null

      USPS state code.

  • electionElection
    10 fields

    • idinteger

      Election id.

    • slugstring

      Election slug, used in elections= filters: <state>-<date>-<type>.

    • namestring

      Election name.

    • short_namestring or null

      Shorter name.

    • datestring (date)

      Election day.

    • statestring or null

      State; null for a multi-state election.

    • typestring

      Kind of election.

      One of general, primary, special, special_primary, runoff, consolidated.
    • primary_systemstring or null

      How the state runs primaries.

      One of none, closed, semi_closed, open, top_two, nonpartisan.
    • info_urlstring (uri) or null

      Official election page.

    • detailsobject

      Voting rules for the election. Only keys that apply are present.

      11 fields

      • all_mailboolean

        Every voter is mailed a ballot.

      • ranked_choiceboolean

        Some contests in this election use ranked choice voting.

      • fusion_votingboolean

        Candidates can appear on more than one party’s line (New York, Connecticut).

      • partisan_primaryboolean

        A party primary.

      • primarystring

        Which primary, where a state holds several.

      • consolidated_withstring

        Elections held on the same ballot.

      • runoff_datestring (date)

        Date of a runoff, if one is needed.

      • runoff_election_datestring (date)

        Date of the runoff election.

      • top_two_primary_datestring (date)

        Date of the top-two primary that chose these candidates.

      • louisiana_open_primaryboolean

        Louisiana’s open (jungle) primary.

      • notestring

        Anything else voters should know.

  • choicesarray of Choice

    Every choice, in ballot order.

    9 fields

    • idinteger

      Choice id: the choice_id endorsements refer to.

    • labelstring

      As printed: the candidate’s ballot name, or Yes / No.

    • measure_answerstring or null

      yes or no for a measure or retention question; null for a candidate.

      One of yes, no.
    • optionstring or null

      A special line: none_of_these (Nevada).

      One of none_of_these.
    • ballot_designationstring or null

      Occupation line printed under the name, e.g. “Transit Planner”.

    • withdrawnboolean

      The candidate withdrew but is still printed on the ballot.

    • candidateCandidate or null

      The candidate; null for a measure answer.

      4 fields

      • idinteger

        Candidate id.

      • full_namestring

        Full name.

      • website_urlstring (uri) or null

        Campaign website.

      • photo_urlstring (uri) or null

        Photo.

    • partyParty or null

      The party (or party preference) printed beside the name.

      3 fields

      • slugstring

        Party slug.

      • namestring

        Party name.

      • abbreviationstring or null

        Short form as printed, e.g. DEM.

    • party_labelstring or null

      The party text exactly as printed, where it differs (fusion lines, top-two preferences).

• next_cursorstring or null

  Pass as cursor= for the next page; null on the last page.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 429 Over a rate limit. Wait Retry-After seconds.

Get a contest with endorsements

GET /v1/contests/{id}

One contest with its choices and every endorser’s position: one pick for vote-for-one, up to N picks for vote-for-N, ranked picks for ranked choice, Yes or No for a measure. Narrow the endorsers with categories, endorsers or endorser_states.

Path parameters

• idintegerrequired

  Contest id.

  At least 1.Example 4410

Query parameters

• categoriescomma-separated strings

  Only endorsers in these categories.

  Example labor,editorial
• endorserscomma-separated strings

  Only these endorsers.

• endorser_statescomma-separated strings

  Only endorsers based in these states, or national.

• langstring

  es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise. Names are never translated.

  One of en, es.Default en.

Returns

200 The contest.

• dataContestDetail
  17 fields

  • idinteger

    Contest id.

  • titlestring

    Title as printed on the ballot.

  • short_titlestring or null

    Shorter title.

  • kindstring

    candidate (an office), measure (a proposition) or retention (keep a judge?).

    One of candidate, measure, retention.
  • vote_methodstring

    How votes are cast: plurality (vote for one), multi_seat (vote for up to votes_allowed), ranked_choice (rank up to ranks_allowed), approval, or yes_no.

    One of plurality, multi_seat, ranked_choice, approval, yes_no.
  • votes_allowedinteger or null

    How many choices a voter may mark (vote for N).

  • ranks_allowedinteger or null

    Ranked choice: how many choices a voter may rank.

  • measure_codestring or null

    The measure’s letter or number: “K”, “Prop 1”.

  • descriptionstring or null

    Measure text or question, where the ballot prints one.

  • ballot_orderinteger or null

    Position on the printed ballot.

  • partyParty or null

    For a party primary, the party.

    3 fields

    • slugstring

      Party slug.

    • namestring

      Party name.

    • abbreviationstring or null

      Short form as printed, e.g. DEM.

  • detailsobject

    Facts about the contest. Only keys that apply are present.

    16 fields

    • uncontestedboolean

      Only one candidate is running.

    • nonpartisanboolean

      Candidates appear without a party.

    • measure_typestring

      bond, charter_amendment, initiative, referendum, tax, …

    • vote_requiredstring

      Share of the vote needed to pass, e.g. "2/3" or "55%".

    • majority_requiredboolean

      A candidate needs a majority to win outright (else a runoff).

    • amountnumber

      Dollar amount of a bond or tax measure.

    • termstring

      Length of the term, e.g. "4 years".

    • short_termboolean

      The seat is for the remainder of an unexpired term.

    • justicestring

      The judge or justice a retention question is about.

    • runoff_datestring (date)

      Date of a runoff, if one is needed.

    • stagestring

      Stage of a multi-round contest.

    • elected_at_largeboolean

      Elected by the whole jurisdiction, not by district.

    • none_of_theseboolean

      The ballot offers “None of these candidates” (Nevada).

    • primary_nominatingboolean

      The primary nominates a party’s candidate.

    • winnersinteger

      Number of winners, where it differs from votes_allowed.

    • ref_typestring

      Kind of referendum.

  • source_urlstring (uri) or null

    The official source the contest was loaded from.

  • districtDistrict

    The district a contest is voted in.

    6 fields

    • idinteger

      District id. Matches an officeholder’s district_id.

    • ocd_idstring or null

      Open Civic Data division id, used in districts= filters.

    • namestring

      District name.

    • levelstring

      Level of government.

      One of federal, state, county, city, school, special.
    • typestring

      Kind of district: statewide, congressional, state_upper, state_lower, county, council, school, …

    • statestring or null

      USPS state code.

  • electionElection
    10 fields

    • idinteger

      Election id.

    • slugstring

      Election slug, used in elections= filters: <state>-<date>-<type>.

    • namestring

      Election name.

    • short_namestring or null

      Shorter name.

    • datestring (date)

      Election day.

    • statestring or null

      State; null for a multi-state election.

    • typestring

      Kind of election.

      One of general, primary, special, special_primary, runoff, consolidated.
    • primary_systemstring or null

      How the state runs primaries.

      One of none, closed, semi_closed, open, top_two, nonpartisan.
    • info_urlstring (uri) or null

      Official election page.

    • detailsobject

      Voting rules for the election. Only keys that apply are present.

      11 fields

      • all_mailboolean

        Every voter is mailed a ballot.

      • ranked_choiceboolean

        Some contests in this election use ranked choice voting.

      • fusion_votingboolean

        Candidates can appear on more than one party’s line (New York, Connecticut).

      • partisan_primaryboolean

        A party primary.

      • primarystring

        Which primary, where a state holds several.

      • consolidated_withstring

        Elections held on the same ballot.

      • runoff_datestring (date)

        Date of a runoff, if one is needed.

      • runoff_election_datestring (date)

        Date of the runoff election.

      • top_two_primary_datestring (date)

        Date of the top-two primary that chose these candidates.

      • louisiana_open_primaryboolean

        Louisiana’s open (jungle) primary.

      • notestring

        Anything else voters should know.

  • choicesarray of Choice

    Every choice, in ballot order.

    9 fields

    • idinteger

      Choice id: the choice_id endorsements refer to.

    • labelstring

      As printed: the candidate’s ballot name, or Yes / No.

    • measure_answerstring or null

      yes or no for a measure or retention question; null for a candidate.

      One of yes, no.
    • optionstring or null

      A special line: none_of_these (Nevada).

      One of none_of_these.
    • ballot_designationstring or null

      Occupation line printed under the name, e.g. “Transit Planner”.

    • withdrawnboolean

      The candidate withdrew but is still printed on the ballot.

    • candidateCandidate or null

      The candidate; null for a measure answer.

      4 fields

      • idinteger

        Candidate id.

      • full_namestring

        Full name.

      • website_urlstring (uri) or null

        Campaign website.

      • photo_urlstring (uri) or null

        Photo.

    • partyParty or null

      The party (or party preference) printed beside the name.

      3 fields

      • slugstring

        Party slug.

      • namestring

        Party name.

      • abbreviationstring or null

        Short form as printed, e.g. DEM.

    • party_labelstring or null

      The party text exactly as printed, where it differs (fusion lines, top-two preferences).

  • endorsementsarray of Position

    Every (matching) endorser’s position, by endorser name.

    2 fields

    • endorserEndorserRef

      Who made an endorsement.

      5 fields

      • idinteger

        Endorser id.

      • slugstring

        Endorser slug, used in endorsers= filters.

      • namestring

        Endorser name.

      • categoryCategory

        The kind of endorser.

        2 fields

        • slugstring

          Category slug, used in categories= filters.

        • namestring

          Display name.

      • statestring or null

        Home state; null for national endorsers.

    • picksarray of Pick

      One pick for vote-for-one, up to N for vote-for-N, the ranking for ranked choice, Yes or No for a measure.

      7 fields

      • choice_idinteger

        The Choice endorsed.

      • labelstring

        That choice’s label.

      • measure_answerstring or null

        yes or no for a measure.

        One of yes, no.
      • rankinteger or null

        Ranked choice: 1 for first choice, 2 for second, …; null otherwise.

      • statementstring or null

        What the endorser said about it.

      • source_urlstring (uri) or null

        Where the endorsement was published.

      • published_onstring (date) or null

        When it was published.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 404 Nothing has that id or slug.
• 429 Over a rate limit. Wait Retry-After seconds.

List endorser categories

GET /v1/endorser-categories

The kinds of endorser (labor, editorial, environment, business, party, club, community, officials), with how many endorsers each has. Use the slugs in categories= filters.

Query parameters

• langstring

  es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise. Names are never translated.

  One of en, es.Default en.

Returns

200 Every category, in display order.

• dataarray of EndorserCategory

  Every item.

  4 fields

  • slugstring

    Category slug, used in categories= filters.

  • namestring

    Display name (plural).

  • singular_namestring

    One of them: “Labor union”.

  • endorser_countinteger

    Endorsers in this category.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 429 Over a rate limit. Wait Retry-After seconds.

List endorsers

GET /v1/endorsers

Endorsers by category, home state, or the elections they’ve endorsed in, or search by name.

Query parameters

• categoriescomma-separated strings

  Category slugs.

  Example labor
• statescomma-separated strings

  Home states (USPS codes), or national.

  Example CA
• electionscomma-separated strings

  Only endorsers with endorsements in these elections.

• qstring

  Name contains (case-insensitive, up to 100 characters).

  Example labor council
• langstring

  es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise. Names are never translated.

  One of en, es.Default en.
• limitinteger

  Results per page, 1–500.

  Default 100.1 to 500.
• cursorstring

  The next_cursor from the previous page.

Returns

200 A page of endorsers, by id.

• dataarray of Endorser

  This page.

  10 fields

  • idinteger

    Endorser id.

  • slugstring

    Endorser slug, used in endorsers= filters and GET /v1/endorsers/{slug}.

  • namestring

    Endorser name.

  • categoryCategory

    The kind of endorser.

    2 fields

    • slugstring

      Category slug, used in categories= filters.

    • namestring

      Display name.

  • descriptionstring or null

    About the endorser.

  • website_urlstring (uri) or null

    Endorser’s website.

  • logo_urlstring (uri) or null

    Logo image.

  • statestring or null

    Home state; null for national endorsers.

  • partyParty or null

    The party, for a party or party club.

    3 fields

    • slugstring

      Party slug.

    • namestring

      Party name.

    • abbreviationstring or null

      Short form as printed, e.g. DEM.

  • endorsement_countinteger

    Endorsements this endorser has made, in every election.

• next_cursorstring or null

  Pass as cursor= for the next page; null on the last page.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 429 Over a rate limit. Wait Retry-After seconds.

Get an endorser

GET /v1/endorsers/{slug}

One endorser, with the elections they’ve endorsed in and how many contests in each.

Path parameters

• slugstringrequired

  Endorser slug.

  Example sf-labor-council

Query parameters

• langstring

  es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise. Names are never translated.

  One of en, es.Default en.

Returns

200 The endorser.

• dataEndorserDetail
  10 fields

  • idinteger

    Endorser id.

  • slugstring

    Endorser slug.

  • namestring

    Endorser name.

  • categoryCategory

    The kind of endorser.

    2 fields

    • slugstring

      Category slug, used in categories= filters.

    • namestring

      Display name.

  • descriptionstring or null

    About the endorser.

  • website_urlstring (uri) or null

    Endorser’s website.

  • logo_urlstring (uri) or null

    Logo image.

  • statestring or null

    Home state; null for national endorsers.

  • partyParty or null

    The party, for a party or party club.

    3 fields

    • slugstring

      Party slug.

    • namestring

      Party name.

    • abbreviationstring or null

      Short form as printed, e.g. DEM.

  • electionsarray of object

    Elections the endorser has endorsed in, newest first.

    4 fields

    • electionstring

      Election slug.

    • namestring

      Election name.

    • datestring (date)

      Election day.

    • contestsinteger

      Contests this endorser took a position in.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 404 Nothing has that id or slug.
• 429 Over a rate limit. Wait Retry-After seconds.

List endorsements

GET /v1/endorsements

Endorsements, one per endorser and choice, each with its endorser, contest (with district and election) and choice. A ranked-choice endorsement of three candidates is three rows with ranks 1–3. This is the way to sync everything, or to catch up after the stream.

Query parameters

• categoriescomma-separated strings

  Endorser category slugs (GET /v1/endorser-categories).

  Example labor
• endorserscomma-separated strings

  Endorser slugs.

  Example sf-labor-council
• endorser_statescomma-separated strings

  Endorsers’ home states (USPS codes), or national for endorsers with none.

  Example CA,national
• electionscomma-separated strings

  Election slugs.

  Example ca-2026-11-03-general
• statescomma-separated strings

  States the contests are voted in (USPS codes).

  Example CA
• contest_kindscomma-separated strings

  Contest kinds.

  One of candidate, measure, retention.Example measure
• levelscomma-separated strings

  District levels.

  One of federal, state, county, city, school, special.Example county,city
• contestinteger

  Only this contest.

  At least 1.Example 4410
• upcomingboolean

  Only elections from yesterday on.

  Default false.
• langstring

  es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise. Names are never translated.

  One of en, es.Default en.
• limitinteger

  Results per page, 1–500.

  Default 100.1 to 500.
• cursorstring

  The next_cursor from the previous page.

Returns

200 A page of endorsements, by id.

• dataarray of Endorsement

  This page.

  8 fields

  • idinteger

    Endorsement id.

  • rankinteger or null

    Ranked choice: the rank the endorser gave; null otherwise.

  • statementstring or null

    What the endorser said.

  • source_urlstring (uri) or null

    Where it was published.

  • published_onstring (date) or null

    When it was published.

  • endorserEndorserRef

    Who made an endorsement.

    5 fields

    • idinteger

      Endorser id.

    • slugstring

      Endorser slug, used in endorsers= filters.

    • namestring

      Endorser name.

    • categoryCategory

      The kind of endorser.

      2 fields

      • slugstring

        Category slug, used in categories= filters.

      • namestring

        Display name.

    • statestring or null

      Home state; null for national endorsers.

  • contestContestBase
    15 fields

    • idinteger

      Contest id.

    • titlestring

      Title as printed on the ballot.

    • short_titlestring or null

      Shorter title.

    • kindstring

      candidate (an office), measure (a proposition) or retention (keep a judge?).

      One of candidate, measure, retention.
    • vote_methodstring

      How votes are cast: plurality (vote for one), multi_seat (vote for up to votes_allowed), ranked_choice (rank up to ranks_allowed), approval, or yes_no.

      One of plurality, multi_seat, ranked_choice, approval, yes_no.
    • votes_allowedinteger or null

      How many choices a voter may mark (vote for N).

    • ranks_allowedinteger or null

      Ranked choice: how many choices a voter may rank.

    • measure_codestring or null

      The measure’s letter or number: “K”, “Prop 1”.

    • descriptionstring or null

      Measure text or question, where the ballot prints one.

    • ballot_orderinteger or null

      Position on the printed ballot.

    • partyParty or null

      For a party primary, the party.

      3 fields

      • slugstring

        Party slug.

      • namestring

        Party name.

      • abbreviationstring or null

        Short form as printed, e.g. DEM.

    • detailsobject

      Facts about the contest. Only keys that apply are present.

      16 fields

      • uncontestedboolean

        Only one candidate is running.

      • nonpartisanboolean

        Candidates appear without a party.

      • measure_typestring

        bond, charter_amendment, initiative, referendum, tax, …

      • vote_requiredstring

        Share of the vote needed to pass, e.g. "2/3" or "55%".

      • majority_requiredboolean

        A candidate needs a majority to win outright (else a runoff).

      • amountnumber

        Dollar amount of a bond or tax measure.

      • termstring

        Length of the term, e.g. "4 years".

      • short_termboolean

        The seat is for the remainder of an unexpired term.

      • justicestring

        The judge or justice a retention question is about.

      • runoff_datestring (date)

        Date of a runoff, if one is needed.

      • stagestring

        Stage of a multi-round contest.

      • elected_at_largeboolean

        Elected by the whole jurisdiction, not by district.

      • none_of_theseboolean

        The ballot offers “None of these candidates” (Nevada).

      • primary_nominatingboolean

        The primary nominates a party’s candidate.

      • winnersinteger

        Number of winners, where it differs from votes_allowed.

      • ref_typestring

        Kind of referendum.

    • source_urlstring (uri) or null

      The official source the contest was loaded from.

    • districtDistrict

      The district a contest is voted in.

      6 fields

      • idinteger

        District id. Matches an officeholder’s district_id.

      • ocd_idstring or null

        Open Civic Data division id, used in districts= filters.

      • namestring

        District name.

      • levelstring

        Level of government.

        One of federal, state, county, city, school, special.
      • typestring

        Kind of district: statewide, congressional, state_upper, state_lower, county, council, school, …

      • statestring or null

        USPS state code.

    • electionElection
      10 fields

      • idinteger

        Election id.

      • slugstring

        Election slug, used in elections= filters: <state>-<date>-<type>.

      • namestring

        Election name.

      • short_namestring or null

        Shorter name.

      • datestring (date)

        Election day.

      • statestring or null

        State; null for a multi-state election.

      • typestring

        Kind of election.

        One of general, primary, special, special_primary, runoff, consolidated.
      • primary_systemstring or null

        How the state runs primaries.

        One of none, closed, semi_closed, open, top_two, nonpartisan.
      • info_urlstring (uri) or null

        Official election page.

      • detailsobject

        Voting rules for the election. Only keys that apply are present.

        11 fields

        • all_mailboolean

          Every voter is mailed a ballot.

        • ranked_choiceboolean

          Some contests in this election use ranked choice voting.

        • fusion_votingboolean

          Candidates can appear on more than one party’s line (New York, Connecticut).

        • partisan_primaryboolean

          A party primary.

        • primarystring

          Which primary, where a state holds several.

        • consolidated_withstring

          Elections held on the same ballot.

        • runoff_datestring (date)

          Date of a runoff, if one is needed.

        • runoff_election_datestring (date)

          Date of the runoff election.

        • top_two_primary_datestring (date)

          Date of the top-two primary that chose these candidates.

        • louisiana_open_primaryboolean

          Louisiana’s open (jungle) primary.

        • notestring

          Anything else voters should know.

  • choiceobject
    8 fields

    • idinteger

      Choice id.

    • labelstring

      As printed.

    • measure_answerstring or null

      yes or no for a measure.

      One of yes, no.
    • optionstring or null

      none_of_these, for that line.

      One of none_of_these.
    • withdrawnboolean

      The candidate withdrew.

    • candidateobject or null

      The candidate; null for a measure answer.

      2 fields

      • idinteger

        Candidate id.

      • full_namestring

        Full name.

    • partyParty or null

      Printed party.

      3 fields

      • slugstring

        Party slug.

      • namestring

        Party name.

      • abbreviationstring or null

        Short form as printed, e.g. DEM.

    • party_labelstring or null

      Party text as printed.

• next_cursorstring or null

  Pass as cursor= for the next page; null on the last page.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 429 Over a rate limit. Wait Retry-After seconds.

List officeholders

GET /v1/officeholders

People in office now, with party, term and contact details. Filter by state, office, level or seat (OCD id). Federal and state offices, and the D.C. Council.

Query parameters

• statescomma-separated strings

  USPS codes.

  Example CA
• officescomma-separated strings

  Offices.

  One of 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.Example us_senator,governor
• levelscomma-separated strings

  Levels.

  One of federal, state, city.Example federal
• districtscomma-separated strings

  OCD division ids of the seats.

  Example ocd-division/country:us/state:ca/sldl:17
• qstring

  Name contains.

• langstring

  es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise. Names are never translated.

  One of en, es.Default en.
• limitinteger

  Results per page, 1–500.

  Default 100.1 to 500.
• cursorstring

  The next_cursor from the previous page.

Returns

200 A page of officeholders.

• dataarray of Officeholder

  This page.

  23 fields

  • person_idstring (uuid)

    Open States person id; stays the same across terms and offices.

  • namestring

    Full name.

  • given_namestring or null

    Given name.

  • family_namestring or null

    Family name.

  • officestring

    The office.

    One of 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.
  • office_titlestring

    Title the state uses: “Assemblymember”, “Delegate”.

  • levelstring

    Level of government.

    One of federal, state, city.
  • statestring

    USPS state code.

  • districtstring or null

    District as the legislature names it: "12", "1A", "21st Middlesex".

  • district_ocd_idstring

    OCD division id of the seat.

  • district_idinteger or null

    The matching contest district id, where there is one.

  • partystring or null

    Party as published: “Democratic”, “Republican/Conservative”.

  • party_abbreviationstring or null

    Party abbreviation.

  • term_startstring (date) or null

    Start of the current term.

  • term_endstring (date) or null

    End of the current term.

  • emailstring (email) or null

    Office email.

  • phonestring or null

    Office phone (capitol office first).

  • website_urlstring (uri) or null

    Official page.

  • image_urlstring (uri) or null

    Official photo.

  • officesarray of object

    Offices with their addresses and phones.

    4 fields

    • classificationstring

      capitol, district, …

    • addressstring

      Mailing address.

    • voicestring

      Phone.

    • faxstring

      Fax.

  • socialobject

    Social accounts, where known.

    4 fields

    • twitterstring

      Handle.

    • facebookstring

      Handle.

    • instagramstring

      Handle.

    • youtubestring

      Handle.

  • source_urlsarray of string (uri)

    Where the data came from.

  • updated_atstring (date-time)

    Last refreshed.

• next_cursorstring or null

  Pass as cursor= for the next page; null on the last page.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 429 Over a rate limit. Wait Retry-After seconds.
• 503 Not ready yet on this server. Wait Retry-After seconds.

Get an officeholder

GET /v1/officeholders/{id}

One officeholder by person_id, with every seat they hold.

Path parameters

• idstring (uuid)required

  The officeholder’s person_id.

  Example 4f6a2c1e-8b3d-4e5f-9a7b-1c2d3e4f5a6b

Query parameters

• langstring

  es for Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English otherwise. Names are never translated.

  One of en, es.Default en.

Returns

200 The officeholder.

• dataOfficeholderDetail
  24 fields

  • person_idstring (uuid)

    Open States person id; stays the same across terms and offices.

  • namestring

    Full name.

  • given_namestring or null

    Given name.

  • family_namestring or null

    Family name.

  • officestring

    The office.

    One of 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.
  • office_titlestring

    Title the state uses: “Assemblymember”, “Delegate”.

  • levelstring

    Level of government.

    One of federal, state, city.
  • statestring

    USPS state code.

  • districtstring or null

    District as the legislature names it: "12", "1A", "21st Middlesex".

  • district_ocd_idstring

    OCD division id of the seat.

  • district_idinteger or null

    The matching contest district id, where there is one.

  • partystring or null

    Party as published: “Democratic”, “Republican/Conservative”.

  • party_abbreviationstring or null

    Party abbreviation.

  • term_startstring (date) or null

    Start of the current term.

  • term_endstring (date) or null

    End of the current term.

  • emailstring (email) or null

    Office email.

  • phonestring or null

    Office phone (capitol office first).

  • website_urlstring (uri) or null

    Official page.

  • image_urlstring (uri) or null

    Official photo.

  • officesarray of object

    Offices with their addresses and phones.

    4 fields

    • classificationstring

      capitol, district, …

    • addressstring

      Mailing address.

    • voicestring

      Phone.

    • faxstring

      Fax.

  • socialobject

    Social accounts, where known.

    4 fields

    • twitterstring

      Handle.

    • facebookstring

      Handle.

    • instagramstring

      Handle.

    • youtubestring

      Handle.

  • source_urlsarray of string (uri)

    Where the data came from.

  • updated_atstring (date-time)

    Last refreshed.

  • seatsarray of Officeholder

    Every seat they hold (rarely more than one).

    23 fields

    • person_idstring (uuid)

      Open States person id; stays the same across terms and offices.

    • namestring

      Full name.

    • given_namestring or null

      Given name.

    • family_namestring or null

      Family name.

    • officestring

      The office.

      One of 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.
    • office_titlestring

      Title the state uses: “Assemblymember”, “Delegate”.

    • levelstring

      Level of government.

      One of federal, state, city.
    • statestring

      USPS state code.

    • districtstring or null

      District as the legislature names it: "12", "1A", "21st Middlesex".

    • district_ocd_idstring

      OCD division id of the seat.

    • district_idinteger or null

      The matching contest district id, where there is one.

    • partystring or null

      Party as published: “Democratic”, “Republican/Conservative”.

    • party_abbreviationstring or null

      Party abbreviation.

    • term_startstring (date) or null

      Start of the current term.

    • term_endstring (date) or null

      End of the current term.

    • emailstring (email) or null

      Office email.

    • phonestring or null

      Office phone (capitol office first).

    • website_urlstring (uri) or null

      Official page.

    • image_urlstring (uri) or null

      Official photo.

    • officesarray of object

      Offices with their addresses and phones.

      4 fields

      • classificationstring

        capitol, district, …

      • addressstring

        Mailing address.

      • voicestring

        Phone.

      • faxstring

        Fax.

    • socialobject

      Social accounts, where known.

      4 fields

      • twitterstring

        Handle.

      • facebookstring

        Handle.

      • instagramstring

        Handle.

      • youtubestring

        Handle.

    • source_urlsarray of string (uri)

      Where the data came from.

    • updated_atstring (date-time)

      Last refreshed.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 404 Nothing has that id or slug.
• 429 Over a rate limit. Wait Retry-After seconds.
• 503 Not ready yet on this server. Wait Retry-After seconds.

Stream endorsement changes (SSE)

GET /v1/stream

Every endorsement change matching a subscription or inline filter, as Server-Sent Events, within seconds of it happening. Events: ready (first, with the subscription name), endorsement (an Event), checkpoint (moves your position past changes your filter skipped), reconnect (we end connections after an hour), and error (cursor_expired). A comment line arrives every 20 seconds.

Each event id is a cursor: reconnect with Last-Event-ID (EventSource does this itself) or ?cursor= to continue. Opening a stream counts as one request; your plan sets how many you can hold open.

Query parameters

• subscriptionstring

  A saved subscription’s id or name, instead of filter parameters.

  Example CA labor
• categoriescomma-separated strings

  Endorser category slugs (GET /v1/endorser-categories).

  Example labor
• endorserscomma-separated strings

  Endorser slugs.

  Example sf-labor-council
• endorser_statescomma-separated strings

  Endorsers’ home states (USPS codes), or national for endorsers with none.

  Example CA,national
• statescomma-separated strings

  States the contests are voted in (USPS codes).

  Example CA
• electionscomma-separated strings

  Election slugs.

  Example ca-2026-11-03-general
• contest_kindscomma-separated strings

  Contest kinds.

  One of candidate, measure, retention.Example measure
• levelscomma-separated strings

  District levels.

  One of federal, state, county, city, school, special.Example county,city
• typescomma-separated strings

  Kinds of change.

  One of created, updated, deleted.Example created,updated
• cursorstring

  Resume after this position: a next_cursor, or an SSE event id. Also read from the Last-Event-ID header.

• fromstring

  Where to start without a cursor.

  One of latest, earliest.Default latest.
• sincestring (date-time)

  Start at changes from this time, within the stream’s retention.

Returns

200 An open event stream.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 404 Nothing has that id or slug.
• 410 The cursor is older than the stream keeps.
• 429 Over a rate limit. Wait Retry-After seconds.
• 503 Not ready yet on this server. Wait Retry-After seconds.

Poll endorsement changes

GET /v1/events

The same changes as the stream, a page at a time. Store next_cursor and send it next time; wait (up to 25 seconds) holds the request open until a matching change arrives. has_more means call again right away.

Query parameters

• subscriptionstring

  A saved subscription’s id or name, instead of filter parameters.

  Example CA labor
• categoriescomma-separated strings

  Endorser category slugs (GET /v1/endorser-categories).

  Example labor
• endorserscomma-separated strings

  Endorser slugs.

  Example sf-labor-council
• endorser_statescomma-separated strings

  Endorsers’ home states (USPS codes), or national for endorsers with none.

  Example CA,national
• statescomma-separated strings

  States the contests are voted in (USPS codes).

  Example CA
• electionscomma-separated strings

  Election slugs.

  Example ca-2026-11-03-general
• contest_kindscomma-separated strings

  Contest kinds.

  One of candidate, measure, retention.Example measure
• levelscomma-separated strings

  District levels.

  One of federal, state, county, city, school, special.Example county,city
• typescomma-separated strings

  Kinds of change.

  One of created, updated, deleted.Example created,updated
• cursorstring

  Resume after this position: a next_cursor, or an SSE event id. Also read from the Last-Event-ID header.

• fromstring

  Where to start without a cursor.

  One of latest, earliest.Default latest.
• sincestring (date-time)

  Start at changes from this time, within the stream’s retention.

• limitinteger

  Events per page, 1–1000.

  Default 100.1 to 1000.
• waitinteger

  Seconds to wait for a change (long polling).

  Default 0.0 to 25.Example 20

Returns

200 Events and the next cursor.

• dataarray of Event

  Changes, oldest first.

  8 fields

  • idstring

    The change’s id: increasing and unique. Use it to drop repeats.

  • typestring

    What happened.

    One of endorsement.created, endorsement.updated, endorsement.deleted.
  • occurred_atstring (date-time)

    When the change was made.

  • endorsementobject
    5 fields

    • idinteger

      Endorsement id.

    • rankinteger or null

      Ranked choice rank.

    • statementstring or null

      What the endorser said.

    • source_urlstring or null

      Where it was published.

    • published_onstring (date) or null

      When.

  • endorserobject
    5 fields

    • idinteger

      Endorser id.

    • slugstring or null

      Endorser slug.

    • namestring or null

      Endorser name.

    • categoryCategory or null

      Category.

      2 fields

      • slugstring

        Category slug, used in categories= filters.

      • namestring

        Display name.

    • statestring or null

      Home state, or null for national.

  • contestobject
    9 fields

    • idinteger

      Contest id.

    • titlestring or null

      Title.

    • short_titlestring or null

      Short title.

    • kindstring or null

      candidate, measure or retention.

    • vote_methodstring or null

      Vote method.

    • votes_allowedinteger or null

      Vote for N.

    • ranks_allowedinteger or null

      Ranks allowed.

    • measure_codestring or null

      Measure code.

    • districtobject or null

      District.

      5 fields

      • idinteger

        District id.

      • namestring

        Name.

      • levelstring

        Level.

      • ocd_idstring or null

        OCD id.

      • statestring or null

        State.

  • electionobject or null

    Election.

    6 fields

    • idinteger

      Election id.

    • slugstring

      Slug.

    • namestring

      Name.

    • datestring (date)

      Date.

    • statestring or null

      State.

    • typestring

      Type.

  • choiceobject
    6 fields

    • idinteger

      Choice id.

    • labelstring or null

      As printed.

    • measure_answerstring or null

      yes or no.

      One of yes, no.
    • candidateobject or null

      Candidate.

      2 fields

      • idinteger

        Candidate id.

      • full_namestring

        Full name.

    • partyobject or null

      Party.

      2 fields

      • slugstring

        Slug.

      • namestring

        Name.

    • withdrawnboolean or null

      Withdrawn.

• next_cursorstring

  Send as cursor= next time.

• has_moreboolean

  More are waiting: call again now.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 404 Nothing has that id or slug.
• 410 The cursor is older than the stream keeps.
• 429 Over a rate limit. Wait Retry-After seconds.
• 503 Not ready yet on this server. Wait Retry-After seconds.

List subscriptions

GET /v1/subscriptions

Your account’s saved subscriptions, by name.

Returns

200 Every subscription.

• dataarray of Subscription

  Every item.

  5 fields

  • idinteger

    Subscription id.

  • namestring

    Name, unique in your account.

  • filterFilter

    Which endorsements: fields combine with AND, values within a field with OR, and a missing field matches everything. Each field takes at most 500 values.

    8 fields

    • categoriesarray of string

      Endorser category slugs (GET /v1/endorser-categories).

    • endorsersarray of string

      Endorser slugs.

    • endorser_statesarray of string

      Endorsers’ home states (USPS codes), or "national".

    • statesarray of string

      States the contests are voted in.

    • electionsarray of string

      Election slugs.

    • contest_kindsarray of string

      Contest kinds.

      One of candidate, measure, retention.
    • levelsarray of string

      District levels.

      One of federal, state, county, city, school, special.
    • typesarray of string

      Stream only: kinds of change.

      One of created, updated, deleted.
  • created_atstring (date-time)

    Created.

  • updated_atstring (date-time)

    Last changed.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 429 Over a rate limit. Wait Retry-After seconds.

Create a subscription

POST /v1/subscriptions

Save a named filter. Use it as subscription=<id or name> on /v1/stream and /v1/events. An account can have up to 50.

Request body

JSON.

• namestring

  1–100 letters, digits, spaces, dots, dashes or underscores.

• filterFilter

  Which endorsements: fields combine with AND, values within a field with OR, and a missing field matches everything. Each field takes at most 500 values.

  8 fields

  • categoriesarray of string

    Endorser category slugs (GET /v1/endorser-categories).

  • endorsersarray of string

    Endorser slugs.

  • endorser_statesarray of string

    Endorsers’ home states (USPS codes), or "national".

  • statesarray of string

    States the contests are voted in.

  • electionsarray of string

    Election slugs.

  • contest_kindsarray of string

    Contest kinds.

    One of candidate, measure, retention.
  • levelsarray of string

    District levels.

    One of federal, state, county, city, school, special.
  • typesarray of string

    Stream only: kinds of change.

    One of created, updated, deleted.

Returns

201 Created.

• dataSubscription
  5 fields

  • idinteger

    Subscription id.

  • namestring

    Name, unique in your account.

  • filterFilter

    Which endorsements: fields combine with AND, values within a field with OR, and a missing field matches everything. Each field takes at most 500 values.

    8 fields

    • categoriesarray of string

      Endorser category slugs (GET /v1/endorser-categories).

    • endorsersarray of string

      Endorser slugs.

    • endorser_statesarray of string

      Endorsers’ home states (USPS codes), or "national".

    • statesarray of string

      States the contests are voted in.

    • electionsarray of string

      Election slugs.

    • contest_kindsarray of string

      Contest kinds.

      One of candidate, measure, retention.
    • levelsarray of string

      District levels.

      One of federal, state, county, city, school, special.
    • typesarray of string

      Stream only: kinds of change.

      One of created, updated, deleted.
  • created_atstring (date-time)

    Created.

  • updated_atstring (date-time)

    Last changed.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 409 A subscription with that name already exists.
• 429 Over a rate limit. Wait Retry-After seconds.

Get a subscription

GET /v1/subscriptions/{id}

One saved subscription.

Path parameters

• idintegerrequired

  Subscription id.

  Example 7

Returns

200 The subscription.

• dataSubscription
  5 fields

  • idinteger

    Subscription id.

  • namestring

    Name, unique in your account.

  • filterFilter

    Which endorsements: fields combine with AND, values within a field with OR, and a missing field matches everything. Each field takes at most 500 values.

    8 fields

    • categoriesarray of string

      Endorser category slugs (GET /v1/endorser-categories).

    • endorsersarray of string

      Endorser slugs.

    • endorser_statesarray of string

      Endorsers’ home states (USPS codes), or "national".

    • statesarray of string

      States the contests are voted in.

    • electionsarray of string

      Election slugs.

    • contest_kindsarray of string

      Contest kinds.

      One of candidate, measure, retention.
    • levelsarray of string

      District levels.

      One of federal, state, county, city, school, special.
    • typesarray of string

      Stream only: kinds of change.

      One of created, updated, deleted.
  • created_atstring (date-time)

    Created.

  • updated_atstring (date-time)

    Last changed.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 404 Nothing has that id or slug.
• 429 Over a rate limit. Wait Retry-After seconds.

Replace a subscription

PUT /v1/subscriptions/{id}

Replace a subscription’s name and filter. Open streams using it keep their old filter until they reconnect.

Path parameters

• idintegerrequired

  Subscription id.

  Example 7

Request body

JSON.

• namestring

  1–100 letters, digits, spaces, dots, dashes or underscores.

• filterFilter

  Which endorsements: fields combine with AND, values within a field with OR, and a missing field matches everything. Each field takes at most 500 values.

  8 fields

  • categoriesarray of string

    Endorser category slugs (GET /v1/endorser-categories).

  • endorsersarray of string

    Endorser slugs.

  • endorser_statesarray of string

    Endorsers’ home states (USPS codes), or "national".

  • statesarray of string

    States the contests are voted in.

  • electionsarray of string

    Election slugs.

  • contest_kindsarray of string

    Contest kinds.

    One of candidate, measure, retention.
  • levelsarray of string

    District levels.

    One of federal, state, county, city, school, special.
  • typesarray of string

    Stream only: kinds of change.

    One of created, updated, deleted.

Returns

200 Saved.

• dataSubscription
  5 fields

  • idinteger

    Subscription id.

  • namestring

    Name, unique in your account.

  • filterFilter

    Which endorsements: fields combine with AND, values within a field with OR, and a missing field matches everything. Each field takes at most 500 values.

    8 fields

    • categoriesarray of string

      Endorser category slugs (GET /v1/endorser-categories).

    • endorsersarray of string

      Endorser slugs.

    • endorser_statesarray of string

      Endorsers’ home states (USPS codes), or "national".

    • statesarray of string

      States the contests are voted in.

    • electionsarray of string

      Election slugs.

    • contest_kindsarray of string

      Contest kinds.

      One of candidate, measure, retention.
    • levelsarray of string

      District levels.

      One of federal, state, county, city, school, special.
    • typesarray of string

      Stream only: kinds of change.

      One of created, updated, deleted.
  • created_atstring (date-time)

    Created.

  • updated_atstring (date-time)

    Last changed.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 404 Nothing has that id or slug.
• 409 A subscription with that name already exists.
• 429 Over a rate limit. Wait Retry-After seconds.

Delete a subscription

DELETE /v1/subscriptions/{id}

Delete a subscription.

Path parameters

• idintegerrequired

  Subscription id.

  Example 7

Returns

204 Deleted. No body.

Errors

• 400 A parameter is missing or not valid.
• 401 No API key, or one that isn’t valid, was revoked or expired.
• 403 The key can’t be used for this: a missing scope, an IP allowlist, an account not yet approved, or data the account hasn’t bought.
• 404 Nothing has that id or slug.
• 429 Over a rate limit. Wait Retry-After seconds.