Change a DRAFT election in the connected account: title, description, organization name, schedule and time zone, secret ballot, results visibility, quorum, and the ballot (add, remove or change questions, or replace them all). While nobody has paid for it, its state, community type, vote type and verification can change too. Fields mean what they mean in create_election_draft. Changes go through the election editor, so anything the election page would refuse is refused with its reason and nothing is half-changed where that can be checked first. Returns one plain sentence per change, written from the saved election, and what still blocks publishing. A published election is changed by the organizer on its page.
View input schema
{
"type": "object",
"properties": {
"election": {
"type": "string",
"description": "The draft's id or slug."
},
"patch": {
"type": "object",
"description": "Only the fields to change; every field means what it means in create_election_draft. At least one field.",
"minProperties": 1,
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"description": "Election title voters see, e.g. \"2026 Board of Directors Election\"."
},
"description": {
"type": "string",
"description": "Instructions or background shown above the ballot. Plain text; an empty string removes it."
},
"organization_name": {
"type": "string",
"description": "Association name shown to voters and used as the email sender name. Defaults to the account's organization."
},
"opens_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When voting opens, ISO 8601 with offset. null opens voting when the election is published."
},
"closes_at": {
"type": "string",
"format": "date-time",
"description": "When voting closes, ISO 8601 with offset, e.g. 2026-11-12T17:00:00-07:00. Must be in the future. Leave it out when nobody said: voting then closes at 5pm in `timezone` seven days from today, and the result says the exact time so it can be relayed and changed."
},
"timezone": {
"type": "string",
"description": "IANA timezone of the association, e.g. America/Denver. Voters see times in it."
},
"verification": {
"type": "string",
"enum": [
"email",
"email_or_sms"
],
"description": "email: every voter confirms a code sent to their email (included free). email_or_sms: voters may also confirm by text message (paid elections only; elections of 25 voters or fewer are email-only)."
},
"secret_ballot": {
"type": "boolean",
"description": "Keep who voted for what private from the organizer. Defaults to true."
},
"results": {
"type": "string",
"enum": [
"after_close",
"live",
"owner_only"
],
"description": "after_close (default): voters see results once voting closes. live: running totals while voting is open. owner_only: only the organizer sees results."
},
"quorum": {
"type": [
"object",
"null"
],
"description": "The quorum: {type: \"percentage\" | \"count\", threshold}. null removes it.",
"properties": {
"type": {
"type": "string",
"enum": [
"percentage",
"count"
]
},
"threshold": {
"type": "integer",
"minimum": 1
}
},
"required": [
"type",
"threshold"
]
},
"state": {
"type": "string",
"description": "Two-letter US state code of the association (e.g. CA). Turns on that state's election-law checks before publishing."
},
"community_type": {
"type": "string",
"enum": [
"hoa",
"condo"
],
"description": "hoa or condo, when the state rules differ between them."
},
"vote_type": {
"type": "string",
"enum": [
"board_election",
"budget",
"amendment",
"resolution",
"custom"
],
"description": "What the vote decides, for the state-law checks."
},
"questions": {
"type": "object",
"description": "Changes to the ballot. set replaces every question and is sent on its own; otherwise remove, update and add run in that order. Positions count from 1, as the ballot stood before this change.",
"minProperties": 1,
"additionalProperties": false,
"properties": {
"set": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "The whole ballot, in order, replacing every question on it.",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "The question or race, e.g. \"Elect three directors\"."
},
"description": {
"type": "string",
"description": "Optional help text under the question."
},
"type": {
"type": "string",
"enum": [
"single_choice",
"multiple_choice",
"yes_no",
"ranked_choice",
"approval",
"cumulative",
"open_text"
],
"description": "single_choice: pick one. multiple_choice: pick up to `seats` (a multi-seat board race). yes_no: approve or reject a motion (Yes/No options are added automatically). ranked_choice: rank candidates; instant runoff for one seat, single transferable vote when seats > 1. approval: approve any number of candidates. cumulative: each voter spreads `seats` votes (minimum 2) across candidates, used where bylaws require cumulative voting. open_text: a written answer."
},
"options": {
"type": "array",
"description": "Candidates or choices; required (at least 2) for every type except yes_no and open_text. A string, or {text, description} to include a candidate statement.",
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"text": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"text"
]
}
]
}
},
"seats": {
"type": "integer",
"minimum": 1,
"description": "How many winners (board seats). multiple_choice: the \"vote for up to N\" limit. ranked_choice/approval/cumulative: seats to fill."
},
"allow_write_in": {
"type": "boolean",
"description": "Let voters write in one candidate (single_choice, multiple_choice, approval, cumulative)."
},
"include_abstain": {
"type": "boolean",
"description": "Add an \"Abstain\" choice that counts toward turnout but never wins (yes_no, single_choice, multiple_choice, approval)."
},
"required": {
"type": "boolean",
"description": "Whether a voter must answer. Defaults to true, except open_text."
}
},
"required": [
"text",
"type"
]
}
},
"add": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "New questions, added after the last one, in this order.",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "The question or race, e.g. \"Elect three directors\"."
},
"description": {
"type": "string",
"description": "Optional help text under the question."
},
"type": {
"type": "string",
"enum": [
"single_choice",
"multiple_choice",
"yes_no",
"ranked_choice",
"approval",
"cumulative",
"open_text"
],
"description": "single_choice: pick one. multiple_choice: pick up to `seats` (a multi-seat board race). yes_no: approve or reject a motion (Yes/No options are added automatically). ranked_choice: rank candidates; instant runoff for one seat, single transferable vote when seats > 1. approval: approve any number of candidates. cumulative: each voter spreads `seats` votes (minimum 2) across candidates, used where bylaws require cumulative voting. open_text: a written answer."
},
"options": {
"type": "array",
"description": "Candidates or choices; required (at least 2) for every type except yes_no and open_text. A string, or {text, description} to include a candidate statement.",
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"text": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"text"
]
}
]
}
},
"seats": {
"type": "integer",
"minimum": 1,
"description": "How many winners (board seats). multiple_choice: the \"vote for up to N\" limit. ranked_choice/approval/cumulative: seats to fill."
},
"allow_write_in": {
"type": "boolean",
"description": "Let voters write in one candidate (single_choice, multiple_choice, approval, cumulative)."
},
"include_abstain": {
"type": "boolean",
"description": "Add an \"Abstain\" choice that counts toward turnout but never wins (yes_no, single_choice, multiple_choice, approval)."
},
"required": {
"type": "boolean",
"description": "Whether a voter must answer. Defaults to true, except open_text."
}
},
"required": [
"text",
"type"
]
}
},
"remove": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Questions to take off the ballot. A ballot keeps at least one question.",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"position": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "The question's place on the ballot as it stood before this change: 1 is the first."
}
},
"required": [
"position"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The question's id, from get_election."
}
},
"required": [
"id"
],
"additionalProperties": false
}
]
}
},
"update": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Questions to change, one entry each. Wording, help text, required, seats and write-ins change in place; a new type, new options or the Abstain choice rebuilds the question in the same place.",
"items": {
"type": "object",
"description": "Name the question by position or by id (not both), then give only the fields to change.",
"additionalProperties": false,
"properties": {
"position": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "The question's place on the ballot as it stood before this change: 1 is the first."
},
"id": {
"type": "string",
"format": "uuid",
"description": "The question's id, from get_election."
},
"text": {
"type": "string",
"description": "The question or race, e.g. \"Elect three directors\"."
},
"description": {
"type": "string",
"description": "Optional help text under the question."
},
"type": {
"type": "string",
"enum": [
"single_choice",
"multiple_choice",
"yes_no",
"ranked_choice",
"approval",
"cumulative",
"open_text"
],
"description": "single_choice: pick one. multiple_choice: pick up to `seats` (a multi-seat board race). yes_no: approve or reject a motion (Yes/No options are added automatically). ranked_choice: rank candidates; instant runoff for one seat, single transferable vote when seats > 1. approval: approve any number of candidates. cumulative: each voter spreads `seats` votes (minimum 2) across candidates, used where bylaws require cumulative voting. open_text: a written answer."
},
"options": {
"type": "array",
"description": "Candidates or choices; required (at least 2) for every type except yes_no and open_text. A string, or {text, description} to include a candidate statement.",
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"text": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"text"
]
}
]
}
},
"seats": {
"type": "integer",
"minimum": 1,
"description": "How many winners (board seats). multiple_choice: the \"vote for up to N\" limit. ranked_choice/approval/cumulative: seats to fill."
},
"allow_write_in": {
"type": "boolean",
"description": "Let voters write in one candidate (single_choice, multiple_choice, approval, cumulative)."
},
"include_abstain": {
"type": "boolean",
"description": "Add an \"Abstain\" choice that counts toward turnout but never wins (yes_no, single_choice, multiple_choice, approval)."
},
"required": {
"type": "boolean",
"description": "Whether a voter must answer. Defaults to true, except open_text."
}
}
}
}
}
}
}
}
},
"required": [
"election",
"patch"
]
}