Skip to main content

Admin Guide: How to Use Bulk Upload to Add Employee Data

This guide explains how to upload employee data to Mo using CSV files, including creating groups, preparing your data, and troubleshooting common errors.

Tahera Barok McArthur avatar
Written by Tahera Barok McArthur
Updated this week

⚠️ Note: You need Admin permission in Mo to create groups and upload employee data.

Before You Begin

What you'll need:

  • Employee data in spreadsheet format (Excel, Google Sheets, etc.)

  • Admin permission in Mo

  • List of groups you want to create (departments, locations, etc.)

  • Basic spreadsheet skills


Overview: Two-Step Process

Step 1: Create Groups

Set up organisational groups like departments, locations, and teams that employees belong to.

Purpose:

  • Groups help colleagues find and connect with each other

  • Groups are used in analytics and reporting

  • Groups enable filtering and list creation

Step 2: Upload Employee Data

Upload a CSV file containing employee information that automatically assigns people to the groups you've created.

What happens:

  • Employee accounts are created or updated

  • Groups are automatically populated with members

  • Users can log in and see their profile information


Step 1: Creating Groups

What Are Groups

Groups are organisational categories that employees belong to, such as:

  • Department (Sales, Marketing, Engineering, HR)

  • Location (London Office, Manchester Office, Remote)

  • Country (United Kingdom, United States, Germany)

  • Division (Europe, North America, Asia Pacific)

  • Job Title (Manager, Senior Developer, Analyst)

Why Create Groups First

Groups must exist before uploading employee data because:

  • The CSV upload assigns employees to existing groups

  • Groups enable profile information visibility

  • Groups power filtering and analytics

  • Groups support list creation for targeted communications

How to Create Groups

Access Group Management

  1. Go to Manage Organisation

  2. Click Groups under user management

You'll see the Groups management page.

Create a New Group

  1. Click Choose Something dropdown

  2. Select a category you want to add (e.g., Department)

  3. Click Add a group

  4. The group is created

Repeat for each group category you need.

Important: Create all groups included in your data before uploading your csv

Understanding Group Items

You don't need to add group items (subcategories) manually.

Group items automatically populate when you upload employee data.

Example:

  • You create a group called "Department"

  • Your CSV includes employees in Sales, Marketing, and Engineering departments

  • These three items (Sales, Marketing, Engineering) willautomatically appear in the Department group after upload

You can refer to this support article on Groups for detailed guidance

Step 2: Uploading Employee Data via CSV

Understanding CSV Upload

CSV (Comma-Separated Values) is a spreadsheet format that Mo uses to bulk upload employee data.

Download the CSV Template

Access Bulk Upload

  1. Click Manage Organisation

  2. Click Bulk Upload Users

  3. Click the Download Template button

The CSV template downloads to your computer.

Why Use the Template

The template ensures:

✅ Correct column headers

✅ Proper field formatting

✅ All required fields included

✅ Consistency with Mo's system

✅ Reduced upload errors

Important: While you can use your own CSV file, headers must exactly match the template format, and the file must be saved as .csv format.

Understanding CSV Template Fields

The template contains required and optional fields for each employee.

Required Fields

These fields MUST be completed for every employee:

external_id

What it is: Unique employee identifier (typically employee ID from your HR system)

Format: Alphanumeric (letters and numbers)

Examples:

  • "EMP001"

  • "12345"

  • "UK-EMP-456"

Requirements:

  • Must be unique for each employee

  • Cannot be blank

  • Used to update existing records in future uploads

Best practice: Use your organisation's existing employee ID system for consistency.

first_name

What it is: Employee's first name (given name)

Format: Text

Examples:

  • "Sarah"

  • "John"

  • "Mary-Anne"

Requirements:

  • Cannot be blank

  • Use proper capitalisation

surname

What it is: Employee's last name (family name)

Format: Text

Examples:

  • "Smith"

  • "O'Brien"

  • "Van Der Berg"

Requirements:

  • Cannot be blank

  • Use proper capitalisation

email

What it is: Employee's email address

Format: Valid email format (name@domain.com)

Examples:

Requirements:

  • Must be unique (one email per employee)

  • Must be valid email format

  • Cannot be blank

  • Used for login and notifications

Best practice: Use corporate email addresses if available

manager

What it is: Indicates whether this employee is a manager

Format: TRUE or FALSE (must be capitalised exactly)

Examples:

  • "TRUE" - This person is a manager

  • "FALSE" - This person is not a manager

Requirements:

  • Must be TRUE or FALSE (no other values accepted)

  • Cannot be blank

Purpose: Manager designation may enable additional permissions or features depending on your Mo configuration.

sso_uid (For non-native login)

What it is: Unique Single Sign-On identifier

Format: Text (format depends on your SSO system)

