An election records the vote for one committee’s seats, including its name, level, status, positions, candidates, measures, and voting dates. You cannot create or maintain elections in the Console or Portal today. To manage them, you call the Rhythm API directly, so this article is for implementers.
Prerequisites
- You are signed in as staff of your Rhythm account. A Portal member’s sign-in is refused.
- The committee for the election already exists in the Committees application. Creating an election does not create a committee.
Routes
| Method and path | Purpose |
|---|---|
POST /elections/{tenantId} | Create an election |
PUT /elections/{tenantId}/{id} | Replace an election’s full record |
PATCH /elections/{tenantId}/{id} | Change part of an election’s record |
DELETE /elections/{tenantId}/{id} | Delete an election |
Creating an Election
Send the committee, name, type, and status. Rhythm generates the election’s identifier, so you cannot choose it.
| Field | Required | Notes |
|---|---|---|
committee_id | Yes | The committee holding the election. It must exist and be readable, or the save fails. Rhythm replaces spaces with dashes when it generates a committee’s ID, but a committee ID edited by hand afterward can still contain spaces. Avoid that because it can break integrations, including this API, that expect the usual ID format. Committee ID generation now favors a value close to the committee’s name instead of an opaque, unique-looking identifier, so do not assume an ID will look like a random string. |
name | Yes | Free text. |
type | Yes | One of national, chapter, or section. |
status | Yes | One of draft, active, certified, or cancelled. |
chapter_id, section_id | No | Rhythm ignores these when you save; see below. |
positions[], candidates, measures[] | No | The seats and, for a measures election, the yes-or-no questions. Rhythm does not check these lists for duplicates or internal consistency. |
open_date, close_date | Conditionally required | ISO 8601 dates; see Voting Window Requirements. |
A new election does not have to start as a draft. Rhythm accepts a create request with a status of active, certified, or cancelled when the request also includes both voting dates.
Chapter and Section Follow the Committee
Rhythm copies an election’s chapter_id and section_id from its committee every time you save the election, whether you are creating it or editing it later. If you send a different chapter or section, Rhythm silently replaces it with the committee’s own value and does not return a message about the change.
A chapter-type election also requires its committee to belong to both a chapter and a section. If the committee has no section, Rhythm refuses the save. A section-type election does not have the same requirement: you can save it with no section if its committee has none, and it will not appear in any section-scoped listing.
If Rhythm cannot read the committee because it does not exist or the Committees application does not answer, the election save fails with a server error instead of a specific “committee not found” message.
Voting Window Requirements
Every election with a status other than draft must include both open_date and close_date as ISO 8601 dates. This rule applies every time you save, including an edit that would remove a date from an election that is already active.
In any status, when both dates are present, close_date cannot come before open_date. Rhythm refuses a window that fails this check with the message Open date must come after close date. The message names the wrong field, so read it as “closing date must come after opening date.”
Elections and Ballots Must Point to Real Records
You cannot save an election if it names a committee, position, or candidate that does not exist. You also cannot save a ballot if it names an election, voter, position, or candidate that does not exist. Rhythm checks only that these records exist; it does not check that they match each other. For example, a ballot can name a position that is not part of the election it votes in.
Rhythm also blocks deletion in the other direction. You cannot delete a committee, position, contact, or election from its own application while any election or ballot still refers to it. The refusal tells you how many records depend on it, but not which records they are, so you may need to search for the referring elections or ballots yourself.
Edit an Election
Editing runs the same checks as creating. Rhythm re-reads the committee, re-copies its chapter and section, applies the voting-window rules again, and checks every reference again. You cannot change the election’s own identifier.
An election’s status does not freeze any of its fields. You can still change a certified election’s candidates, counts, and status through the same edit operation, so editing an election, correcting its result, and certifying it are not separate actions.
Delete an Election
You can delete an election only when no ballot names it. If any ballot refers to the election, Rhythm refuses the delete and reports how many ballots depend on it, without naming them. Delete or reassign those ballots first. Deletion is permanent, with no cascade to ballots and no restore.
An election that was just deleted keeps its identifier reserved for up to an hour before a new record could reuse it.
Errors
| Response | Cause |
|---|---|
400 ObjectInvalid: … | A required field is missing or invalid, including a status that is not in the allowed list. |
400 … Open date must come after close date | The closing date is earlier than the opening date. |
409 ForeignKeyViolation | The election names a position or candidate that does not exist. |
500 | Rhythm could not read the committee named by committee_id, or a delete is refused because elections or ballots still refer to the record. |
404 | The election named in the path does not exist in your account. |
Related
- Look Up Elections Through the API
- Record and Manage Ballots Through the API
- How Elections and Ballots Work