CSV Import

CSV import is the fastest way to bring submissions in from a spreadsheet, an old form provider, or another platform. Click Import in the Submissions tab header (next to Add submission) to open the import wizard.

When to use it

• Migrating from Google Forms, Typeform, or another platform mid-cycle
• Bringing in late entries collected outside HackHQ
• Seeding test data when you're configuring the form
• Loading projects that were collected through a partner channel

For a single project, use Add submission instead. CSV import is optimized for batches.

Download a sample CSV

The upload step has a Sample CSV button (next to the dropzone). Clicking it downloads a hackhq-sample-submissions.csv file with the canonical column names and two example rows, one with a 3-member team and one with a solo submitter. If your event already has tracks or challenges configured, the sample pre-fills the first of each so the file is a working starting point you can edit and re-upload.

Use it when you're not sure how to name your columns, want to confirm the ;-separated team format, or just need a clean starting point.

CSV requirements

The importer accepts standard CSV files (comma-separated, UTF-8). Up to 1,000 rows per import.

Header names are matched flexibly. Any of Project Name, project_name, Project, or Title map to the project name column. The same forgiving matching applies to team names, team emails, description, track, and challenges. Lead Name and Lead Email are also accepted as headers and map to Team Names / Team Emails for single-member teams.

Teams

Teams are imported lead-first. Both Team Names and Team Emails are ;-separated lists, and the importer pairs them by position: the first name belongs with the first email, the second with the second, and so on.

• The first member is the lead. They become the Lead on the submission and own the manage page.
• Every other member becomes a team member. They're added to the submission with role Team Member.
• Email is required for every member, including the lead. HackHQ keys participants on email per event, so a member without an email can't be created. If you don't have an email for someone yet, leave them out of the CSV and add them through the submission's edit flow later.
• Team Names and Team Emails must have the same number of entries. If they don't, the row is rejected with a clear error pointing at the mismatch.
• Up to 50 team members per submission.
• Duplicate emails inside one team are rejected. A typo that lists the same email twice surfaces as a row-level error rather than silently merging members.
• Empty entries inside a list (Maya;;Lin) are dropped before counting, so a stray double-; doesn't break a row.

Example

Project Name,Team Names,Team Emails,Track,Challenges
Pixel Pal,Maya Chen;Lin Park;Sam Diaz,maya@example.com;lin@example.com;sam@example.com,Web App,Best Use of Auth;Best Newcomer Project
Solo Synth,River Kim,river@example.com,Hardware,

In this example, Maya Chen is the lead of Pixel Pal with Lin Park and Sam Diaz as team members. Solo Synth is a single-member team with River Kim as the lead.

The import wizard

The wizard steps through four stages:

Tracks and challenges

Tracks and challenges are matched against existing competitions on your event by name (case-insensitive, whitespace-trimmed). You don't pre-create them through the importer.

• Track: a single value per row. If your event has tracks, the column is required and unknown values reject the row. If your event has no tracks, leaving the Track cell empty is silently fine. Rows that supply a track value anyway get a per-row warning and still import, the value is just ignored.
• Challenges: multiple values per row, separated by ;. Unknown names produce a non-fatal warning and the row still imports without that challenge attached.
• Overall competitions are attached automatically to every imported submission, the same as on the regular submission form.

Custom fields from extra columns

Any column that isn't recognized as a built-in field (project name, team names, team emails, description, track, challenges) is treated as a custom field. In the preview step you can decide whether each unknown column becomes a new question on your submission form or gets dropped.

When Create new fields is on (the default for empty events), HackHQ creates the matching FormField entries before importing rows so the responses land on real fields and show up in future submissions, exports, and the public submission page.

This auto-creation is disabled when:

• The event already has form responses (existing structure is preserved)
• The event already has submissions (avoids redefining fields mid-cycle)

In those cases, extra columns still come through on each row's data, but the form schema isn't changed.

Duplicate handling

Two duplicate checks run against the (project name, lead email) pair (lead email = the first entry in Team Emails):

• Already in the system: the same project name and lead email already exists in this event. The row is skipped and counted as a "duplicate of an existing submission" in the results.
• Duplicated within your CSV: the same pair appears twice in the same file. Only the first row imports; later rows are counted as "duplicate within file" so you can spot the issue in your spreadsheet.

This separation is intentional, knowing whether a duplicate is in your file or in the system tells you whether to fix the CSV or just live with the dedup.

Errors and warnings

The wizard distinguishes two outcomes per row:

• Errors stop the row from importing. Examples: missing required column, missing or invalid member email, missing member name, list-length mismatch between Team Names and Team Emails, duplicate emails within one team, unknown required track, validation failure on the project name length.
• Warnings allow the row to import but flag something the organizer should know. Examples: unknown challenge name (the row imports without that challenge), unknown track on an event where tracks are optional.

Errors are listed in the results step with the original spreadsheet row number, so the row label matches what you see in Excel or Google Sheets (header is row 1, the first data row is row 2).

What happens after import

When the import finishes, HackHQ:

• Upserts a participant record for every team member (lead and team members alike) so they're all discoverable in the participants list
• Attaches every Overall competition automatically
• Resolves Track and Challenges by name, scoped to the event
• Triggers auto-assign for each new submission so judges immediately see the new projects in their queue
• Auto-disables voting if the import pushes the event past your plan's submission limit, so existing votes aren't disrupted

Tips

• Start from the sample CSV if you've never used the importer before. The Sample CSV button on the upload step gives you a file with the right column names already filled in.
• Try a small file first. Run 3-5 rows through the wizard to confirm your column mappings before uploading the full batch.
• Match track and challenge names exactly (case doesn't matter, but spelling does). Set up your competitions before importing.
• Use a Demo Video URL column for embedded video previews. URL fields auto-render YouTube, Loom, GitHub, and Twitter/X embeds in the submission detail panel.
• Keep emails normalized in your spreadsheet. Imports are deduped on lowercase, trimmed emails, but trailing whitespace in source data is a common cause of "missing" matches.
• Spreadsheet tip: in Excel/Google Sheets, build the team columns by typing each member on a separate row, then use TEXTJOIN(";", TRUE, range) to combine them into one cell per submission.