RCV123 - Export ballot file format

RCV123 Export ballot file format

The RCV123 Export ballot format is a JSON file that captures ballot configuration including contest names, candidates, and settings. It can be used to duplicate ballots or transfer configurations between RCV123 accounts.

Export a ballot from Dashboard → Ballot actions → Export ballot

Import using Tools → Import ballot

File Structure

The export file contains a JSON object with the following structure:

This example shows a multi-contest ballot:

{
  "format": "rcv123",
  "version": "1.0",
  "ballot": {
    "name": "Annual Elections",
    "description": "Vote in our annual board elections",
    "language": "en",
    "contests": [
      {
        "contestName": "Board President",
        "contestDescription": "Vote for one president",
        "numberOfWinners": 1,
        "maxRankingsAllowed": 3,
        "candidates": [
          { "name": "Alice Smith", "excluded": false },
          { "name": "Bob Jones", "excluded": false }
        ]
      },
      {
        "contestName": "Board Members",
        "contestDescription": "Vote for three board members",
        "numberOfWinners": 3,
        "maxRankingsAllowed": 5,
        "candidates": [
          { "name": "Carol White", "excluded": false },
          { "name": "Dan Brown", "excluded": false },
          { "name": "Eve Green", "excluded": false },
          { "name": "Frank Black", "excluded": false }
        ]
      }
    ]
  }
}

Field Reference

Top-Level Fields

Field	Type	Description
`format`	string	Always `"rcv123"` — identifies this as an RCV123 export file
`version`	string	Format version (currently `"1.0"`)
`ballot`	object	The ballot configuration object

Ballot Object

Field	Type	Description
`name`	string	Ballot name shown to voters and on the dashboard
`description`	string	Optional description shown on the ballot
`language`	string	Two-letter language code (e.g., `"en"`, `"es"`)
`contests`	array	Array of contest objects

Contest Object

Field	Type	Description
`contestName`	string	Contest name (multi-contest ballots only)
`contestDescription`	string	Contest description (multi-contest ballots only)
`numberOfWinners`	integer	How many winners (1 for single-winner, 2+ for multi-winner)
`maxRankingsAllowed`	integer	Number of ranking columns on the ballot
`candidates`	array	Array of candidate objects

Candidate Object

Field	Type	Description
`name`	string	Candidate name as shown on the ballot
`excluded`	boolean	Optional. If `true`, the candidate will not be imported

Notes

Multi-contest ballots — A single export file can contain multiple contests in the contests array.
Single-contest ballots — When a ballot has only one contest, omit contestName and contestDescription. The ballot's name and description serve as the contest name and description.
Votes are not exported — The export file contains only ballot configuration. Voter data remains private.
Ballot options are not included — Settings like voter access, results visibility, and scheduling are configured during the process of importing the ballot.
RCTab compatibility — The Contest object is based on configuration files used by RCTab, an open source Ranked Choice Voting tabulator used in public elections. If an RCTab configuration JSON file is imported by RCV123, a single contest ballot will be created.