In this article: Overview · Before you begin · Preparing your CSV · Running the import · Understanding the results · FAQs

Overview

The CSV Importer lets you sync your people directory and team structure into Span using a spreadsheet, no HR system integration required. It's useful when:

• You don't have an HRIS connected yet

• You need to make bulk updates to your directory

• You want to onboard quickly with data you already have in a spreadsheet

⚠ Important: Syncing via CSV replaces your entire Span directory with the data in your file. People not included in the CSV will be deactivated, and teams not included will be removed. This action cannot be undone. Review the import preview carefully before applying.

Before you begin

Before uploading, we strongly recommend downloading your current directory as a backup:

1. Go to Settings → People Directory

2. Open the Actions menu and select Sync from CSV

3. On the first screen, click "download your current directory" to save a copy

You can also download a blank CSV template from the same screen if you're starting from scratch.

Preparing your CSV

Required columns

Your CSV must include these four columns. Column names are flexible. Span will auto-detect common variations (e.g. "hire date" maps to Start Date, "fname" maps to First Name).

Date format

Dates must be written as MM/DD/YYYY (for example, 03/17/2024). Other formats — including DD/MM/YYYY and YYYY-MM-DD — are rejected with the error "Date must be in MM/dd/yyyy format". This applies to both Start Date and Termination Date. Start Date is required and must be on or after 01/01/1970.

Optional columns

Manager Email must match the Email of another person included in the same CSV. Because the sync replaces your whole directory, a manager who isn't in the file will cause a "Manager email not found" error. Leave the cell blank for people with no manager (for example, the CEO).

Formatting team hierarchy

Use the Team Hierarchy column to assign people to teams. Teams are expressed as comma-separated paths showing the nesting structure:

Engineering,Backend,Platform

This creates three nested teams and places the person on the deepest one (Platform):

• Engineering

• Engineering > Backend

• Engineering > Backend > Platform

To assign someone to multiple teams, separate paths with a pipe |:

Engineering,Backend|Data,ML

Running the import

Step 1: Read the warning and confirm

Review how the sync works, then check the box to confirm you understand that your directory data will be replaced.

Step 2: Upload your CSV

Drag and drop your file or click to browse. Maximum file size is 5MB. Span will automatically review your column headers (including checks for duplicate or blank headers) and check for formatting errors.

Step 3: Review column mapping

Span auto-maps your CSV columns to Span fields. Review the mapping and correct anything it missed or got wrong before continuing.

Step 4: Fix any validation errors (if applicable)

If Span finds problems in your file, they're listed here with the row number and column. Validation is all-or-nothing: a single bad row blocks the entire sync until you fix it and re-upload. Common errors:

• A missing required field (First Name, Last Name, Email, or Start Date)

• A date that isn't in MM/DD/YYYY format, or a Start Date before 01/01/1970

• An invalid email address

• The same email on more than one row (duplicate)

• A Manager Email that doesn't match anyone else in the file

• A reporting cycle (for example, A reports to B and B reports to A)

Fix the flagged rows in your CSV and re-upload.

Step 5: Map your teams

Span detects all teams from the Team Hierarchy column and shows them here. For each team, choose to:

• Map to an existing Span team: the CSV team will be merged into it

• Create a new team: Span will create a new team during the import

Step 6: Review and apply

Before anything is saved, you'll see a full preview of every change:

• ✅ People found: new and updated

• ➖ People not in CSV: will be deactivated

• ✅ Teams found: new and updated (including renames and restructuring)

• ➖ Teams not in CSV: will be removed

Check the confirmation box once you've reviewed, then click Apply to complete the sync.

Understanding the results

Tip: If someone shows as "No team" in the review, it means they don't have a value in the Team Hierarchy column. They'll be added to Span but won't appear in team-level reporting. To fix this, add them to a team in your CSV and re-upload.

FAQs

Can I undo an import?

No. Once applied, the sync cannot be reversed. Always download your existing directory before running an import.

What date format should I use?

MM/DD/YYYY (for example, 03/17/2024) for both Start Date and Termination Date. Any other format is rejected during validation.

Why is my whole import blocked by one bad row?

Validation is all-or-nothing. If any row fails, nothing is imported until every error is fixed. Correct the flagged rows and re-upload.

It says a manager email isn't found. Why?

Every Manager Email must belong to someone who is also a row in the same CSV. Add the manager to the file, or clear the Manager Email cell for people with no manager.

What happens if my column names don't match exactly?

Span uses fuzzy matching to detect common variations automatically. If a column isn't recognized, you'll be able to map it manually in Step 3.

What if I only want to update some people, not replace everyone?

The CSV importer is a full directory sync. It replaces everything. If you only want to make targeted changes, update individual records manually in the People Directory instead.

Can a person be on more than one team?

Yes. Use a pipe | to separate multiple team paths in the Team Hierarchy column.

What's the maximum file size?

5MB. If your file exceeds this, try removing optional columns or splitting the import into multiple files (note: only the final import will represent the full directory state).

My team structure changed. Do I need to remap everything?

Only teams that changed. During Step 5, you can map each CSV team to an existing Span team or create a new one. Teams that match exactly may be auto-mapped.

Need help preparing your CSV or running your first import? Contact us at support@span.app.