Endorsement Stream docs
Getting started with the Endorsement Stream
The Endorsement Stream sends you every endorsement as endorsers publish it, and every change after: added, updated or withdrawn. Each one is tied to the choice on the printed ballot, with its contest, endorser and source. You choose how it arrives. To query the data yourself instead, see the API docs.
Start receiving endorsements
- Buy an endorsements plan at ballotdata.ai: one contest or measure, whole states, or national. It runs through December 31, 2027, and doesn’t renew.
- At checkout, pick how you’d like it delivered (below) and, if you like, only some kinds of endorsers (labor, newspapers, parties…). For the live stream, also choose your API account’s password there.
- Once you’ve paid, deliveries start. Sign in to your ballotdata.ai account with an emailed link to change the delivery any time, get your private file link or postback secret, and see what was sent.
Ways to receive it
| Way | What you get | Format | You need |
|---|---|---|---|
| Live stream (Server-Sent Events) | Each change, the moment it publishes | JSON events | An API key |
| Polling | The changes since your last cursor, on your schedule | JSON | An API key |
| Email, each change | One email per change, as it happens | CSV or JSON attached | An address |
| Email, hourly summary | The hour’s changes, only when something changed | CSV or JSON attached | An address |
| Email, daily summary | That day’s changes | CSV or JSON attached | An address |
| CSV or JSON downloads | The complete file, rebuilt every day | CSV or JSON | A private link |
| Signed postbacks | Each batch of changes POSTed to your server | Signed JSON | An HTTPS endpoint |
Every way carries the same endorsements with the same ids as the API, so a file load, the emails and the stream stay in step. The fields are described in Formats and fields.
Your first delivery
- Live stream or polling: confirm your email from the message the API sends, sign in, create a key with
stream:read, and connect:curl -N -H "Authorization: Bearer ebk_…" "https://api.ballotdata.ai/v1/stream?from=latest"
Our client libraries for JavaScript and Python read the stream for you and resume where they stopped. - Email: nothing to set up. The first email goes out with the first change (or, for a daily summary, at the next 13:00 UTC).
- Downloads: create a private link in your account, then fetch it from a script:
curl -fL -o endorsements.csv https://ballotdata.ai/files/bdf_your_private_token
- Postbacks: enter your HTTPS endpoint at checkout, copy the signing secret from your account and check each request’s signature.
How fresh it is
New and changed endorsements generally publish within the hour of an endorser announcing them. The live stream, polling, change emails and postbacks carry them as they publish; hourly and daily emails summarize them; and the complete file is rebuilt every day at 13:00 UTC. Withdrawn endorsements are sent as changes and disappear from the next day’s file.
In the Endorsement Stream docs
- Live stream (SSE and polling)
Every change the moment it publishes, over Server-Sent Events or by polling with a cursor.
- Email
Each change as it happens, or an hourly or daily summary, with a CSV or JSON of the changes.
- CSV and JSON downloads
The complete file, rebuilt daily, from your account or a private link.
- Signed postbacks
Changes POSTed to your server as signed JSON, and how to check the signature.
- Formats and fields
The CSV columns, the JSON layout, change files and identifiers.
- Stream API reference
The stream, polling and subscription endpoints, their parameters and their responses.
Need something else?
A different format, SFTP, S3, a spreadsheet you share with us: choose “Something else” at checkout, write to sales@ballotdata.ai or use the contact form.