Importing Race Participants from a CSV File

Managing large numbers of race participants can be time-consuming when done manually. Importing participants from a CSV file allows you to quickly and accurately upload all your registrants at once. This is especially useful when pulling data from online registration platforms, spreadsheets, or timing systems. By using the import feature, you can save valuable time, reduce the risk of typos, and ensure your participant list is complete and consistent—so you can focus on delivering a successful event.

A CSV (Comma-Separated Values) file is a simple text file format used to store tabular data, such as participant lists, in a structured way. Each line in the file represents a row of data, and each value (or “cell”) within that row is separated by a comma. CSV files are widely supported by spreadsheet applications like Microsoft Excel, Google Sheets, and most registration platforms. The format follows standard UTF-8 text encoding and uses a comma or semicolon as the delimiter. The application does not support other delimiters. When preparing your CSV for import, make sure it’s saved in plain text (.csv), with consistent headers and no special formatting like merged cells or formulas.

To ensure your data is correctly mapped to the system, your CSV file must include a header row with specific reserved words in English. These reserved words identify each column’s purpose—such as the participant’s name, bib number, category, birthdate, and gender—and allow the system to automatically recognise and organise the information. This header row must be the first line of your file and should use the exact reserved terms (e.g., name, bib, category, birthdate, gender). Avoid using translated or customised labels, as the system relies on these English keywords to process the data accurately.

Columns that do not have one of the predefined headers are ignored during the import process.

Headers

NAME

This column contains the participant’s full name. If multiple columns are labeled NAME, their values will be automatically combined into a single name, in the order the columns appear. This allows flexibility in separating first names, last names, or middle names across columns while still producing a complete name during import. The field is mandatory.

BIB or NUMBER

This column defines the participant’s bib number (also known as race number). Each value must be a whole number (integer) and should be unique within the event to avoid conflicts. Optional.

CATEGORY

This column assigns each participant to a specific race category. The values must exactly match the names of existing categories in your event. If a value does not match any category, a new category will be added automatically.

This field is generally optional, but RaceTime requires categories. If the CATEGORY column is missing from the file, the participant will be automatically assigned to the category that is currently selected at the time of import. If no categories exist, a category named "Auto-created" will be added. You can rename it later.

GENDER(M;F) or GENDER

This column specifies the gender of each participant. By default, the application accepts M for male and F for female. However, you can customise the accepted values by defining your own terms in parentheses directly in the header.

For example, if your CSV uses the words "Boy" and "Girl" instead of M and F, you can write the header as:

GENDER(Boy;Girl)

The first value will be treated as male, and the second as female. Make sure the values in the column match the ones you specify exactly, including capitalisation.

BIRTHDATE(pattern) or BIRTHDATE

This column contains participants’ birth dates. Because date formats can vary, you can specify how the application should interpret them by providing a pattern string. The pattern uses placeholders like dd, mm, yyyy or yy, combined with separators such as slashes or dashes.

For example:

• dd/mm/yy for a date like 15/07/25

• dd/mm/yyyy for 15/07/2025

• yyyy-mm-dd for 2025-07-15 (this is the default format if no pattern is specified)

Make sure the pattern matches the actual format used in your CSV to ensure correct date parsing.

TEAM

This column is used to assign a team or club to the participant. If the team does not exist then it will be created. Note that the team names are case-sensitive. This field is mandatory in competitions based on team results and optional otherwise.

File Encoding Requirements

For best results, your CSV file should be saved using UTF-8 encoding, which supports a wide range of characters and ensures compatibility across different platforms. If your file uses a different encoding, only Latin-1 (ISO-8859-1) is supported as an alternative. Other encodings may cause errors or lead to incorrectly displayed characters—especially for names or categories containing special symbols or accented letters. To avoid issues during import, always double-check that your file is saved in UTF-8 or Latin-1 format.

Errors

During the participant import process, the system validates each record from the uploaded CSV file and captures any issues encountered. These issues may include missing required fields, invalid data formats, and business rule violations. Instead of stopping the entire import when an error occurs, the system continues processing the remaining records and logs all detected errors for later review.

All validation and processing errors are written to a structured log file generated specifically for that import session. Each log entry typically includes the row number, the name of the field in which the error occurred, the original CSV line and the error message.

Once the import process has finished, the system automatically sends an email to the user who initiated the import. This email includes a link to the error log file, allowing the user to review what failed and why. The user can then correct the reported issues and re-run the import if needed.

Before re-importing, it is important to decide whether the new import should replace previously imported data or add to it. The import dialog you may see a special switch for this. When this switch is enabled, the system will first remove all objects created by the previous import run for that dataset, and then import the corrected file.

To prevent excessive invalid data processing and reduce system load, the import process enforces an error threshold limit of 20 errors per CSV file. Once the number of detected errors exceeds 20, the system automatically aborts the import. The partial error log is still generated and emailed to the user, allowing them to review the reported issues, correct the CSV file, and run the import again.