When required:

  • Only required if your organisation uses Single Sign-On (SSO)

  • For standard email/password login, leave blank or use email address

Examples:

Requirements:

  • Must match your SSO provider's user identifier

  • If SSO not enabled, remove the sso-uid column

country (Reward store)

What it is: Employee's country location

Format: ISO Alpha-2 country codes (two-letter codes)

Examples:

  • "GB" - United Kingdom

  • "US" - United States

  • "DE" - Germany

  • "FR" - France

  • "CA" - Canada

  • "AU" - Australia

When required:

  • Required if your organisation uses Mo Rewards

  • If not specified, defaults to "GB"

Find country codes: Search "ISO 3166-1 alpha-2" for complete country code list.

manager_id

What it is: The external_id of this employee's manager

Format: Must match the external_id of another employee in the CSV otherwise leave this field blank

Example:

  • Employee's external_id: "EMP005"

  • Their manager's external_id: "EMP001"

  • In EMP005's row, manager_id: "EMP001"

Purpose:

  • Creates reporting hierarchies

  • Enables organisational chart views

  • Powers manager-specific features

Best practice: Include manager relationships for full organisational structure visibility.


Optional Fields

These fields are not required but provide additional functionality:

language

What it is: User interface language preference

Format: Language code in format: xx_XX

Supported languages:

  • "en_GB" - English (British)

  • "fr_FR" - French

  • "de_DE" - German

  • "pl_PL" - Polish

  • "pt_PT" - Portuguese

  • "ru_RU" - Russian

  • "es_ES" - Spanish

  • "nl_NL" - Dutch

  • "ro_RO" - Romanian

Default: If not specified, defaults to "en_GB" (English British)

Requirements:

  • Must exactly match one of the supported language codes above

  • Case-sensitive (use underscore, not hyphen)

occasion:occasions-birthday

What it is: Employee's date of birth


Format: YYYY-MM-DD (year-month-day)

Examples:

  • "1985-03-15" (15 March 1985)

  • "1990-12-01" (1 December 1990)

Requirements:

  • Must use exact format: YYYY-MM-DD

  • Use hyphens as separators

  • Include leading zeros (01, not 1)

Purpose: Enables birthday and recognition features.

occasion:occasions-work_anniversary

What it is: Date employee started with the company

Format: YYYY-MM-DD (year-month-day)

Examples:

  • "2020-06-15" (15 June 2020)

  • "2018-01-10" (10 January 2018)

Requirements:

  • Must use exact format: YYYY-MM-DD

  • Use hyphens as separators

  • Include leading zeros

Purpose: Enables work anniversary recognition and tenure tracking.

suspend

What it is: Indicates whether this employee account should be suspended (deactivated)

Format: TRUE or FALSE (must be capitalised exactly)

Examples:

  • "FALSE" - Account is active

  • "TRUE" - Account is suspended

When to use TRUE:

  • Future uploads when employees leave the company

  • Temporarily deactivating accounts

  • Rehire situations requiring reactivation

Default: If not specified, defaults to FALSE (active).

Note: You can use the "suspend non included users" button when uploading your csv instead. This option will suspend all users in your account who do not exist in the file.

Group Fields (group:name)

What they are: Assignment of employees to the groups you created in Step 1

Format: Column header starts with "group:" followed by group name

Examples:

  • "group:Department"

  • "group:Location"

  • "group:Job Title"

  • "group:Division"

Values: The specific item within that group

Example for group:Department column:

  • "Sales"

  • "Marketing"

  • "Engineering"

  • "Human Resources"

Requirements:

  • Group must already exist (created in Step 1)

  • Values automatically create group items

  • Can be left blank if not applicable

Best practice: Include all relevant group assignments to enable full analytics and filtering capabilities.


Preparing Your Employee Data

Gather Employee Information

Collect the required information for all employees from your HR system, spreadsheets, or other sources.

Required for each employee:

  • Employee ID

  • First and last names

  • Email address

  • Manager status (yes/no)

  • Manager ID

  • Country (if using Rewards)

Optional but recommended:

  • Department

  • Location

  • Job title

  • Start date

  • Birth date

Format Your Data

Open the downloaded CSV template in Excel, Google Sheets, or similar spreadsheet application.

Copy and paste your employee data into the template, matching each field to the appropriate column.

Important formatting rules:

Text fields:

  • Use proper capitalisation

  • Remove extra spaces

  • Check for special characters

TRUE/FALSE fields:

  • Must be capitalised exactly: TRUE or FALSE

  • No quotes needed

  • No other values accepted (not Yes/No, not 1/0)

Date fields:

  • Must use format: YYYY-MM-DD

  • Use hyphens, not slashes

  • Include leading zeros (2020-03-05, not 2020-3-5)

