Directory Sync
Directory Sync keeps your PBX user extensions in step with the identities in a configured Directory Service - Azure Active Directory, Okta, or LDAP/Active Directory. Instead of adding, updating, and removing extensions by hand as staff join, change details, or leave, you let the directory you already maintain for logins and email drive extension lifecycle. This avoids drift between your identity system and your phone system: when HR offboards someone in the directory, sync removes the extension it created for them.
Sync Status
Navigate to Users > Bulk Operations > Directory Sync to view the current sync status and run synchronization.
When a directory service is configured, the page displays:
- Provider — the type of directory service (LDAP / Active Directory, Okta, or Azure AD)
- Server — the directory server being synced with
- Synced Extensions — the number of extensions currently managed by sync
- Last Sync — when synchronization last ran
- Sync Result — a summary of the last sync operation (e.g., “3 new, 2 updated, 0 removed”)
Click the Synchronize button to perform synchronization manually. The system also performs automatic synchronization on an hourly schedule.
A Directory Service integration must be configured before sync is available. See Directory Services for setup instructions.
Source of Truth
The external directory is the source of truth for identity data. Synchronization is strictly one-way — from the directory to the PBX. There is no write-back from the PBX to the directory.
If a user’s information is edited directly in the PBX, the next sync will overwrite those fields with whatever the external directory has.
Synchronized Fields
The following fields are managed by the directory and updated on every sync:
| PBX Field | Source |
|---|---|
| First Name | Directory attribute (e.g., givenName in LDAP, first name in Azure AD/Okta) |
| Last Name | Directory attribute (e.g., sn in LDAP, last name in Azure AD/Okta) |
| Directory email address | |
| Mobile | Directory mobile number |
| Extension Number | Work phone / telephone number — used as the extension number when creating a new extension |
For LDAP integrations, the specific directory attributes used for each field are configurable. See Directory Services for attribute mapping details.
What Sync Does NOT Change
All PBX-specific telephony settings remain locally managed and are never affected by sync:
- Voicemail settings, call forwarding, call screening, call blocking
- SIP passwords, user login credentials
- DID assignments, caller ID settings
- Queue membership, department assignment
- Permissions and feature access
- Protocol settings, phone provisioning
- CRM integration settings
These settings are configured in the PBX after the extension is created by sync and are preserved across subsequent syncs.
How Synchronization Works
New Users
If a user exists in the directory but has no corresponding extension in the PBX (based on the tracked unique identifier), a new User Extension is automatically created.
A user must have both an extension number (work phone) and an email address in the directory to be provisioned. Users missing either field are skipped.
Updated Users
If a synced user’s name, email, or mobile number changes in the directory, the corresponding fields on the PBX extension are updated to match.
Deleted Users
If a user is removed from the directory and there is a PBX extension that was previously created by sync, that extension is deleted from the PBX.
Important: Sync only deletes extensions that it previously created. Extensions that were created manually in the PBX (through the UI, API, bulk generator, or CSV upload) are never modified or deleted by sync, even if they have the same extension number.
Internally, the system tracks which extensions were created by sync using a unique object identifier from the directory. This mapping ensures that manually created extensions are always safe from sync operations.
Identifying Synced Extensions
Extensions managed by Directory Sync are marked in two places:
- Extensions grid — a green indicator icon appears in the Sync column for directory-managed extensions
- Extension form — when editing a synced extension, an information message at the top of the form indicates it is managed by Directory Sync
These indicators help identify which extensions are automatically maintained by the directory and which were created manually.
Sync Results
After a sync completes, the results are displayed showing:
- New — extensions that were created
- Updated — extensions whose information was changed
- Removed — extensions that were deleted because the user no longer exists in the directory
For small numbers of changes (5 or fewer per category), individual user names are shown. For larger numbers, only the count is displayed. If no changes are found, the sync reports that everything is up to date.
Best practices
- Treat the directory as the master for name, email, and mobile - do not edit those fields in the PBX, since the next sync overwrites them.
- Configure all PBX-only settings (voicemail, DID, permissions, provisioning) in the PBX after sync creates the extension; these are preserved across syncs.
- Rely on the hourly automatic sync for steady-state operation and use Synchronize manually only when you need a change reflected immediately.
- Extensions sync created are the only ones it deletes - so manually created extensions are safe, but be aware that removing a user from the directory removes their synced extension.
Related documentation
- Directory Services - configure the Azure AD, Okta, or LDAP connection and attribute mapping.
- User Extensions - where synced extensions appear and PBX-only settings are configured.
- Bulk Generator - one-time CSV/table creation when a directory is not the source of truth.