Bulk User Import: How to Upload a Batch of Users in Worksmith

Overview

This article explains how to upload multiple users into Worksmith at once using the bulk import CSV template, and lists the errors that most commonly cause an upload to fail.

Before You Start

• Always start from a fresh copy of the official template — don't reuse an old file. Column order and header names matter.

• Fill in one row per user.

• Enter data in a spreadsheet program (Excel, Google Sheets, Numbers), then export/save the file as CSV — not .xlsx — before uploading.

• The template has 7 columns:

  • FirstName (required)

  • LastName (required)

  • Email (required)

  • Location (required)

  • EmployeePositionTitle (optional)

  • PhoneNumber (optional)

  • Role (required)

Field-by-Field Requirements

FirstName / LastName

• Enter as two separate fields — do not combine into one column.

• Cannot be left blank.

Email

• Must be a valid, correctly formatted address (name@domain.com).

• Must be unique:

  • No two rows in the file can share an email.

  • Cannot already belong to an existing user in the system.

• Double-check for typos — a mistyped email means the invite never arrives.

Location

• Must exactly match an existing store/location name already set up in Worksmith, including spacing and punctuation.

• Best practice: copy the value directly from the Locations list in the admin portal rather than typing from memory.

EmployeePositionTitle (Optional)

• Free text (e.g., "Store Manager," "Sales Associate").

• Descriptive only — does not affect system permissions.

• Can be left blank.

PhoneNumber (Optional)

• Use a consistent format with country code, e.g., +18005555555.

• Leave blank rather than entering placeholder text like "N/A" or "none."

Role

• Must exactly match a role name configured in your Worksmith instance (template examples: "Manager," "Administrator").

• Determines system permissions — cannot be blank or an invalid value.

• If unsure of exact role names, check the Roles section of the admin portal first.

Common Upload Errors

File-Level Errors

• Wrong file type — uploading .xlsx, .xls, or .numbers instead of .csv typically fails the upload. Always export/Save As CSV.

• Header row changed — renaming, reordering, adding, or deleting header columns will cause misreads or rejection. Keep headers exactly as provided.

• Blank rows mid-file — an empty row between users can halt processing or throw a confusing "blank user" error.

• Wrong delimiter — regional Excel settings sometimes save with semicolons instead of commas, scrambling every row into one column.

• File too large — very large batches may hit a row limit or time out. Consider splitting into smaller batches (by location or department).

• Encoding/special character issues — names with accents (ñ, é, etc.) can appear garbled if not saved as UTF-8. Re-export with UTF-8 if this happens.

Required Field Errors

• Blank required field — missing FirstName, LastName, Email, Location, or Role on any row will fail that row. Most common cause: a stray Tab key or partially filled row.

• Extra whitespace — a leading/trailing space (often from copy-pasting) can cause an otherwise-correct Location or Role to not match, even though it looks identical visually.

Email Errors

• Invalid format — missing "@", missing domain, or stray spaces.

• Duplicate within file — same email listed twice, often from a copied placeholder row that wasn't updated.

• Already exists in system — email is tied to an existing active account, common when re-uploading a file that included previously added users.

Location & Role Errors

• Location doesn't match an existing store — typos, abbreviations, or a location not yet created in the admin portal.

• Role doesn't match a valid role name — must match exactly; a common mistake is putting a job title (e.g., "Store Manager") in Role instead of EmployeePositionTitle.

• Case/spacing mismatches — e.g., "manager" vs. "Manager," or a double space in a location name, may fail to match depending on system matching rules.

Phone Number Errors

• Inconsistent formatting — mixing (800) 555-5555, 800-555-5555, and +18005555555 across rows. Pick one format and use it consistently, or leave blank.

• Non-numeric characters — extensions or notes (e.g., "555-5555 ext 2") typically fail validation.

Excel Formatting Artifacts

• Auto-formatting — Excel may convert phone numbers to scientific notation or strip a leading "+" if the column isn't formatted as Text. Format the phone column as Text before entering numbers.

• Unescaped commas — a field containing a comma (e.g., "Store, Downtown") must be wrapped in quotation marks, or it will split into an extra column and shift the rest of that row.

Recommended Workflow

• Fill out the template.

• Save as plain CSV, then reopen it to visually confirm columns still line up correctly.

• Upload the file.

• Review the confirmation/error summary — most bulk import tools flag exactly which rows failed and why.

• Fix only the flagged rows and re-upload just that smaller file, rather than resubmitting the entire batch.

• For large batches: test with 2–3 rows first to confirm Location and Role values are matching correctly before uploading the full list.

When to Contact Support

• If a row fails with an error not listed above, or a Location/Role value that looks correct keeps getting rejected, contact your Worksmith administrator or support with:

  • The specific error message

  • The row in question

• This is usually enough to determine whether it's a data issue or a system-side configuration gap (e.g., a location that hasn't been created yet).