Skip to main content
This walkthrough runs an end-to-end e-voting session: board elections, by-law changes, motion votes. It uses the VoteCollection, Vote and VoteOption resources. Who is this for: governance automation that spins up scheduled votes (annual board elections, motion ratification), or integrations that copy vote outcomes back into a federation’s records. Creating and managing votes needs chapter HR rights or being the vote’s owner. For admin-side screens, see E-voting.

Concepts

  • A VoteCollection is one voting session: one meeting, one ratification cycle, one election. It groups one or more questions.
  • A Vote is a single question, such as “Elect the treasurer”. Each has a type: single (one option) or multiple (several options).
  • A VoteOption is one answer to a question.
  • A ballot is anonymous (isAnonymous: true) or attributed (each ballot is tied to the voter, for votes where the record of who voted how must be kept). Anonymity is chosen up front.
  • A member can vote once. There is no changing a vote after it is cast.
A collection’s status is computed, not set by you: draft, upcoming (published, before dateStart), live (open now), closed, or empty (open period over with no votes).

Step 1: Create the vote collection

The new collection is a draft and comes with one default question and two default answer options, which you rename or extend in step 2. The response includes totalEligible, isEditable, status and isDraft.

Who can vote

The eligible voters follow how the collection is scoped: For a private vote, add voters while the collection is still editable, one at a time or in bulk:
The bulk call takes up to 50 members of the organization, skips those already on the list, and returns the number added and the new eligible total. A single voter is POST /api/v1/vote_users with {"voteCollection": "/api/v1/vote_collections/22", "user": "/api/v1/users/42"}.

Optional settings

hideVotersList hides who has voted from other members. hasPreliminaryResults lets voters see running results while the vote is live; otherwise results appear only after it closes.

Step 2: Add questions and options

A new question starts with two default options. Add the rest, and rename the defaults with PATCH /api/v1/vote_options/{id}:
Repeat for each candidate (Emma Whitfield, Sarah O’Connor, Michael Chen, Olivia Brown). Reorder questions with PATCH /api/v1/vote_collections/{id}/reorder-questions and options with PATCH /api/v1/votes/{id}/reorder-options. There are no ranked-choice or free-text question types. Questions and options can only be changed while the collection is editable: no ballot cast yet, and not yet live or closed. Once voting starts they are locked.

Step 3: Publish

When the questions are in place:
Publishing checks the dates and scope, then emails the eligible voters and moves the collection to upcoming (or straight to live if dateStart has passed). Publishing twice answers 400 Voting is already published. Until voting starts you can still edit the collection. There is no separate “open” call: voting opens by itself at dateStart.

Step 4: Members vote

While the collection is live, each eligible member casts one ballot that answers every question at once:
voteOptions maps each question id to the chosen option id (for a single question) or a list of option ids (for multiple). Leaving a question out answers 400 Please answer all questions. The ballot is cast as the signed-in member, so this is called with the member’s session, not an admin token. Typical refusals, all 400: This voting did not started yet, This voting ended, You are not eligible for this vote., You are not set as eligible for this vote by the admin., and Already voted. The answer is a seal (an integrity token over the ballot). GET /api/v1/has_live_votes tells the signed-in member whether there is an open vote they can take part in, which is handy for an “unfinished vote” badge.

Step 5: Close and read the results

Voting closes by itself at dateEnd. To end it early:
The collection must be published and currently open. Results are then available on the collection:
Counts are raw option totals. Results are only shown (hasAvailableResults) after closing, or while live when hasPreliminaryResults is on. For an attributed (non-anonymous) vote, owners can read who voted how: GET /api/v1/vote_collections/{id}/attributed-results, and export it with .../attributed-export.

Step 6: Export

For board minutes or compliance, export the result set as CSV once the vote has closed:
The file lists the questions and answers with the cryptographic seals recorded for audit. Exporting an unfinished vote answers 403 Vote must be finished to export results. The voter roster (who voted, not how) is GET /api/v1/vote_collections/{id}/voters-export.

Step 7: Archive

When the results are circulated and the minutes signed:
Only a closed collection can be archived. Archived collections stay readable; the list endpoint can filter on them (isArchived, or exists[isArchived]).

Cloning for the next cycle

To run the same election again, clone instead of rebuilding:
The clone is a new draft that copies the questions, options and eligible voters, with fresh dates (from now to one hour later) and no results. Update the name, dates and candidates, then publish it as in step 3. For a vote attached to an event, only the event’s owner can clone it.

Common gotchas

Eligibility follows the scope table above. For a vote on a local center or group, only members in it count, and only active members. For a private vote, only people on the voter list count. Check totalEligible before publishing.
Publishing emails the eligible voters, so a voter without a usable email address is not reached. They can still vote from the member dashboard while the vote is live.
No. A ballot is final: a second attempt answers 400 Already voted. Plan for this in your instructions to voters.
There is no quorum gate. After closing, compare totalVoted with totalEligible (or read participationPercentage) against your bylaws before treating the result as binding.
Orgo reports raw totals. Tie-breaking is a governance decision. For a runoff, clone the collection, keep only the tied candidates, and run it again.

What to do next