This guide serves as a start to finish walkthrough of running an election through electrr. It starts with creating an election, and covers everything from adding roles and candidates, to generating results.

First steps

The first step in running any election is to either sign up for an account, or log in to one if you have one already. Signing up is easy, at electrr.app. Simply click log in or sign up at the top right, and enter your details. When you sign up for the first time you'll need to verify your email address, please make sure to check your spam folder if you can't find the email.

Now, you'll need to choose whether you want to create a trial election, or a paid election. Trial elections can be upgraded later.

If creating a paid election, click on 'Create an election'. You might be taken to a page to enter your payment details. To create a trial election, click on 'create a trial election'.

When creating your election, the most important information you need to provide is the slug.

  • It will be the web address people access your election through (for example electrr.app/elections/my-election)
  • It can only contain letters, numbers, and hyphens
  • It must be unique across all of electrr
  • It's probably better to choose a name that describes your election, such as the name of your group or organisation
  • You can have multiple roles inside of each election, and so the name probably shouldn't indicate a specific role (except trial elections)

Once you've created your election, you'll get taken to it's detail screen if it was successful. You might get an error message here - usually because someone else has already taken that name, or because you included a character that isn't allowed.

If you were successful, then you're now at the page from which you can add voters and roles, and update details about your election.

Add Roles

Once our election is set up, it's time for us to add a role to be elected.

Access your election's edit page, and look in the right hand side bar to find the link to add a role.

You'll be asked to provide some basic information about the role, such as a title and an optional description. The description field uses markdown to support rich text, and there's a toolbar at the top to help you format this.

You'll also need to provide the number of seats - that is to say, the number of candidates to be elected - and open and closing times for voting.

Voting open and close times must be in UTC, and will determine whether voters are shown elections. If a voter attempts to access the voting page for a role which isn't open, they'll be redirected away with a message telling them that voting isn't open.

If you're running multiple roles, there's no obligation to make the open and close times the same, but this might make sense from a view of encouraging turnout.

You get to choose whether voters should preference candidates, or just choose their favourite. We love STV elections, but 'one choice' voting works great for things like referendums or decisions, as well as elections.

At this point you can choose to make Reopen Nominations (RON) a candidate in the election. This setting cannot be changed later.

Users who chose to enable nominations in the election settings can also enter the open and close of nominations, or to not allow nominations for this role.

You can edit these details at any time by going to your election's edit screen and clicking on the name of the role.

Once you've entered those details, click on Create role, and it'll ready for candidates!


Before we talk about adding candidates directly to elections, we're going to talk about nominations. The nominations system is only available to paid users, and allows potential candidates to submit their own details during a window defined by you, so that you don't have to collect these details separately and enter them in.

Make sure nominations is turned on in your system settings, and set up the open and close of nominations for each role. Again, there's no obligation to use the same dates for each role.

Once that's done, anyone can access electrr.app/elections/your-election/nominate to submit a nomination. There's no obligation to log in, which means you can encourage nominations before distributing voting details.

Potential candidates are asked to provide their name, photo (optional), manifesto (optional), and answers to questions you can set on an election wide or role specific basis.

At any point, you can click on the name of a role in the election's edit screen, and view candidates who have nominated themselves under Pending Candidates (it won't show up if there aren't any).

By clicking on a candidate's name, you can see the details they provided, and choose to approve them. You can also change their image or manifesto if necessary. Once approved, they're no different to any other candidate.

Add Candidates

To add candidates directly, access the election's edit screen and click on the role you'd like to add a candidate to.

Click Add candidate in the right hand side bar, and you'll be asked for the candidates name, manifesto (optional), and photo (optional).

You can edit a candidates name, manifesto, or photo after adding them by going back to the role, and clicking on their name.

If you need to withdraw a candidate after adding them, you can go back to the role, click on that candidates name, and check the box next to Check box if candidate has withdrawn. They will no longer be presented as an option to voters.

Add Voters

Now that we've got a role to be elected, and some candidates to vote for, it's time to add our voters.

All voters in electrr have a voting code and a security code. The voting code acts as a username, and the security code acts as a password. They're generated randomly when adding voters, and electrr has no limit on the number of voters you can add (except limiting trial elections to 1000 voters).

To add voters, go to your election's edit screen, and look at the options in the 'voters' box. You can see a list of existing voters, or export a .csv file of these details to use in a mailmerge or similar.

If necessary, scroll down and you'll see a box labeled To add non email voters to this election, please enter the number below and click create. Enter the number of voters you need and click on Create. Please don't click this more than once as you might create more voters than intended.

Adding large numbers of voters can take a while, so please be patient. If you need to add a very large number of voters (in the tens of thousands), you can email contact@electrr.app and we can add these voters for you. You're welcome to use the online form as well, it just might take a while.

Paid users can choose to add voters by email address. You can enter a list of email addresses separated by semicolons and electrr will create login details for each email address, and email these out to voters. For larger lists of voters, you can upload a csv file of voter email addresses, and electrr will process them in the same way. We recommend using a file when adding more than a few hundred voters.

Please note that we specifically allow duplicate email addresses in case of multiple voters sharing an email address, so you need to ensure your list is accurate.

Again, please be patient while voters are added, especially if you've provided a very large list of email addresses.

Use of the direct email feature is subject to additional charges; we currently charge £1 per 1000 emails sent using the feature. If your organisation already has a mailing system in place we recommend using that as a cheaper (or free) alternative.

Generating Results

We now have roles, candidates, voters, and (hopefully) some votes cast, so it's time to get our results.

electrr provides two ways to access your results - you can either download a file of all votes cast (anonymously), or calculate and view results directly in the browser,

To access results, go to your admin dashboard and click on the name of the role. To calculate and view results, select your counting method (your organisation may have a specific counting system to use, or we recommend Scottish STV and ERS97STV), and click on Generate results. electrr will count your votes, and display the result for you. Please note that where there are multiple winning candidates, they are listed in order of being added to the database, and not in order of votes.

To export your results, scroll to the bottom of the page and click Download .blt file. The file produced can be used in software such as OpenSTV to verify results, or can be manually viewed by candidates and voters.

Where very large numbers of votes have been cast, we might email you the results, because we cannot keep the page loading for more than 30 seconds. You'll be told if the results are emailed to you, and this should only happen when upwards of 50,000 votes have been cast.

The End

That's a walkthrough of how to conduct an election in electrr, but we didn't touch on all of electrr's features. There's more detail available in the feature guides (lsited in the menu to the left), or you can discover more by playing around. If you have any issues with using electrr, you can email contact@electrr.app for help and advice.