👉 Note: Directory Sync is available for companies on the Pro Plan and allows admins to automatically create, update, deactivate and offboard users in Velory.
🧠In this guide:
- How to configure Directory Sync
- Integration settings
- Importing users
- Realtime Sync
- Data fields imported from Directory Sync
- Restore connection
How to configure Directory Sync
- Go to your profile in the top-right navigation bar.
- Click Settings > Integrations.
- Under Directory Sync, choose a provider from current supported providers in the dropdown menu.
- When the provider is chosen, click on Configure via Velory.
- You will then be guided through a step-by-step process directly within the Directory sync provider, which you need to follow.
⚠️ The user setting up the integration must have access to all users in the Directory Sync provider. Otherwise, not all users can be imported.
Once setup is completed:
- A label will indicate “Synchronising users”
- When this is done, proceed to below Integration settings and set your required settings
Integration settings
When the Directory sync provider is active and before importing users, you can configure how user data is processed, the available settings options may vary depending on which directory sync provider you have connected.
-
Send email invitations to new users (disabled by default)
-
Send offboarding emails (enabled by default)
-
Auto-assign users to locations (disabled by default)
-
User deactivation timing:
- On a set date (default)
- Immediately
- Never
- On a set date (default)
-
User deletion timing:
- Immediately
- Never
- Immediately
Click Save changes to apply your settings.
đź’ˇTo learn how to handle users on leave, see this related article.
Importing users
When users are ready, click Import users to add them to Velory.
🛠️ Import rules:
- Users are imported in the background.
- Only users with "active" status are imported in the first sync.
- If a user reports to a manager, the manager will be created first.
- Users without an email will not be imported.
- If you filter by user groups, only those groups will be imported.
- If a user with the same email already exists, their data will be updated, not duplicated.
Realtime Sync
Once users are synced, Velory listens to updates from the Directory Sync provider daily.
This means:
- Changes made in the Directory Sync provider (create/update/delete) will be reflected in Velory the next day or depending on the settings enabled in the integration settings section.
- Velory identifies users by email or identity provider ID, then updates them accordingly.
Data fields imported from Directory Sync
Velory imports the following employee data fields:
| Field | Description |
| id | Unique user ID in HiBob |
| username | System-assigned username (usually the work email) |
| first_name / last_name | Employee’s first and last name |
| job_title | Job title |
| employee_number | Unique employee identifier, used to merge records across systems |
| department_name | Department (nullable) |
| division_name | Division (nullable) |
| employee_type | Type of employment (e.g., full-time, contractor) (nullable) |
| cost_center_name | Assigned cost center (nullable) |
| state | Employment status (e.g., active, inactive) |
| employment_start_date | Employment start date (YYYY-MM-DD) |
| employment_end_date | Employment end date (YYYY-MM-DD) (nullable) |
| manager_email / manager_id | Email and ID of the direct manager (nullable) |
Email information
Velory supports multiple email addresses per employee:
| Field | Description |
| emails[].type | Email type (work, personal, etc.) |
| emails[].value | Email address |
| emails[].primary | Is this the primary email? (boolean) |
| personal_email | Standalone personal email (nullable) |
Phone numbers
Multiple phone numbers can also be imported:
| Field | Description |
| phone_numbers[].type | Phone type (home, mobile, etc.) |
| phone_numbers[].value | Phone number |
| phone_numbers[].primary | Is this the primary phone? (boolean) |
Group and location data
| Field | Description |
| groups[].id / groups[].name | Group membership |
| office_location | Employee’s office location (nullable) |
| building_id | Building ID (nullable) |
Address data
| Field | Description |
| addresses[].type | Address type (home, work, etc.) |
| addresses[].street_address | Street name and number |
| addresses[].locality | City |
| addresses[].postal_code | ZIP or postal code |
| addresses[].country | Country |
| addresses[].primary | Is this the primary address? (boolean) |
| addresses[].raw_address | Full unstructured address string |
đź’ˇ In addition to the fields listed above, Velory can also import any attribute available via the HR or Directory sync API.
Restore connection
If the integration breaks (e.g., due to token expiry, revoked access, password change, etc.), follow these guidelines to restore the connection safely:
🔄 Best practices:
- The user restoring the connection should have the same or higher access level than the previous user.
-
Do not delete the existing connection — use the edit flow to reconnect. This preserves user sync history.
- Only delete and recreate if you’re switching to a different Directory sync provider or home directory.
- Double-check that settings match your data processing needs after reconnecting.