Email addresses:

  • Valid email format required

  • One unique email per employee

Country codes:

  • Must be two-letter ISO Alpha-2 codes

  • Capitalised (GB, US, DE)

  • Not full country names

Group assignments:

  • Match group names exactly

  • Case-sensitive

  • Spell consistently

Data Quality Checklist

Before uploading, verify:

✅ All required fields completed for every employee

✅ No duplicate external_id values

✅ No duplicate email addresses

✅ TRUE/FALSE fields use exact capitalisation

✅ Date fields use correct format (YYYY-MM-DD)

✅ Country codes are two letters

✅ manager_id values exist in external_id column

✅ Group columns match groups created in Step 1

✅ No extra columns that don't match template

✅ File saved as .csv format (not .xlsx or other format)


Saving Your CSV File

Save in Correct Format

  1. In Excel:

    • Click File > Save As

    • Choose "CSV (Comma delimited) (*.csv)" as file type

    • Save the file

  2. In Google Sheets:

    • Click File > Download

    • Select "Comma-separated values (.csv)"

    • File downloads to your computer

Critical: The file must be saved as .csv format. Excel files (.xlsx) or other formats will not work.

Uploading Your CSV File

Access Bulk Upload Function

  1. Go to Manage Organisation > Under User management Click Import Users

  2. Click Bulk Upload Users

  3. Click Upload New CSV button

  4. Click Browse to select your file

  5. Choose the .csv file you prepared

  6. Click Open

Suspend Non-Included Users Option

Before clicking upload, you'll see an option: "Suspend non-included users"

What this means: Users currently in Mo who are NOT in your CSV file will be suspended (deactivated).

For your first upload: Leave this box UNTICKED

You're creating new accounts, not updating existing ones, so you don't need to suspend anyone.

Checking Upload Status

Once you have uploaded your file, it will show on the upload log list.


If your file status shows as valid, you can click on 'Approve Upload' to initiate the data upload.

The status will then show as 'Pending' to show the data is currently being processed

The processing time depends on the size of the file uploaded

Upload Completion Status

Once your file has been processed, the status will change as follows:

Complete: Upload successfully processed. All employee accounts created or updated.

Error: Issues were found in the CSV file. Click "View" for error details.


Common Upload Errors and Solutions

Error: Missing Required Field

Message: "Required field missing" or "Field cannot be blank"

Cause: A required field (external_id, first_name, surname, email, manager, country) is blank for one or more employees.

Solution:

  • Review the CSV file

  • Find rows with blank required fields

  • Fill in the missing information

  • Re-upload the corrected file

Error: Duplicate external_id

Message: "external_id must be unique" or "Duplicate identifier found"

Cause: Two or more employees have the same external_id value.

Solution:

  • Search the CSV for duplicate external_id values

  • Assign unique identifiers to each employee

  • Verify no two employees share the same ID

  • Re-upload the corrected file

Error: Duplicate Email Address

Message: "Email must be unique" or "Duplicate email found"

Cause: Two or more employees have the same email address.

Solution:

  • Search the CSV for duplicate email addresses

  • Verify each employee has their own unique work email

  • Correct any shared email addresses

  • Re-upload the corrected file

Error: Invalid Email Format

Message: "Invalid email address" or "Email format incorrect"

Cause: Email address doesn't follow standard format (name@domain.com).

Solution:

  • Check for common issues:

    • Missing @ symbol

    • Spaces in email address

    • Missing domain (.com, .co.uk)

    • Special characters

  • Correct email addresses to valid format

  • Re-upload the corrected file

Error: Invalid TRUE/FALSE Value

Message: "Invalid boolean value" or "manager/suspend field must be TRUE or FALSE"

Cause: The manager or suspend field contains something other than TRUE or FALSE.

Common mistakes:

  • "Yes" or "No" instead of TRUE or FALSE

  • "true" or "false" (lowercase)

  • "1" or "0"

  • Blank cells

  • "Y" or "N"

Solution:

  • Change all values to exactly: TRUE or FALSE

  • Use capital letters

  • No quotes needed

  • Re-upload the corrected file

Error: Invalid Date Format

Message: "Invalid date format" or "Date must be YYYY-MM-DD"

Cause: Date fields (date_of_birth, employment_start_date) don't use the required format.

Common mistakes:

  • DD/MM/YYYY instead of YYYY-MM-DD

  • Using slashes (/) instead of hyphens (-)

  • Missing leading zeros (2020-3-5 instead of 2020-03-05)

  • Text dates ("1 March 2020")

Solution:

  • Convert all dates to format: YYYY-MM-DD

  • Example: 15 March 1985 becomes 1985-03-15

  • Use hyphens as separators

  • Include leading zeros

  • Re-upload the corrected file

