CSV Import of People + Team Data

Last updated: March 31, 2026

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).

FieldExamples of accepted column names

First Name

first, firstname, given name

Last Name

last, lastname, surname

Email

email address, work email, e-mail

Start Date

hire date, join date, employment start

Optional columns

FieldExamples of accepted column names

Manager Email

reports to, supervisor, supervisor email

Job Title

title, position, role

Job Family

function, department function

Level

grade, band, seniority, career level

Location

office, site, city

Termination Date

end date, exit date, last day

GitHub Usernames

github, github handle, gh username

GitLab Usernames

gitlab, gitlab handle, gl username

Team Hierarchy

team, teams, department, org hierarchy

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 teams: Engineering → Engineering > Backend → Engineering > Backend > Platform, and places the person on the deepest one.

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 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 data errors in your file (e.g. invalid email formats, missing required fields), they'll be listed here. Fix them 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 marked as terminated

  • ✅ 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

What happened in SpanWhy

A person was updated

They existed in Span and were found in the CSV

A person was added

They were in the CSV but not previously in Span

A person was marked as terminated

They were in Span but not found in the CSV

A team was created

It was in the CSV and mapped to "Create new team"

A team was updated

It was in the CSV and mapped to an existing Span team

A team was removed

It existed in Span but wasn't included in the CSV

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 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.