ClayHR On-Premises Active Directory Sync keeps employee records in ClayHR aligned with an on-premises Microsoft Active Directory environment. A PowerShell script runs on a customer's Windows Server, retrieves employee changes from ClayHR over HTTPS, and applies configured changes to AD.

What the integration does

• New hires: Create an AD account for an active employee in the designated organizational unit (OU), using an initial password that must be changed at first sign-in.
• Employee changes: Update supported fields such as names, job title, department, email, phone, and target OU when employee records change.
• Rehires: Re-enable a matching disabled account, with a password reset where configured, rather than creating a duplicate.
• Leavers: Automatic deprovisioning is not part of the described sync. Continue to disable departing employees through your standard IT offboarding process.

How synchronization works

1. Windows Task Scheduler starts the PowerShell script on a domain-joined server.
2. The script checks its configuration, reads last_sync.txt, and calls the secured GET /api/users endpoint with a per-user API key. The request filters active employees and, after the first run, employees changed since the last successful sync.
3. On the first run, the empty checkpoint triggers a full sync of active employees. Later calls use status=A and lastupdatets=<time>, fetching up to 500 employees per page.
4. For each employee, it searches AD by work email first and Employee ID second.
5. It creates new accounts or writes only changed attributes to existing accounts. Existing usernames and user principal names (UPNs) are preserved.
6. The script records created, updated, moved, re-enabled, skipped, unchanged and error outcomes. It advances the last_sync.txt checkpoint only when the run has no errors, so failed changes are retried.

Network model: Requests are initiated by your server to ClayHR. No inbound connection from ClayHR to your corporate network is required. The architecture also shows a separate outbound POST /external-logs call, authenticated with a system API key, to report sync logs back to ClayHR.

Prerequisites

• A domain-joined Windows Server with Windows PowerShell 5.1 or later.
• The Active Directory PowerShell module (RSAT).
• A dedicated service account with permissions to create, modify, move, enable, and reset passwords on user accounts within the intended OUs. Delegate only the permissions required.
• Outbound HTTPS connectivity to your ClayHR instance.
• ClayHR API credentials issued for your company.
• Target organizational units already created in AD.

To install the AD module on supported Windows Server versions, an administrator can run Install-WindowsFeature RSAT-AD-PowerShell.

Step 1: Copy the synchronization files

ClayHR provides ClayHR-ADSync.ps1, the PowerShell script, and ClayHR-ADSync.config.psd1, the configuration file. Copy both to C:\ClayHR\ADSync\ on the domain-joined server.

Step 2: Store ClayHR credentials

Configure the API key and API user ID as machine-level environment variables that the scheduled service account can read:

[Environment]::SetEnvironmentVariable("CLAYHR_API_KEY", "<your-api-key>", "Machine")
[Environment]::SetEnvironmentVariable("CLAYHR_API_USERID", "<your-user-id>", "Machine")

Limit administrator access to the server and protect credentials appropriately. Machine-level environment variables are readable by privileged server administrators.

Step 3: Configure the sync

Place ClayHR-ADSync.ps1 and ClayHR-ADSync.config.psd1 in C:\ClayHR\ADSync\. Edit the configuration file for your environment; do not leave placeholder values in place.

ApiUrl         = "https://<your-instance>.clayhr.com/rm/api/users"
Domain         = "corp.example.com"
DefaultOU      = "OU=Employees"
UpnSuffix      = $null
UsernameFormat = "first.last"
CustomFieldMappings = @{
    "Office Location" = "physicalDeliveryOfficeName"
    "Employee Type"   = "employeeType"
}

Confirm the correct API URL and credentials with your ClayHR contact. Other relevant configuration settings include OUCustomFieldName, SyncFields, ReEnableDisabledAccounts, RehireResetPassword, PageSize, MaxUsers, LogFile, and StateFile. The example reference uses a maximum page size of 500.

What employee data can sync?

• First and last name to AD given name and surname.
• Full name to display name and object name; duplicate names can be distinguished using Employee ID.
• Work email to the AD mail attribute.
• Department, position, and phone to the corresponding AD attributes.
• Employee ID to the AD Employee ID attribute, with the ClayHR user ID available as a fallback.
• The ClayHR custom field Azure On-Prem AD OU to the employee's target OU, with a default OU when blank.
• Configured custom fields, such as office location and employee type, to appropriate AD attributes.

Employees without first name, last name, or work email are skipped and logged. Supported standard field updates can be disabled in configuration when IT prefers to manage those attributes in AD.

Step 4: Test before enabling changes

Begin with a test domain or pilot OU, and run the script as the intended service account.

cd C:\ClayHR\ADSync
.\ClayHR-ADSync.ps1 -DryRun
.\ClayHR-ADSync.ps1
Get-Content "C:\ClayHR\ADSync\Logs\sync.log" -Tail 50

-DryRun previews proposed directory operations without writing changes. Review the affected accounts and OU paths before running the live sync.

Step 5: Schedule ongoing synchronization

1. Open Windows Task Scheduler and create a task named ClayHR-AD-Sync.
2. On the General tab, choose Run whether user is logged on or not and Run with highest privileges, using the designated service account.
3. Choose an off-peak recurring schedule, such as 2:00 AM daily.
4. On the Actions tab, select Start a program, set the program to powershell.exe, and enter -ExecutionPolicy Bypass -File "C:\ClayHR\ADSync\ClayHR-ADSync.ps1" as arguments. Have IT review the execution-policy choice against your environment's security rules.
5. On the Settings tab, allow on-demand runs, retry failures three times at 10-minute intervals, and stop the task after one hour. Save the task and provide the service account credentials when prompted.

Logs and troubleshooting

Each run concludes with totals for created, updated, re-enabled, unchanged, skipped and failed records. The checkpoint advances only after a successful error-free run. The script records actions such as CREATED, UPDATED, MOVED, NOOP (no changes), DRYRUN, SKIPPED, WARN, INFO, and ERROR. Review the summary after each run.

• Missing environment variables: Set CLAYHR_API_KEY and CLAYHR_API_USERID, then restart the task.
• Failed to fetch page: Confirm outbound HTTPS connectivity, your instance URL, and API credentials. The next run should retry pending changes where the checkpoint was not advanced.
• Skipped employee: Add the missing first name, last name, or work email in ClayHR.
• OU move failed: Check that the destination OU exists and the service account has permission on both source and target OUs.
• Repeat a full sync: Follow the recovery procedure for the configured StateFile; accounts that already match should not require new writes.

Recommended go-live sequence

1. ClayHR shares the script, configuration file, API key and user ID.
2. IT prepares a pilot OU and performs a dry run.
3. Review the output and logs together with ClayHR.
4. Enable the daily schedule once the results are approved.

Security and operational boundaries

• The script operates inside your environment and calls the ClayHR API over encrypted outbound HTTPS.
• Use least-privilege service-account permissions and protect API credentials.
• Changes are logged; unchanged fields are not rewritten.
• The described integration does not delete or automatically disable leavers' accounts.
• Keep an established IT review and offboarding process in place.

For assistance with API credentials, the PowerShell package, or planning a pilot, contact ClayHR Support. See also the On-Premises Active Directory Sync integration overview.