> 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.getmobly.com/help-center/account-and-team/how-to-bulk-upload-users.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.