The Users Uploader lets you bulk create or update user accounts in Uncountable by uploading a formatted .xlsx file. This is useful when onboarding a new team, provisioning users across multiple groups, or updating account details in bulk.
Example file: Users Uploader template
Preparing your file
Your file must be a .xlsx spreadsheet. The first row must contain column headers using the exact field reference names listed in the table below. Each subsequent row represents one user.
Column reference
| Column | Required | Description |
|---|---|---|
name | Yes (create only) | Display name used to identify the user. Replace with id when updating existing users. |
email | Yes (create only) | The user’s email address. |
firstName | No | First name. |
lastName | No | Last name. |
active | No | Set to true or false to control account status. |
licenseId | No | ID of the license entity to assign to this user. |
userGroupsForUserVirtual | No | Semicolon-delimited list of user group IDs (e.g. grp_001;grp_002). |
available_in_portal | No | Set to true or false to control portal access. |
ref_name | No | A slug identifier for the user (e.g. alice_johnson). |
Note: Column headers are case-sensitive and must match the reference names above exactly.
Creating new users
To create new users, your file must include at minimum a name column and an email column. All other columns are optional and can be omitted or left blank.
Example (minimal)
| name | |
|---|---|
| Alice Johnson | alice.johnson@example.com |
| Bob Smith | bob.smith@example.com |
Example (full)
| name | firstName | lastName | active | licenseId | userGroupsForUserVirtual | available_in_portal | ref_name | |
|---|---|---|---|---|---|---|---|---|
| Alice Johnson | alice.johnson@example.com | Alice | Johnson | true | lic_001 | grp_001;grp_002 | true | alice_johnson |
| Bob Smith | bob.smith@example.com | Bob | Smith | true | lic_001 | grp_001 | false | bob_smith |
Updating existing users
To update users who already exist in Uncountable, replace the name column with id. The id value should be the user’s entity ID (visible in the user’s record URL or via the platform API).
Example (update)
| id | active | |
|---|---|---|
| usr_abc123 | alice.new@example.com | true |
| usr_def456 | bob.smith@example.com | false |
You can include any combination of optional columns alongside id — only the columns present in your file will be updated.
Running the upload
- Navigate to Admin → Users in the Uncountable platform.
- Click Import and select Users Uploader.
- Upload your
.xlsxfile. - Review the preview to confirm the rows and column mappings look correct.
- Click Confirm to execute the import.
Any rows with errors (e.g. missing required fields, invalid boolean values) will be flagged in the results summary. Successfully processed rows are applied immediately.
Troubleshooting
The upload fails with a column not recognized error
Double-check that your header row uses the exact field reference names listed above. Headers are case-sensitive — email will work but Email will not.
Boolean fields are not being applied
Use lowercase true or false in boolean columns (active, available_in_portal). Other formats such as TRUE, 1, or Yes may not be recognized.
Group assignments are not saving
Confirm that the group IDs in userGroupsForUserVirtual are valid and separated by semicolons with no spaces (e.g. grp_001;grp_002, not grp_001, grp_002).
I want to update users but the names are not matching
Use the id-based update approach instead of name. Matching by name is only used for new user creation and is sensitive to exact spelling.