Error: Invalid Country Code

Message: "Invalid country code" or "Country must be ISO Alpha-2 code"

Cause: Country field contains full country name or incorrect code.

Common mistakes:

  • "United Kingdom" instead of "GB"

  • "USA" instead of "US"

  • "England" instead of "GB"

  • Three-letter codes

Solution:

  • Use only two-letter ISO Alpha-2 country codes

  • GB (not UK or United Kingdom)

  • US (not USA or United States)

  • Search "ISO 3166-1 alpha-2" for correct codes

  • Re-upload the corrected file

Error: Invalid manager_id

Message: "manager_id not found" or "Invalid manager reference"

Cause: The manager_id value doesn't match any external_id in the CSV.

Solution:

  • Verify manager_id matches exactly with an external_id

  • Check for typos or extra spaces

  • Ensure manager's row is included in the CSV

  • Correct any mismatches

  • Re-upload the corrected file

Error: Invalid Language Code

Message: "Unsupported language" or "Invalid language code"

Cause: Language field contains unsupported language or incorrect format.

Solution:

  • Use only supported language codes:

    • en_GB, fr_FR, de_DE, pl_PL, pt_PT, ru_RU, es_ES, nl_NL, ro_RO

  • Check for correct format (underscore, not hyphen)

  • Verify capitalisation

  • Re-upload the corrected file

Error: File Format Issue

Message: "Invalid file format" or "Cannot parse CSV"

Cause: File not saved as proper .csv format or encoding issues.

Solution:

  • Open file in Excel or Google Sheets

  • Save As > CSV (Comma delimited) format

  • Verify file extension is .csv

  • Try re-saving with UTF-8 encoding

  • Re-upload the corrected file

Error: Column Headers Don't Match

Message: "Invalid headers" or "Column headers incorrect"

Cause: CSV column headers don't exactly match the template.

Solution:

  • Download the template again

  • Copy your data into the fresh template

  • Don't modify header names

  • Ensure no extra or missing columns

  • Re-upload the corrected file

General Error Resolution Process

  1. Review error message carefully

    • Note which rows have errors

    • Understand what the issue is

  2. Open your CSV file

    • Find the problematic rows

    • Locate the specific fields with issues

  3. Correct the errors

    • Fix formatting issues

    • Fill in missing data

    • Remove duplicates

    • Verify changes

  4. Save file as .csv

    • Use Save As > CSV format

    • Verify file extension is .csv

  5. Re-upload the file

    • Follow upload process again

    • Monitor for successful completion


After Successful Upload

Verify Upload Results

Once upload shows "Complete" status:

  1. Check employee accounts created:

    • Go to Manage > Organisation > Users

    • Verify employee count matches your CSV

    • Spot-check several employee profiles

  2. Verify group populations:

    • Go to Manage > Organisation > Groups

    • Check that group items populated correctly

    • Verify employees assigned to correct groups

  3. Test user access:

    • Have a few employees try logging in

    • Verify they can access their accounts

    • Check profile information displays correctly

Next Steps

After successful data upload:

Configure permissions: Set up admin permissions, nominations managers, reward givers, etc.

Customise platform: Configure features, add company branding, set up budgets.

Launch communications: Inform employees about Mo, provide login instructions, encourage engagement.

Enable features: Activate Moments, Rewards, Nominations, Ideas as appropriate.

Create Lists: Use groups to create targeted Lists for communications.


Updating Employee Data

Future Uploads

After your initial upload, you can upload new CSV files to:

  • Add new employees

  • Update existing employee information

  • Remove or suspend former employees

Using external_id for Updates

The external_id field identifies existing users for updates.

When uploading a CSV:

  • If external_id matches existing user: Updates that user's information

  • If external_id is new: Creates new user account

This allows you to:

  • Update departments, locations, job titles

  • Change manager relationships

  • Update email addresses

  • Suspend departed employees

Suspending Departed Employees

Two methods to suspend former employees:

Method 1: Set suspend = TRUE in CSV

In your CSV, change the employee's suspend field from FALSE to TRUE, then upload.

Method 2: Use "Suspend non-included users" option

  1. Create CSV with only current employees

  2. When uploading, tick "Suspend non-included users"

  3. Employees not in the CSV are automatically suspended

Best practice: Method 2 is recommended for regular updates to maintain an accurate active employee list.


Update Best Practices

Regular upload schedule:

  • Monthly updates to keep data current

  • After significant organisational changes

  • When onboarding multiple new employees

Version control:

  • Save dated versions of uploaded CSVs (e.g., "Employee_Data_2025-10-01.csv")

  • Maintain upload history for reference

  • Document significant changes

Data accuracy:

  • Verify data before uploading

  • Test with small batches first if making major changes

  • Check results after each upload


Did this answer your question?