CSV Formatting Guide

How To: Format Your Voter CSV

Overview

UrVote accepts a wide range of CSV layouts when importing voters. Whether you have a single column of emails or a multi-column file with constituency assignments, the importer can usually figure it out — as long as the file follows a few rules.

This guide walks through every supported layout, the layouts UrVote will reject, and how to fix the most common formatting issues.

Quick rules

Every file must contain at least one email column. The header should be email, e-mail, or email address. If no header matches, UrVote will pick any column where most values look like email addresses.
Empty rows are ignored automatically.
Duplicate emails are deduplicated — across all rows and across all groups.
The file should be saved as plain CSV (UTF-8). Excel .xlsx files won't work.

Supported layouts

1. Single-column emails

The simplest format. One column, one email per row.

email
alice@example.com
bob@example.com
charlie@example.com

Use this for ungrouped private elections where every voter is eligible for every ballot.

2. Email + one constituency column

Each voter is assigned to exactly one constituency.

email,constituency
alice@example.com,North
bob@example.com,South
charlie@example.com,North

When you upload this, UrVote will offer to create one constituency per unique value. Pick the column from the Create constituencies from dropdown in the import side panel.

3. Multiple groups in a single column

If a voter belongs to several constituencies, list them in one cell separated by commas or semicolons.

email,groups
alice@example.com,"North;Board"
bob@example.com,South
charlie@example.com,"North,Audit"

UrVote will split on ; and , and create the membership in each listed group.

4. Duplicate email rows for each group

Equivalent to layout #3 — list the same email on multiple rows, one per group.

email,constituency
alice@example.com,North
alice@example.com,Board
bob@example.com,South
charlie@example.com,North
charlie@example.com,Audit

UrVote deduplicates the email and adds it to each constituency it appears in.

5. Group-only eligibility

If a row has no email but lists a constituency, UrVote treats it as a group definition with no members yet. You can add voters later from the Manage Voters screen.

email,constituency
,North
,South
alice@example.com,North

6. Duplicate emails with conflicting info

If the same email appears in multiple rows with different group assignments, UrVote uses the union — the voter is added to every group they appear in. Other columns (name, etc.) are ignored.

Unsupported formats

UrVote will show a destructive toast and clear your file when it detects any of the following.

No detectable email column

name,department
Alice,Sales
Bob,HR

There is no column whose header is email-like, and no column where most values pass an email check. Fix: rename the email column to email, or make sure that column actually contains email addresses.

Zero valid emails

The file parses but no row contains a well-formed email address. Fix: check for trailing spaces, missing @, or a header row mistakenly counted as data.

Empty cells in the selected constituency column

If you pick a column for grouping but some rows have an empty cell there, UrVote stops the import. Otherwise those voters would silently disappear at import time.

email,region
alice@example.com,North
bob@example.com,        ← empty cell, would be skipped
charlie@example.com,South

Fix: fill in the missing cell, or move that voter to a different file/column.

Tips & best practices

Open your file in a plain-text editor before uploading to confirm there are no stray characters or encoding issues.
For very large files, run a small sample first (10–20 rows) to confirm the format before importing the full list.
If your data lives in a spreadsheet, use File → Export → CSV (UTF-8) rather than copy-pasting cells.
Strip header rows from any third-party export tool that adds preamble text above the actual data.

Common questions

Can I mix column orderings between rows? No. CSV requires all rows to follow the same header. Re-export from your source if the columns shift mid-file.

What if my file has a column UrVote doesn't recognize? Extra columns are simply ignored. They don't cause an error.

How many constituencies can I create at once? There's no fixed limit, but the visual palette repeats after 8 unique constituencies. Group names remain stable.

Next steps

After your file is correctly formatted, see Upload Member List for the full upload workflow, or Add Members After Publishing if you need to invite more voters once the election is live.

On this page