> For the complete documentation index, see [llms.txt](https://help.getmobly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.getmobly.com/help-center/account-and-team/how-to-bulk-upload-users.md).

# How to bulk upload users

When you need to add more than a handful of users at once — for example, onboarding the field team before a quarterly kickoff — the CSV bulk upload is the fastest path. **Admin-only.**

For a single user, see [How to add users](/help-center/account-and-team/how-to-add-users.md) instead.

## The CSV template

Mobly provides a template CSV with the exact column names it expects. Always start from the template — extra columns are ignored, but mismatched or missing required columns cause errors on import.

### Required columns

| Column      | Notes                                                  |
| ----------- | ------------------------------------------------------ |
| `firstName` | Required for every row                                 |
| `lastName`  | Required for every row                                 |
| `email`     | Required for every row; must be unique within your org |

### Optional columns

| Column                    | Notes                                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------------ |
| `sendWelcomeEmailYesOrNo` | `Yes` sends a sign-in PIN email at upload time. `No` (or blank) skips it — you can send manually later |

> The welcome email comes from `support@getmobly.com` and contains a 6-digit PIN the user enters to complete setup. See [How to add users](/help-center/account-and-team/how-to-add-users.md#what-the-new-user-sees) for what the user experiences.

## Upload steps

1. In the Hub, navigate to **Users**.
2. Click **Add User** in the top right. From the dropdown, select **Import from CSV**.

   ![](//d33v4339jhl8k0.cloudfront.net/docs/assets/67f00b47b96c282fea91b6f6/images/69b320239c0a2d7ca870f4ff/file-B7cs8Tx47u.png)
3. Click **Download template file** to grab a starter CSV with the right column names.

   ![](//d33v4339jhl8k0.cloudfront.net/docs/assets/67f00b47b96c282fea91b6f6/images/69b3203aa280f057e03025df/file-gHJ7Zcvbqb.png)
4. Open the `User_Upload_Template.csv` you downloaded. Paste your data into the columns. Every row needs `firstName`, `lastName`, and `email`.
5. For each row, set `sendWelcomeEmailYesOrNo` to `Yes` if you want that user to get the sign-in PIN email immediately. Otherwise leave it blank.

   ![](//d33v4339jhl8k0.cloudfront.net/docs/assets/67f00b47b96c282fea91b6f6/images/69b32044a280f057e03025e0/file-sbZoCZzwig.png)
6. Save the file and return to the Hub. Upload the file using the same Import from CSV drawer.

   ![](//d33v4339jhl8k0.cloudfront.net/docs/assets/67f00b47b96c282fea91b6f6/images/69b3204ea280f057e03025e1/file-F6zCQu4Ggk.png)
7. The Hub will validate the file and flag any rows with errors before saving. Fix and re-upload as needed.
8. Click **Save**. The valid rows are created as users in your org.

## Common errors

| What you see              | What it usually means                                                                                                     |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| "User already exists"     | The email is already in the org. Mobly won't create duplicates — the existing user is preserved as-is.                    |
| "Invalid email"           | The email doesn't pass basic format validation. Fix the row and re-upload.                                                |
| "Missing required column" | Your CSV doesn't have `firstName`, `lastName`, or `email` as a column header. Re-download the template and start from it. |
| "Unknown column"          | You added a column that Mobly doesn't recognize. Extra columns are ignored — this is informational, not an error.         |

If the file keeps failing in a way that doesn't make sense, reach out to your CSM with the CSV attached.

## After upload

New users land in the Users table with the role **Client** by default. The CSV doesn't currently set role per row. If you need any of them set to Mobly Admin, contact your CSM with the list of users to promote — see [User roles in Mobly](/help-center/account-and-team/user-roles.md).

## Related articles

* [How to add users](/help-center/account-and-team/how-to-add-users.md) — single-user form
* [User roles in Mobly](/help-center/account-and-team/user-roles.md) — what Client vs Admin can do