# Bulk User Import

Source: https://docs.qvoice.net/admin/users/

## User Bulk Import

User Bulk upload allows the QVOICE Platform admin to easily upload one or more users to the platform via a simple to use CSV file.  
Future adds, moves and changes can be administered via a CVS (Excel) file and re-uploaded to the QVOICE Platform when changes are required.

Navigate to the QVOICE Platform [portal](https://qvoice.net/portal)

1. Navigate to **Users** in the top bar
2. Click on the **Upload** button
3. Click on Select File and choose a file from the local computer drive

|  |
| --- |
|  |
|  |

## Bulk Import CSV File

[Link to the CVS upload sample file](https://docs.google.com/spreadsheets/d/1lponA18rso4AwCSBYslowUXYQw-Pr1cqh8GQKkQsyl4/edit#gid=0)

- Click on the link above, and save it in a new google doc or download it and open it as Excel CSV file
- Add all user data, if unsure leave the field empty

## CSV file format

The upload is read by the portal's bulk users import. Each row creates a new user or, when the email already belongs to a user in the account, edits that user.

**Use all 29 columns:**

The header must have **29 columns**, in the order below. The help panel in the **Bulk Users** upload window lists only some of them. A file built from that list is rejected with `number of columns provided is incorrect`. If the sample spreadsheet linked above has a different header, use the one on this page.

The quickest way to get a valid file is **Users → Download**. The downloaded file has the same 29 columns and can be edited and uploaded again.

**File rules**

- Comma-separated. In Excel use **Save As → CSV (Comma delimited)** or **CSV UTF-8**.
- The first line is the header. Column names must be in this order. Case does not matter.
- Every row has 29 fields, including the empty ones. If any row has a different number, nothing is imported and the window lists the rows to fix.
- Put a value that contains a comma in double quotes.

```
First Name,Last Name,Email,Extension,SIP Username,Phone Name,Phone Profile,Phone Label,Phone Number E164,Directory,Admin,UCP,UCP Mobile,SIP Phone,MAC Address,Phone Manufacturer,Phone Model,SIPURI,Cell Phone,Caller ID Name,Caller ID Number,Conferencing,Conferencing PIN,Send Invitation,Invitation Status,Numbers,Cellphones,Tags,Feature Plan
```

Yes/no columns take `1` for yes. `0` or empty means no.

**Columns**

| Column | Value |
| --- | --- |
| `First Name` | Required. |
| `Last Name` | Required. |
| `Email` | Required. Becomes the user's login username. A row whose email already exists in the account edits that user. |
| `Extension` | Required. Numbers only, 3 to 6 digits by default. |
| `SIP Username` | SIP username of the user's SIP device (`SIP Phone`) or SIP URI device (`SIPURI`). Left empty, a random `user_…` username is generated. |
| `Phone Name` | Name of the SIP device. Left empty, it is `<First Name> <Last Name> SIP Device`. |
| `Phone Profile` | Name of a provisioning profile, to also provision a desk phone. See [Provision a desk phone from the user file](https://docs.qvoice.net/admin/users/#provision-a-desk-phone-from-the-user-file). |
| `Phone Label` | Label of the phone's line key. Used only when a desk phone is provisioned. |
| `Phone Number E164` | A phone number to assign to the user, for example `+13055550123`. It is added to the account if it is not there yet. The row fails if the number belongs to another user. |
| `Directory` | `1` lists the user in the company directory. |
| `Admin` | `1` makes the user an account admin. Otherwise the user is a regular user. |
| `UCP` | `1` creates the user's UCP softphone device. |
| `UCP Mobile` | `1` creates the user's mobile app device. |
| `SIP Phone` | `1` creates a SIP device for the user. The SIP password is generated. |
| `MAC Address` | MAC of the desk phone to provision. Used only with `SIP Phone` and `Phone Profile`. |
| `Phone Manufacturer` | For example `yealink`, `polycom`, `fanvil`, `grandstream`, `yeastar`. Used only when `Phone Profile` does not exist yet. |
| `Phone Model` | Phone model, for example `T54W`. Used only when `Phone Profile` does not exist yet. |
| `SIPURI` | A SIP URI to ring, such as `sip:1001@pbx.example.com`. Creates a SIP URI device when `SIP Phone` is not set. |
| `Cell Phone` | When filled, a cell phone device is created for the user. |
| `Caller ID Name` | External caller ID name. |
| `Caller ID Number` | External caller ID number. |
| `Conferencing` | `1` creates a personal conference for the user. |
| `Conferencing PIN` | PIN of that conference. Used only with `Conferencing`. |
| `Send Invitation` | `1` emails the new user their login. |
| `Invitation Status` | Ignored. Present so a downloaded file can be uploaded again. |
| `Numbers` | Ignored. Present so a downloaded file can be uploaded again. |
| `Cellphones` | Ignored. Present so a downloaded file can be uploaded again. |
| `Tags` | Existing tag names, separated by `;`. A tag name that does not exist is reported for that row. |
| `Feature Plan` | ID of the feature plan to assign. The row fails if the plan does not exist or its user limit is reached. |

**Example**

Two users with an extension and a SIP device. The first takes the generated SIP username and device name. The second sets its own and also provisions a Yealink desk phone.

```
First Name,Last Name,Email,Extension,SIP Username,Phone Name,Phone Profile,Phone Label,Phone Number E164,Directory,Admin,UCP,UCP Mobile,SIP Phone,MAC Address,Phone Manufacturer,Phone Model,SIPURI,Cell Phone,Caller ID Name,Caller ID Number,Conferencing,Conferencing PIN,Send Invitation,Invitation Status,Numbers,Cellphones,Tags,Feature Plan
John,Smith,john.smith@example.com,201,,,,,,1,0,0,0,1,,,,,,,,0,,0,,,,,
Jane,Doe,jane.doe@example.com,202,jdoe202,Jane Desk Phone,Yealink T54W,Jane,,1,0,0,0,1,805ec0aabbcc,yealink,T54W,,,,,0,,0,,,,,
```

## Upload the file

1. Go to **Users** and click **Upload**. The **Bulk Users** window opens.
2. Click **Upload CSV File** and select your file.
3. Click **Send CSV File and Create Users**.

When every row succeeds, the window closes with *All users have been created/edited successfully*. Otherwise, the window shows how many rows failed, and **View Details** lists each one with the reason. Fix those rows and upload the file again. Rows that already succeeded are edited, not duplicated.

## Edit users with the same file

Uploading a row for an existing email edits that user. Their SIP, UCP and mobile devices are updated in place and keep their current passwords. To change many users at once, download the list with **Users → Download**, edit it, and upload it.

## Provision a desk phone from the user file

A row with `SIP Phone` = `1`, `Phone Profile`, `MAC Address`, `Phone Manufacturer` and `Phone Model` filled also provisions a desk phone:

- If no profile with that name exists in **Provisioning → Profiles**, one is created from the manufacturer and model.
- If the MAC is new, a phone is created with one line key for the user's SIP device.
- If the MAC already exists, only its profile, manufacturer and model are updated. **No line key is added.**

That covers one user per phone. To put several users on one device, such as several lines on a desk phone or one user per port on a Yeastar FXS gateway, create the users here first, then set the lines with [Import phones from CSV](https://docs.qvoice.net/admin/phone-provisioning/#import-phones-from-csv). The guide [Set Up a Yeastar FXS Gateway in Bulk](https://docs.qvoice.net/how-to/yeastar-fxs-gateway-bulk-setup/) walks through it end to end.

## Common errors

| Message | Fix |
| --- | --- |
| `number of columns provided is incorrect` | The header does not have the 29 columns. Copy the header from this page. |
| `Column names are incorrect` | A column is renamed or out of order. Copy the header from this page. |
| `CSV has rows with wrong number of fields` | The listed rows do not have 29 fields. Add the missing commas, or quote values that contain a comma. |
| `User could not be created. Check Email or Extension` | The email or the extension is already in use, or the extension is not 3–6 digits. |
| `feature plan error` | The `Feature Plan` ID does not exist or the plan's user limit is reached. |
| `Tag name not found` | Create the tag first, or fix its spelling in `Tags`. |
