CSV Import of People + Team Data

Last updated: October 29, 2026

The CSV importer syncs your people directory and team structure into Span from a spreadsheet, with no HR system integration required.

Why it matters

A CSV is the fastest way to load a full roster when you don't have an HR system connected yet, or to make bulk changes to people and teams in one step. It's how many organizations load their first roster.

How it works

Syncing from a CSV replaces all directory data with the contents of your file. This can't be undone, so download your current directory first as a backup.

Entity	What happens
People	Existing people are updated, new people are added, and people not in the CSV are deactivated. Deactivated people are terminated: they keep their history and are not deleted.
Teams	New teams are created. Teams from the CSV can be mapped to existing teams. Existing teams that aren't mapped to a CSV team are deleted.

Required columns

Column names are flexible. Span auto-detects common variations, and you can correct the mapping during upload.

Field	Template column	Also recognized
First Name	`first_name`	first, firstname, fname, given name
Last Name	`last_name`	last, lastname, lname, surname
Email	`email`	email address, work email, e-mail
Start Date	`start_date`	hire date, joined, join date, employment start

Optional columns

Field	Template column	Also recognized
Manager Email	`manager_email`	manager, reports to, supervisor, supervisor email
Team Hierarchy	`team_hierarchy`	team, teams, group, groups, hierarchy, org hierarchy, department, departments
Job Title	`job_title`	title, position, role
Job Family	`job_family`	function, department function
Level	`level`	grade, band, seniority, career level
Location	`location`	office, site, city
Termination Date	`termination_date`	end date, exit date, last day
GitHub Usernames	`github_usernames`	github, github handle, gh username
GitLab Usernames	`gitlab_usernames`	gitlab, gitlab handle, gl username
Azure DevOps Usernames	`ado_usernames`	ado, azure devops, ado username

Dates must be MM/DD/YYYY, for example 03/17/2024, for both Start Date and Termination Date. Other formats, including DD/MM/YYYY and YYYY-MM-DD, are rejected with "Date must be in MM/dd/yyyy format". Start Date must be on or after 01/01/1970.

Manager Email must match the Email of another person in the same file. Because the CSV replaces your whole directory, a manager who isn't in the file causes a "Manager email '…' not found in dataset" error. Leave the cell blank for people with no manager, such as the CEO.

The Team Hierarchy column

This column decides which teams each person belongs to and how teams nest.

Symbol	Meaning
`,` (comma)	Separates levels in a team path, parent to child
`\|` (pipe)	Separates multiple team memberships for one person

Whitespace around commas and pipes is ignored. Span creates every level of a path as its own team, and places the person on the deepest one. For example, "Engineering,Backend,Platform" creates Engineering, Engineering > Backend, and Engineering > Backend > Platform, and makes the person a member of Platform. You can go as many levels deep as you need.

Single-level team: "Engineering"
Two teams: "Engineering,Backend | DevOps,Infrastructure" makes the person a member of Backend (under Engineering) and Infrastructure (under DevOps).
Three teams: "Product,Mobile | Product,Web | Support,Escalations"
No team: leave the cell empty. The person is added to Span but shows as "No team" and doesn't appear in team-level reporting.

Span reads every Team Hierarchy value across all rows and builds the full team tree from the unique paths. For example, rows for Alice ("Engineering,Backend"), Bob ("Engineering,Frontend"), and Carol ("Operations") create Engineering, Engineering > Backend, Engineering > Frontend, and Operations.

How to sync from a CSV

Go to Settings → People Management, open Add member, and choose Sync from CSV.
Intro: read how the sync works. Click download your current directory to save a backup, or download the empty CSV template if you're starting from scratch. Check the box to confirm.
Upload: drag in your file or browse to it. The maximum size is 5MB. Span checks the headers, including duplicate or blank headers.
Column mapping: review the automatic mapping and fix anything it missed.
Validation errors (only if there are any): each error shows its row and column. Fix the file and upload again.
Review teams: Span suggests matches between CSV teams and your existing teams. For each team, map it to an existing team or create a new one. If your CSV has exactly one top-level team, Span maps it to your organization's root.
Review directory: preview every change: people found (new and updated), people not in the CSV (to be deactivated), teams found, and teams not in the CSV (to be removed). Check the confirmation box and click Next, finalize and sync.

Things to know

It's a full replace: the CSV is the whole directory, not a partial update. For targeted changes, edit people one at a time on People Management.
Validation is all-or-nothing: one bad row blocks the whole import. Common errors are a missing required field, a date not in MM/DD/YYYY, a Start Date before 01/01/1970, an invalid email, the same email on two rows, a Manager Email that isn't in the file, and a reporting cycle such as A reports to B and B reports to A.
Wrap cells that contain commas or pipes in double quotes: for example "Engineering,Backend".
Team names are case-sensitive: Engineering and engineering are different teams.
Map renamed teams to keep continuity: if your CSV renames a team, for example Analytics to Analytics Team, map the new name to the existing team in the Review teams step. Otherwise Span deletes the old team and creates a new one.
Circular hierarchies aren't allowed: a team can't be its own ancestor.
Multiple Git usernames: separate them with a comma inside the cell, for example "user1,user2".
Off while an automated sync runs: Sync from CSV is disabled when Directory Sync or an HR system integration is your roster source.
File too large: remove optional columns. If you split the import into several files, remember each one replaces the whole directory, so only the last file's contents remain.
Changes take time to show: People Management updates right after you apply. Team edits take about 30 minutes to show in reports.
Worked example: Span has 200 people. You upload a CSV with 190 of them and 5 new hires, and leave out a team called Legacy. The review shows 5 new people, 190 updated, 10 to be deactivated, and Legacy to be removed. After you apply, the 10 people are terminated with their history kept, and Legacy's members keep their personal history.

Understanding the results

What happened in Span	Why
A person was updated	They existed in Span and were in the CSV
A person was added	They were in the CSV but not in Span
A person was deactivated	They were in Span but not in the CSV
A team was created	It was in the CSV and set to create a new team
A team was updated	It was in the CSV and mapped to an existing team
A team was removed	It existed in Span but wasn't mapped to anything in the CSV

FAQs

Can I undo an import? No. Download your existing directory before every import.

Can a person be on more than one team? Yes. Separate team paths with a pipe |.

What if my column names don't match exactly? Span uses fuzzy matching. If a column isn't recognized, map it by hand in the column mapping step.

My team structure changed. Do I need to remap everything? Only teams that changed. Span suggests matches for the rest, and you confirm them in the Review teams step.

People Data & Roster Management

Using Directory Sync for Roster Management

Creating a Team in Span

How Span attributes metrics to teams

Need help?

Contact your Span account team or reach out to support@span.app.