Stream event
One endorsement change as the Endorsement Stream delivers it, by Server-Sent Events, polling, email, file or postback.
- Returned by
GET /v1/stream,GET /v1/events
How it connects
- The same changes as
GET /v1/changes, with more of the contest and choice in each one.
Good to know
idincreases and is unique: use it to drop an event you have already seen.
Fields
| Field | Type | Meaning | Example |
|---|---|---|---|
id | string | The change’s id: increasing and unique. Use it to drop repeats. | 18342 |
type | string | What happened: an endorsement created, updated or deleted.endorsement.created, endorsement.updated, endorsement.deleted meanings | endorsement.created |
occurred_at | stringISO 8601 date and time with time zone | When the change was made. | 2026-10-14T21:07:33.512Z |
endorsement | object | The endorsement as it is now (for endorsement.deleted, as it was). | — |
endorsement.id | integer | Endorsement id. | 90211 |
endorsement.rank | integeror null | Ranked choice: the rank the endorser gave; null otherwise. | 1 |
endorsement.statement | stringor null | What the endorser said. | — |
endorsement.source_url | stringor nullURL | Where it was published. | https://sflaborcouncil.org/endorsements |
endorsement.published_on | stringor nullYYYY-MM-DD | When it was published. | 2026-09-18 |
endorsement.added_by | string | How the endorsement got here: automatic (added by our automatic watch of the endorser’s own page), staff (entered by hand by BallotData staff) or data_load (loaded in a researched data pass).automatic, staff, data_load meanings | data_load |
changed | array of string | For endorsement.updated: the fields that changed. Empty for other events.choice_id, rank, statement, source_url, published_on meanings | — |
previous | objector null | For endorsement.updated: the values before the change. null for other events. | — |
previous.choice_id | integer | The choice endorsed before. | — |
previous.rank | integeror null | The rank before. | — |
previous.statement | stringor null | The statement before. | — |
previous.source_url | stringor nullURL | The source URL before. | — |
previous.published_on | stringor nullYYYY-MM-DD | The publication date before. | — |
endorser | object | Who made the endorsement. | — |
endorser.id | integer | Endorser id. | 512 |
endorser.slug | stringor null | Endorser slug; null if the endorser has since been removed. | sf-labor-council |
endorser.name | stringor null | Endorser name; null if the endorser has since been removed. | San Francisco Labor Council |
endorser.category | Endorser categoryor null | The endorser’s category. | — |
endorser.state | stringor null | Home state, or null for a national endorser. | CA |
contest | object | The contest. | — |
contest.id | integer | Contest id. | 4410 |
contest.title | stringor null | Title as printed on the ballot. | Member, Board of Supervisors, District 8 |
contest.short_title | stringor null | Shorter title. | Supervisor, D8 |
contest.kind | stringor null | candidate (an office), measure (a proposition) or retention (keep a judge?).candidate, measure, retention meanings | candidate |
contest.vote_method | stringor null | How votes are cast.plurality, multi_seat, ranked_choice, approval, yes_no meanings | ranked_choice |
contest.votes_allowed | integeror null | How many choices a voter may mark (vote for N). | 1 |
contest.ranks_allowed | integeror null | Ranked choice: how many choices a voter may rank. | 10 |
contest.measure_code | stringor null | The measure’s letter or number. | — |
contest.district | objector null | The district the contest is voted in. | — |
contest.district.id | integer | District id. | 77 |
contest.district.name | string | District name. | San Francisco Supervisorial District 8 |
contest.district.level | string | Level of government.federal, state, county, city, school, special meanings | county |
contest.district.ocd_id | stringor null | Open Civic Data division id. | ocd-division/country:us/state:ca/county:san_francisco/council_district:8 |
contest.district.state | stringor null | USPS state code. | CA |
election | objector null | The contest’s election. | — |
election.id | integer | Election id. | 3 |
election.slug | string | Election slug. | ca-2026-11-03-general |
election.name | string | Election name. | California General Election |
election.date | stringYYYY-MM-DD | Election day. | 2026-11-03 |
election.state | stringor null | USPS state code; null for a multi-state election. | CA |
election.type | string | Kind of election.general, primary, special, special_primary, runoff, consolidated meanings | general |
choice | object | The choice endorsed. | — |
choice.id | integer | Choice id. | 20931 |
choice.label | stringor null | As printed: the candidate’s ballot name, or Yes / No. | Jane Doe |
choice.measure_answer | stringor null | yes or no for a measure; null for a candidate.yes, no meanings | — |
choice.candidate | objector null | The candidate; null for a measure answer. | — |
choice.candidate.id | integer | Candidate id. | 8811 |
choice.candidate.full_name | string | Full name. | Jane Doe |
choice.party | objector null | The party printed beside the name. | — |
choice.party.slug | string | Party slug. | — |
choice.party.name | string | Party name. | — |
choice.withdrawn | booleanor null | The candidate withdrew but is still printed on the ballot. | false |
choice.incumbent | booleanor null | The candidate holds this seat now: true or false where we know, null where we don’t (and for a measure answer). | true |