M365 PowerShell

Using Update-MgUserContact in Graph PowerShell

The Update-MgUserContact cmdlet is a powerful tool within the Microsoft Graph PowerShell module that allows administrators to update contact information for users in their Microsoft 365 environment. This cmdlet is especially useful for keeping contact details up to date, ensuring smooth communication across the organization.

Cmdlet Syntax

Update-MgUserContact -UserId <String> -ContactId <String> -BodyParameter <Hashtable>

-UserId: The unique identifier of the user (or their UserPrincipalName).
-ContactId: The unique identifier of the contact to be updated.
-BodyParameter: A hashtable containing the contact properties and values to update.

Note: You need ContactID and UserID to work with this cmdlet. Use Get-MgUserContact and Get-MgUser to get the IDs.

Usage Examples

Example 1: Update Contact's Email Address

This example updates the email address of a specific contact.

$params = @{
    EmailAddresses = @(
        @{
            Address = "new.email@example.com"
            Name = "John Doe"
        }
    )
}
Update-MgUserContact -UserId "user@domain.com" -ContactId "contactId123" -BodyParameter $params

Example 2: Update Contact's Name and Job Title

This example changes the first name, last name, and job title of the contact.

$params = @{
    GivenName = "Jane"
    Surname = "Doe"
    JobTitle = "Senior Manager"
}
Update-MgUserContact -UserId "user@domain.com" -ContactId "contactId456" -BodyParameter $params

Example 3: Update Contact's Phone Number

This example updates the business phone number of a contact.

$params = @{
    BusinessPhones = @("+1 555 555 1234")
}
Update-MgUserContact -UserId "user@domain.com" -ContactId "contactId789" -BodyParameter $params

Example 4: Update Multiple Contact Details

This example updates multiple details for a contact, including their name, email address, and phone number.

$params = @{
    GivenName = "Michael"
    Surname = "Smith"
    EmailAddresses = @(
        @{
            Address = "michael.smith@example.com"
            Name = "Michael Smith"
        }
    )
    BusinessPhones = @("+1 555 555 6789")
}
Update-MgUserContact -UserId "user@domain.com" -ContactId "contactId101" -BodyParameter $params

Cmdlet Tips

Hashtable Structure: Always ensure that the hashtable provided to -BodyParameter follows the correct structure. Each property must be correctly named and formatted according to Microsoft documentation.
Testing Changes: Before running updates on live data, consider testing the cmdlet in a controlled environment to ensure that the hashtable is constructed correctly.
Mandatory Fields: Certain fields, such as GivenName or EmailAddresses, may be required depending on your update scenario. Always validate the input data before execution.

Use Cases

Keeping External Contact Information Up-to-Date:

Scenario: Organizations often maintain a directory of external contacts, including vendors, clients, and partners, which can quickly become outdated if not regularly updated.
Implementation: Use Update-MgUserContact to modify contact details such as email addresses, phone numbers, and job titles to reflect the most current information.
Benefit: Ensures that communication with external stakeholders remains smooth and accurate, reducing the risk of missed opportunities or miscommunication due to outdated contact details.

Standardizing Contact Information Across the Organization:

Scenario: To maintain consistency in communication, organizations may need to standardize the way external contacts are stored, ensuring that naming conventions and data formats are uniform.
Implementation: Use Update-MgUserContact to automate the standardization of contact details, such as setting uniform job title formats or normalizing phone numbers across the organization.
Benefit: Improves the accuracy and professionalism of the contact directory, making it easier for employees to quickly locate and connect with the right contacts.

Synchronizing Contact Data with CRM Systems:

Scenario: Organizations that use CRM systems need to ensure that their external contacts in Microsoft 365 are synchronized with the CRM database to maintain accurate and up-to-date information.
Implementation: Use Update-MgUserContact to automatically update contact records in Microsoft 365 when changes are made in the CRM system, ensuring consistency between the two platforms.
Benefit: Enhances data integrity by ensuring that all contact information is consistent and current across multiple systems, reducing manual data entry and errors.

Bulk Updating Contact Details During Organizational Changes:

Scenario: During mergers, acquisitions, or other large-scale organizational changes, contact details may need to be updated in bulk to reflect the new company structure or branding.
Implementation: Use Update-MgUserContact to bulk update the email domains, company names, or other relevant contact information for multiple entries at once.
Benefit: Saves time and effort by automating the update process, ensuring that all contact information is immediately aligned with the new organizational standards.

Possible Errors & Solutions

Error: InvalidAuthenticationToken

Cause: The provided token is expired or invalid.

Solution: Refresh your authentication token by reconnecting to Microsoft Graph using Connect-MgGraph.

Connect-MgGraph -Scopes "Contacts.ReadWrite"
Update-MgUserContact -UserId "user@domain.com" -ContactId "contactId123" -BodyParameter $params

Error: ResourceNotFound

Cause: The specified UserId or ContactId does not exist.

Solution: Verify that the UserId and ContactId are correct and correspond to existing resources.

Get-MgUser -UserId "user@domain.com"
Get-MgUserContact -UserId "user@domain.com" -ContactId "contactId123"

Error: BadRequest

Cause: The -BodyParameter hashtable is incorrectly formatted.

Solution: Double-check the structure of the hashtable. Ensure that property names and values are correctly formatted according to Microsoft documentation.

$params = @{
    GivenName = "Jane"
    Surname = "Doe"
}
Update-MgUserContact -UserId "user@domain.com" -ContactId "contactId123" -BodyParameter $params

Error: InsufficientPermissions

Cause: The account being used does not have the necessary permissions.

Solution: Ensure that the account has sufficient permissions to update user contacts. You may need to grant additional permissions in the Azure portal.Contacts.ReadWrite is the required Graph API permission.

# Ensure the account has Contacts.ReadWrite permission
Update-MgUserContact -UserId "user@domain.com" -ContactId "contactId123" -BodyParameter $params

Conclusion

The Update-MgUserContact cmdlet is an essential tool for managing user contacts within Microsoft 365. By following the correct -BodyParameter hashtable structure and understanding the cmdlet's usage scenarios, administrators can efficiently maintain accurate contact information across their organization. Whether for small updates or large-scale changes, this cmdlet provides the flexibility and power needed to keep your contact information up to date.

Additional Resources:

Microsoft Graph PowerShell Module Documentation
Microsoft Graph API Documentation

Using Get-MgDirectoryRole in Graph PowerShell
Using Get-MgUserLicenseDetail in Graph PowerShell
Using Find-GraphMgCommand in Graph PowerShell
Connect to Microsoft 365 Using PowerShell
How to Create Bulk Users in Office 365 Using Graph PowerShell?
Create Microsoft 365 Group Using Microsoft Graph PowerShell
Block Microsoft 365 User Using Microsoft Graph PowerShell
Assign Microsoft 365 License Using Graph PowerShell
Microsoft 365 User Management Using Graph PowerShell
Checking Group Membership in Microsoft 365
Bulk Assign Microsoft 365 License
Find Inactive Users in Microsoft 365
Using Powershell Graph Search Query
Using Powershell Graph Filter Query
Using Where-Object In Graph PowerShell
Using Expand Property In Graph PowerShell
Using Select Object In Graph PowerShell
Using -Contains Operator In Graph PowerShell
Add User to Multiple Microsoft 365 Groups Using Graph PowerShell
Get Microsoft 365 User Location Using Graph PowerShell
Import Microsoft 365 Groups from CSV File Using Graph PowerShell
Microsoft 365 Group User Import Using Graph PowerShell