⚠️ 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
Go to Manage Organisation
Click Groups under user management
You'll see the Groups management page.
Create a New Group
Click Choose Something dropdown
Select a category you want to add (e.g., Department)
Click Add a group
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
Click Manage Organisation > Users: Import Users
Click Bulk Upload Users
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
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:
"EMP001"
SSO system-specific identifier
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
In Excel:
Click File > Save As
Choose "CSV (Comma delimited) (*.csv)" as file type
Save the file
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
Go to Manage Organisation > Under User management Click Import Users
Click Bulk Upload Users
Click Upload New CSV button
Click Browse to select your file
Choose the .csv file you prepared
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 company 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
Review error message carefully
Note which rows have errors
Understand what the issue is
Open your CSV file
Find the problematic rows
Locate the specific fields with issues
Correct the errors
Fix formatting issues
Fill in missing data
Remove duplicates
Verify changes
Save file as .csv
Use Save As > CSV format
Verify file extension is .csv
Re-upload the file
Follow upload process again
Monitor for successful completion
After Successful Upload
Verify Upload Results
Once upload shows "Complete" status:
Check employee accounts created:
Go to Manage > Organisation > Users
Verify employee count matches your CSV
Spot-check several employee profiles
Verify group populations:
Go to Manage > Organisation > Groups
Check that group items populated correctly
Verify employees assigned to correct groups
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
Create CSV with only current employees
When uploading, tick "Suspend non-included users"
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