Using a CSV to bulk update your roster data in Span

Last updated: March 19, 2026

Overview

CSV upload lets you sync your organization's people and team structure into Span in one step. It is available under Settings → People Management

⚠ Important: Syncing via CSV replaces all directory data with the contents of your file. This action cannot be undone. Before you start, download your current roster from your People Management page so you have a backup.

What Gets Replaced

Entity	Behavior
People	Existing people are updated; new people are added; people absent from the CSV are deactivated
Teams	New teams are created; teams not present in the CSV (and not mapped to an existing team) are deleted

Preparing Your CSV

Download the empty template from the intro screen or export your existing directory as a starting point.

Required Columns

These four columns must be present:

Column	Description
`first_name`	Person's first name
`last_name`	Person's last name
`email`	Work email address (must be unique)
`start_date`	Hire/start date

Optional Columns

Column	Description
`manager_email`	Email of this person's direct manager
`team_hierarchy`	Team membership and structure (see below)
`job_title`	Job title
`job_family`	Job family or function
`location`	Office location
`level`	Career level or band
`termination_date`	Departure/offboarding date
`github_usernames`	GitHub handle(s)
`gitlab_usernames`	GitLab handle(s)

Flexible Header Names

Span automatically maps your column headers even if they don't exactly match the names above. For example, "hire date", "joined", and "employment start" all map to start_date.

For team_hierarchy, accepted synonyms include "team", "teams", "group", "groups", "hierarchy", "org hierarchy", "department", and "departments".

During the upload wizard you'll have a chance to review and correct any automatic mappings before proceeding.

The `team_hierarchy` Field

This is the most important field for defining how your engineering org is structured in Span. It tells Span which team(s) each person belongs to and how those teams nest inside one another.

Syntax at a Glance

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

Whitespace around commas and pipes is ignored.

Defining a Team Path

A comma-delimited path describes a chain from top-level group down to the person's direct team. Span automatically creates every level of that path as its own team.

Example:

"Engineering,Backend,Platform"

Span creates three teams:

Engineering
Engineering > Backend
Engineering > Backend > Platform

The person is a member of Platform (the deepest level), and metrics roll up through Backend and Engineering automatically.

Single-Level Teams

If a person belongs to a team with no parent, just use the team name alone:

"Engineering"

Deep Hierarchies

You can go as many levels deep as you need:

"Tech Division,Engineering Department,Platform Team,Core Subteam,Alpha Squad"

Span will create all five levels.

Multiple Team Memberships

Use a pipe (|) to assign a person to more than one team. Each segment is its own full hierarchy path.

Example:

"Engineering,Backend | DevOps,Infrastructure"

This person is a member of Backend (under Engineering) and Infrastructure (under DevOps).

Three teams at once:

"Quant,Analytics | Quant,Summarization | Qual,Surveys"

People Without a Team

Leave team_hierarchy empty for anyone who isn't assigned to a team:

"",

How Teams Are Built from the CSV

When you upload, Span reads every team_hierarchy value across all rows and extracts all unique paths and their intermediate levels. It then builds the full org tree from those paths.

Example — given these three rows:

Person	team_hierarchy
Alice	`"Engineering,Backend"`
Bob	`"Engineering,Frontend"`
Carol	`"Operations"`

Span will create:

Engineering
Engineering > Backend (Alice's team)
Engineering > Frontend (Bob's team)
Operations (Carol's team)

The Upload Process (Step by Step)

Intro — Read the warning, optionally download your current directory or an empty template, and check the acknowledgment box.
Upload — Drag and drop or select your CSV file. Span immediately reviews the column headers and checks for errors.
Column Mapping — Review the automatic header-to-field mapping. Correct any mismatches before continuing.
Validation Errors (only shown if errors exist) — Fix any data issues (e.g., missing required fields, invalid email formats) and re-upload.
Review Teams — See all teams extracted from team_hierarchy. Map any new CSV team names to existing teams in Span if you want to preserve continuity (e.g., if a team was renamed in the CSV).
Review Directory — Preview the full set of changes — new people, updated people, deactivated people, new teams, and removed teams — before committing.

Tips & Gotchas

Wrap values with commas or pipes in double quotes. Since commas are used inside the team_hierarchy value, the cell value must be quoted: "Engineering,Backend".
Team names are case-sensitive. "Engineering" and "engineering" are treated as different teams.
Mapping teams during review preserves history. If your CSV renames a team (e.g., "Analytics" → "Analytics Team"), use the team mapping step to link the new name to the existing team so metrics aren't reset.
Deactivation is not deletion. People not in the CSV are deactivated, not permanently removed.
Circular hierarchies are not allowed. A team cannot be its own ancestor.
GitHub/GitLab usernames support multiple values. Separate multiple handles with a comma inside the cell: "user1,user2".