How do I enable automatic directory sync in Span?
Last updated: November 12, 2026
By default, each directory sync waits for someone to review and apply it. Span staff can turn on auto-apply for your organization so syncs apply without that manual step.
Why it matters
When new data arrives from the Span Sync API or your HR system, Span stages it as a sync. In manual mode, new hires, leavers, and team changes don't reach Span until someone with the right permission opens the Directory Sync page and clicks Apply. Auto-apply removes that wait. Manual mode gives you a chance to catch bad source data before it changes your roster.
How it works
Manual mode (default): each new sync is staged on Settings → Directory Sync. Nothing changes in Span until a reviewer clicks Apply. A staged sync that hasn't been applied doesn't appear in the audit log, and new people in it don't exist in Span yet.
Auto-apply: each sync applies as soon as it is generated, and there is nothing to approve. The Directory Sync page shows "Auto-apply enabled" and no Apply button.
Timing: syncs aren't generated on a timetable. A change in a source leads to a new sync once Span has processed that source, so data you just sent won't appear immediately.
How to turn on auto-apply
Auto-apply isn't a setting you can change yourself. Span staff turn it on per organization.
Contact your Span account team or support and ask for auto-apply on directory syncs.
If you want to check a few syncs first, ask support to keep manual approval in place until you're ready.
To apply a pending sync manually in the meantime:
Go to Settings → Directory Sync.
Review the pending changes across the People, Teams, and Memberships tabs. Pay special attention to the Teams and Memberships tabs to check for Removed items. For a first full sync, seeing many removed items, such as 86 teams and 137 memberships, is often expected because existing teams are replaced by the ones in your payload. However, skim those tabs to confirm that none of the removed teams are ones you want to keep before clicking Apply.
After a sync is applied, changes show right away in Settings → People Management. Other areas of the app can take longer to update.
Things to know
Who can apply syncs: reviewing and applying needs the Manage Directory Sync permission. Owners and Admins hold it by default, and you can grant it to any permission group under Settings → Permission Groups. If you or a colleague can't see the Directory Sync page, check this permission first. The page also stays hidden until Span has configured a roster source for your organization.
Auto-apply also applies terminations: people missing from the source are terminated as soon as the sync applies, with no review step. Make sure your source sends everyone you expect before you switch on auto-apply.
Worked example: your HR system sends a sync on Monday with 2 new hires and 1 leaver. In manual mode, the 2 hires don't appear in Span, and the leaver stays active, until a reviewer clicks Apply, say on Thursday. With auto-apply, all three changes land as soon as Span generates the sync on Monday.
When new people get metrics: a new person appears once the sync applies. Their PRs and commits count once their Git usernames are mapped, and they enter per-person rates from their first code activity.
Errors stop a sync either way: if a sync has a data problem, such as a person with no start date, it fails to apply in both modes. The Directory Sync page shows the error. Fix the source and the next sync replaces it.
Troubleshooting "Terminated" status in sync preview
If you see people listed as "Terminated" who still work at your company, do not apply the sync. In the preview, "Terminated" means the person is active in Span but did not appear in the current sync data. Span will mark them as terminated if you click Apply—it is not reading a "terminated" flag from your HRIS.
This usually happens when:
They are outside the departments selected to sync.
They have no work email in your HRIS.
Their Span email does not match their HRIS email.
To resolve: send one or two names or emails from the terminated list to support to investigate. The fix is usually to add their department to the sync scope or align the work email. Support will then regenerate the preview.
Related articles
Using Directory Sync for Roster Management
How to use the directory sync JSON file to import team hierarchy and membership into Span
Need help?
Contact your Span account team or reach out to support@span.app.