Using Directory Sync for Roster Management
Last updated: October 27, 2026
Directory Sync keeps your people, teams, and reporting lines current in Span. It collects your roster from the sources Span configures for your organization, merges them, and stages the result for review before anything in Span changes.
Why it matters
Team views, manager permissions, and per-person metrics all depend on an accurate roster. Many organizations keep basic employee records in an HR system but don't keep a complete engineering team structure there. Directory Sync lets you take people from one source and teams from another, so you don't have to maintain the team structure by hand in Span.
For admins: new hires, leavers, and reorgs reach Span without manual edits.
For managers: team pages and manager-scoped access follow your real org chart.
How it works
Sources. Span can take roster data from any of these, alone or combined:
Your HR system, connected through Kombo, Span's HR integration partner. HR syncs supply people and managers, and can also supply teams and team memberships from your HR system's groups.
The Span Sync API, where you send people and team hierarchies as JSON.
Your version control provider, for example GitHub teams and memberships.
A common setup uses the HR system for people records and the Sync API for team hierarchy. Many customers load their first roster with a CSV upload during their trial. Once Directory Sync is on, it updates those existing records.
Staged syncs. Whenever data changes in any connected source, Span processes it and prepares a new staged sync. There is no fixed schedule, so a sync you just sent will not appear right away. Each staged sync shows an overview of People, Teams, and Memberships, and lists:
New people, and people who will be terminated (or removed, see below)
New teams, re-parented teams, restored teams, and removed teams
New and removed team memberships
Field-only changes, such as a new job title, apply with the sync and are not listed one by one.
Applying. By default, nothing changes until someone with the Manage Directory Sync permission reviews the sync and clicks Apply. Span can turn on auto-apply for your organization, so each sync applies as soon as it is generated. See How do I enable automatic directory sync in Span?
People missing from a sync. By default, Span terminates people who are no longer in the source. Their history and metrics stay in Span. The review lists them under Terminated People. Span can instead turn on an option that permanently deletes people missing from the source. With that option on, the review lists them under Removed People, and their data and settings are lost when you apply.
Restored teams. If a team that Span removed in an earlier sync comes back in your source, Span restores it with its original history and lists it under Restored Teams. Access policies and notification subscriptions aimed at that team apply again.
Rehires. When a person's termination date is earlier than their start date, Span treats it as a past employment and keeps them active with their history.
Setup
Contact your Span account team to choose your sources. Span configures them for your organization. The Directory Sync page appears under Settings once a source is configured.
Make sure the people who will review syncs hold the Manage Directory Sync permission. Owners and Admins have it by default. You can give it to any permission group under Settings → Permission Groups.
Send data from your sources. For the Sync API, Span provides OpenAPI documentation for the endpoint. See How to use the directory sync JSON file.
Open Settings → Directory Sync, review the staged changes, and click Apply.
Correcting data. If something in a staged sync looks wrong, fix it in the source system and let Directory Sync pick up the change, or contact Span for help. The next sync replaces the staged one, and you review it again.
Things to know
Default is terminate, not delete: people missing from a source are terminated and keep their history. Permanent deletion happens only when Span has turned on the delete option for your organization.
Worked example: Span has 125 active people. Your HR system's next sync contains 120 of them plus 3 new hires. The review shows 3 new people and 5 Terminated People. After you apply, the 5 leavers keep their past PRs and metrics, and they stop counting in active-day and per-person rates after their termination date.
Synced fields are read-only: fields that come from a sync, such as name, title, level, start date, and manager, can't be edited in People Management. Change them in the source. When teams sync, Team Management shows a "Teams synced" banner and some team fields are locked.
CSV upload is off while a sync runs: Sync from CSV is disabled when Directory Sync or an HR system is your roster source.
Missing start dates block a sync: Span won't apply a sync where anyone lacks a start date. Fix the source, then wait for the next sync.
Missing managers block a sync: if a person's manager isn't in the source, the sync fails to apply. Span can turn on an option to skip those manager links instead.
Emails are the match key: Span matches people by email address. If an email changes in your source, Span treats it as a new person and terminates the old record.
Audit log: a sync appears in the audit log when it is applied, not when it is staged.
Best practice: use the Sync API as the source of truth for people and team hierarchy where you can, and use your HR system for basic employee data when it is accurate and complete.
Troubleshooting
I can't see the Directory Sync page: you need the Manage Directory Sync permission, and Span must have configured a source for your organization.
The page says there are no directory syncs yet: a source is configured but no data has been processed yet. Staged syncs appear after Span processes the first data from your source.
The Apply button is missing: auto-apply is on for your organization (the page shows "Auto-apply enabled"), or the sync is not ready, or it is outdated because a newer sync replaced it.
Someone was terminated unexpectedly: check whether they fell outside the departments or groups your source sends, or whether their email changed in the source.
Related articles
How do I enable automatic directory sync in Span?
How to use the directory sync JSON file to import team hierarchy and membership into Span
People Data & Roster Management
Setting Up SCIM Provisioning for Span
Need help?
Contact your Span account team or reach out to support@span.app.