update active directory attribute

Question

Hi All,

I have a requirement to update the telephoneNumber attribute for Active Directory users.

I have a CSV file with the following columns:

• Users – Contains the user's UPN or email address.
• TNumber – Contains the telephone number that needs to be updated.

I need to import the CSV and update the telephoneNumber attribute in on-premises Active Directory by matching users based on their UPN or email address.

Could anyone please help me with a PowerShell script to perform this update? The script should import the telephone number from the CSV exactly as it appears, including any formatting (for example, +1(234) 567-1234 or +11234567893), without modifying or reformatting the value.

Could anyone please help me with a PowerShell script to perform this update?

Answer 1

If you want an alternative to PowerShell check out AD Pro Toolkit. You can easily bulk update user attributes from a CSV file, it also lets you preview the change before updating them.

Answer 2

Welcome to Microsoft Q&A!

Thank you for providing the detailed information.

You can use the Active Directory PowerShell module to import the CSV and update the telephoneNumber attribute directly. The telephoneNumber attribute is stored as a string, so values such as +1(234) 567-1234 or +11234567893 are written exactly as they appear in the CSV without any reformatting. The telephoneNumber LDAP attribute is also exposed as the OfficePhone property in the Set-ADUser cmdlet.

Import-Module ActiveDirectory

$users = Import-Csv "C:\Temp\PhoneUpdate.csv"

foreach ($row in $users) {

$identity = $row.Users

$phone = $row.TNumber

$adUser = Get-ADUser `

-Filter "UserPrincipalName -eq '$identity' -or mail -eq '$identity'"

if ($adUser) {

Set-ADUser -Identity $adUser `

-Replace @{telephoneNumber = $phone}

Write-Host "Updated $identity -> $phone"

}

else {

Write-Warning "User not found: $identity"

}

}

CSV example

Users, TNumber

******@contoso.com,+1(234) 567-1234

******@contoso.com,+11234567893

Notes:

• The CSV headers must be Users and TNumber.
• The Users column can contain either the user's UPN (UserPrincipalName) or email address (mail).
• Set-ADUser -Replace @{telephoneNumber = $phone} updates the telephoneNumber attribute directly and preserves the value exactly as stored in the CSV.
• In hybrid environments where identities are mastered on-premises and synchronized to Microsoft Entra ID through Azure AD Connect, updating the attribute in on-premises Active Directory is the supported approach.

If the information provided is helpful, please click Accept Answer.

Thank you for choosing Microsoft Q&A!

Answer 3

Use the on-premises Active Directory PowerShell module and update the telephoneNumber attribute directly. The telephoneNumber AD attribute is a Unicode string, so the value can be written as-is from the CSV without reformatting.

Import-Module ActiveDirectory

$users = Import-Csv "C:\Temp\PhoneUpdate.csv"

foreach ($row in $users) {
    $identity = $row.Users
    $phone    = $row.TNumber

    $adUser = Get-ADUser -Filter "UserPrincipalName -eq '$identity' -or mail -eq '$identity'" -Properties telephoneNumber

    if ($adUser) {
        Set-ADUser -Identity $adUser.DistinguishedName -Replace @{telephoneNumber = $phone}
        Write-Host "Updated $identity -> $phone"
    }
    else {
        Write-Host "User not found: $identity"
    }
}

Notes:

• CSV headers should be exactly Users and TNumber.
• Users can contain either the UPN or the mail address.
• Set-ADUser -Replace @{telephoneNumber = $phone} writes the value exactly from TNumber.
• The telephoneNumber attribute is single-valued.
• The documented range upper limit for telephoneNumber is 64 characters.

If the environment is hybrid and these users are mastered on-premises, updating the attribute in on-premises Active Directory is the correct approach so the value can sync upward.

---

• Telephone-Number attribute
• Govern on-premises Active Directory users that are provisioned from and managed in Workday.
• HiddenFromAddressListsEnabled - Microsoft Q&A