🚀 Quick Overview
With the CSV upload, you can create or update many users at once.
Each row in the file represents one person.
Required fields must be filled in, otherwise the upload will be rejected.
After the import, you will immediately see how many users were created or updated.
🛠️ Before You Start
Permissions: Only users with the Client Admin role can upload CSV files.
File format: .csv
Delimiter: , (comma). If your file uses ;, adjust it before uploading.
Date format: YYYY-MM-DD (e.g., 2024-09-10)
Multi-values: Use the pipe | separator, e.g. Team1|Team2.
Max file size: 32 MB (~150,000 rows possible).
⚠️ Common pitfalls:
Required fields empty → upload rejected.
Different number of columns between header and rows → error.
Wrong date format or invalid values (e.g., phone numbers with letters) → row invalid.
📑 Step-by-Step Guide
1. Download CSV
Go to the Employees menu in the admin area.
Click Download CSV (top right).
The file will be downloaded as .csv (either an empty template or including current data).
2. Edit CSV
Open the file in Excel, Google Sheets, or another spreadsheet tool.
Fill in the data.
Always save the file again as CSV (UTF-8, comma-separated).
3. Upload CSV
Go back to the Employees menu in the admin area.
Click Upload CSV file.
Select your prepared file.
(Optional) Enable/Disable Users
⚠️ Important: Before using this option, please read the section
“Enable/Disable Users”.
Incorrect usage can unintentionally block many users.
Click Next.
Review the preview:
✅ Green check = valid rows.
❌ Red cross = errors (hover to see details).
Fix issues in your file if needed and re-upload.
Click Import.
After completion, you will see how many users were created or updated.
⚠️ Important Note: Enable/Disable Users
If you activate this option, the system will behave as follows:
All users in your CSV will be set to active → even those previously blocked will be reactivated.
All existing users not included in the CSV will be blocked.
✅ When useful
If you upload a complete, up-to-date list of all users.
Example: You export all employees, adjust data (e.g., phone numbers), and upload the full list again.
❌ When risky
If you only want to add a few new users.
If you only want to make small updates (e.g., one user’s phone number).
If you are not sure your CSV contains all users.
Example:
You currently have 200 active users in the system.
You upload a CSV with 50 users and select Enable/Disable Users.
→ Result: The 50 users in the CSV remain active.
→ The other 150 are blocked and lose access immediately.
📌 Recommendation:
Only enable this option if your CSV truly contains all active users.
For partial updates (e.g., adding 5 colleagues or changing one phone number) → leave this option disabled.
🔒 Exception: Users with the Client Admin role will never be blocked, even if they are not included in the file.
📋 Field Reference (Users)
Column | Description | Required | Data | Allowed values / Format | Example(s) | Common errors |
Email address (unique identifier) | Yes | max. 254 chars, valid format | Invalid format, missing | |||
password | Password | No | Text | free | Secure123! | – |
first_ | First name | Yes | Text | max. 100 chars | Maria | Missing |
last_ | Last name | Yes | Text | max. 100 chars | Meier | Missing |
academi | Title | No | Text | max. 255 chars | Dr. | – |
personal | Internal ID | No | Text | max. 255 chars | EMP12345 | – |
birthdate | Date of birth | No | Date | YYYY-MM-DD | 1980-12-20 | Wrong format |
gender | Gender | No | Enum | Male, Female, Other | Female | Invalid value |
position | Job position | No | Text | max. 255 chars | Project Manager | – |
category | Categories | No | Multi | ` | `-separated, must exist in app | `HR |
goal | Personal goal | No | Text | very long text possible | Career development | – |
mobile_ | Country code (with +) | No | Text | +xx, valid code | +41 | Invalid code |
mobile_ | Mobile number | No | Number | digits only | 791234567 | Contains letters |
busines | Business phone | No | Number | digits only | 321654987 | Contains letters |
language | Language in the app | No | Enum | en, de, fr, it, es, pt-pt | de | Not supported |
sms_ | SMS notifications enabled? | No | Bool | Yes / No | No | Typo |
start_ | Start date | No | Date | YYYY-MM-DD | 2023-11-21 | Wrong format |
termination_ | Termination date | No | Date | YYYY-MM-DD | 2025-04-24 | Wrong format |
roles | Roles in the system | No | Multi | ` | `-separated | `HR admin |
teams | Assigned teams (via external_id) | No | Multi | ` | 1|2|3| or just one | `team_1 |
💡 Tip for partial updates:
If you only want to update certain information for employees (e.g. personal numbers or phone numbers), we recommend removing all columns you do not intend to change. If you leave other columns empty and upload the file, the existing values in those fields will be overwritten and deleted.
Example:
You only want to update the personal numbers and leave the Long-term development goal column empty. If you upload the file like this, the existing development goals in those profiles will be removed.
➡️ Recommendation: Keep only the columns in your CSV that you actually want to update.
❌ Typical Error Messages & Fixes
“Email is required.” → email column missing or empty.
“Birthdate is not in the right format.” → Value must be YYYY-MM-DD.
If you have difficulties with date formatting or need to reformat the date, you can find a step-by-step guide in the Help Center article
“Mobile phone can only contain numbers.” → Remove letters or spaces.
“Team with external id @id does not exist.” → Team must exist in the system or in the same file.
“Unsupported delimiter.” → Save the file with comma ,, not semicolon ;.
📝 Examples
Minimal valid CSV (only required fields)
email,first_name,last_name
[email protected],Anna,Muster
[email protected],Peter,Test
Full CSV (all fields)
email,password,first_name,last_name,academic_title,personal_number,birthdate,gender,position,category,goal,mobile_country_code,mobile_phone,business_phone,language,sms_enabled,start_date,termination_date,roles,teams
[email protected],Secure123!,Anna,Muster,Dr.,EMP001,1985-05-12,Female,Project Manager,HR|Finance,Career development,+41,791234567,321654987,de,Yes,2020-01-15,2024-12-31,HR admin|Surveys/user,team_1|team_2
✅ Pre-Upload Checklist
File is .csv in UTF-8 format
Delimiter is , (comma)
Required fields filled (email, first_name, last_name)
Dates in format YYYY-MM-DD
Multi-values separated with |
Phone numbers digits only, country code with +
Same number of columns in all rows
No typos in column headers
Languages and roles exist in the system
File smaller than 32 MB
❓ FAQ
What happens if a user already exists?
→ The record will be updated (email is the unique identifier).
Can I deactivate users?
→ Yes, using the “Enable/Disable Users” option. Users not in the file will be blocked.
Do I need to upload teams first?
→ Recommended: Yes. This way you can directly assign users to teams.
Can I assign multiple roles or teams?
→ Yes, separate with |, e.g. HR admin|Surveys/user.
Which languages are supported?
→ en, de, fr, it, es, pt-pt.
Why do I see red crosses in the preview?
→ One or more rows contain errors (wrong format, missing required fields).
How big can the file be?
→ Up to 32 MB (~150,000 rows).
Can I use special characters or umlauts?
→ Yes, as long as the file is saved in UTF-8 encoding.
🆘 Support
For support requests, please provide:
Upload timestamp
The CSV file (or a sample row with error)
The exact error message from the system
Your browser and version
👉 Note: The technical documentation also describes team-specific CSV columns. Your current template only contains user fields. If you want to manage teams via CSV, you will need a separate template with columns such as external_id, name, type.