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) ormultiple(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.
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
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:
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
PATCH /api/v1/vote_options/{id}:
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: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 islive, 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 atdateEnd. To end it early:
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: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:isArchived, or exists[isArchived]).
Cloning for the next cycle
To run the same election again, clone instead of rebuilding:Common gotchas
The eligible count is lower than expected
The eligible count is lower than expected
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.A voter says they didn't get the notification
A voter says they didn't get the notification
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.
Can a member change their vote?
Can a member change their vote?
No. A ballot is final: a second attempt answers
400 Already voted. Plan for this in your instructions to voters.The vote needs a quorum: how do I enforce it?
The vote needs a quorum: how do I enforce it?
There is no quorum gate. After closing, compare
totalVoted with totalEligible (or read participationPercentage) against your bylaws before treating the result as binding.How are ties broken?
How are ties broken?
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
- Permissions: which roles can create and manage votes
- E-voting: the admin-side documentation
- Handle webhooks: react to member and attendance changes around a vote

