Introduction

The SharePoint Home Site experiences have moved to Viva Connections and is managed from the Microsoft 365 admin centre through the Viva Connections admin centre

I started exploring how to manage these SharePoint Home Sites/Viva Experiences using browser’s developer tools, considering I had little luck with the SPO PowerShell, PnP PowerShell, and CLI for M365. These PowerShell experiences will be updated at some point to work with the updated Viva Connections Experience.

SPO PowerShell cmdlets

The SPO PowerShell cmdlets are not effective in managing the Viva Connections Home site at the time of publishing this blog post in November 2024. Hopefully, they will soon be fixed to allow them to be used.

Set-SPOHomeSite

The cmdlet Set-SPOHomeSite requires the site to have been specified as a Home site; otherwise, running the script will throw the following error.

Set-SPOHomeSite : [Error ID: 8f95a9e8-4aab-49d7-85b9-5fe9954dbe5c] This site hasn’t been added as a home site or Viva Connections experience. At line:1 char:1

+ Set-SPOHomeSite -HomeSiteUrl https://reshmeeauckloo.sharepoint.com/si ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [Set-SPOHomeSite], ServerException
    + FullyQualifiedErrorId : Microsoft.SharePoint.Client.ServerException,Microsoft.Online.SharePoint.PowerShell.SPOHomeSite+SetHomeSite

Remove-SPOHomeSite

If there are more than one Home Site defined within the Viva Connections, the cmdlet Remove-SPOHomeSite fails with a warning.

WARNING: There are more than one home site or Viva Connections, please go to Microsoft 365 admin center to configure the settings. To learn more about home sites, go to aka.ms/homesites.

Get-SPOHomeSite

If there are more than one Home Site defined within the Viva Connections, the cmdlet Remove-SPOHomeSite returns one Home Site with a warning.

WARNING: We recommend using Microsoft 365 admin center instead of this command. If you have multiple home sites, this command returns only the site with the highest priority. To learn more about home sit es, go to aka.ms/homesites.

REST APIs Endpoints for Viva Connections Home Site Configuration

AddHomeSite

Only a valid Home Site can be added to the Viva Connections experiences.

The endpoint ValidateHomeSite can be used to validate whether the specified home site url can be added to the Viva Connections experiences.

The endpoint AddHomeSite is used to create the Viva Connections experience.

Endpoint	Payload	Response
/_api/SPO.Tenant/ValidateHomeSite	{"validationActionType":0,"siteUrl":"testcommsite"}	{ "odata.metadata": "", "odata.null": true }
Example Image
/_api/SPO.Tenant/AddHomeSite	{"homeSiteUrl":"}	{ "odata.metadata": "", "Audiences": [], "IsInDraftMode": true, "IsVivaBackendSite": false, "SiteId": "ca49054c-85f3-41eb-a290-46ffda8f219c", "TargetedLicenseType": 0, "Title": "testcommsite", "Url": "", "VivaConnectionsDefaultStart": false, "WebId": "256c4f0f-e372-47b4-a891-b4888e829e20" }

RemoveTargetedSite

To remove the Viva Connections experience, use the endpoint RemoveTargetedSite

Endpoint	Payload	Response
https://admin.microsoft.com/_api/SPO.Tenant/RemoveTargetedSite	{"siteId":"ca49054c-85f3-41eb-a290-46ffda8f219c"}	{ "odata.metadata": "", "odata.null": true }
Example Image

UpdateTargetedSite endpoint

To update the properties Viva Connections experiences, the endpoint UpdateTargetedSite can be used.

API Endpoints for Configuring Viva Connections Home Site

Get Home Site endpoint

The endpoint GetTargetedSitesDetails can be used to get list of Home Sites/Viva Connection Experiences.

Endpoint: /_api/SPO.Tenant/GetTargetedSitesDetails

Example response:

{
    "odata.metadata": "https://reshmeeauckloo-admin.sharepoint.com/_api/$metadata#Collection(SP.TargetedSiteDetails)",
    "value": [
        {
            "Audiences": [
                {
                    "Email": "ColumnSearchable@reshmeeauckloo.onmicrosoft.com",
                    "Id": "978b5280-4f80-47ea-a1db-b0d1d2fb1ba4",
                    "Title": "ColumnSearchable Members"
                },
                {
                    "Email": "contosoteam@reshmeeauckloo.onmicrosoft.com",
                    "Id": "21af775d-17b3-4637-94a4-2ba8625277cb",
                    "Title": "Contoso TeamR Members"
                }
            ],
            "IsInDraftMode": false,
            "IsVivaBackendSite": false,
            "SiteId": "431d7819-4aaf-49a1-b664-b2fe9e609b63",
            "TargetedLicenseType": 2,
            "Title": "The Landing",
            "Url": "https://reshmeeauckloo.sharepoint.com/sites/TheLanding",
            "VivaConnectionsDefaultStart": true,
            "WebId": "626c1724-8ac8-45d5-af87-c07c752fab75"
        },
        {
            "Audiences": [],
            "IsInDraftMode": false,
            "IsVivaBackendSite": false,
            "SiteId": "45d4a135-40e4-4571-8340-61d17fdfd58a",
            "TargetedLicenseType": 0,
            "Title": "Contoso Electronics",
            "Url": "https://reshmeeauckloo.sharepoint.com/sites/contosoportal",
            "VivaConnectionsDefaultStart": true,
            "WebId": "9418e2a1-855c-4752-8dd4-48693f43b10a"
        },
        {
            "Audiences": [],
            "IsInDraftMode": true,
            "IsVivaBackendSite": false,
            "SiteId": "5880cb96-a29d-46a1-890c-75baa1504281",
            "TargetedLicenseType": 0,
            "Title": "TestEventsList",
            "Url": "https://reshmeeauckloo.sharepoint.com/sites/TestEventsList",
            "VivaConnectionsDefaultStart": false,
            "WebId": "f1c70b8f-6110-41de-90cf-375442f3a148"
        },
        {
            "Audiences": [],
            "IsInDraftMode": true,
            "IsVivaBackendSite": false,
            "SiteId": "b492e346-8262-4576-a4e5-50fa75c1862c",
            "TargetedLicenseType": 0,
            "Title": "Contoso Inc",
            "Url": "https://reshmeeauckloo.sharepoint.com/sites/Contosoinc-intranet",
            "VivaConnectionsDefaultStart": false,
            "WebId": "3f8e101c-87f0-47cd-91fe-e5e90ca05362"
        },
        {
            "Audiences": [],
            "IsInDraftMode": true,
            "IsVivaBackendSite": false,
            "SiteId": "ca49054c-85f3-41eb-a290-46ffda8f219c",
            "TargetedLicenseType": 0,
            "Title": "testcommsite",
            "Url": "https://reshmeeauckloo.sharepoint.com/sites/testcomms",
            "VivaConnectionsDefaultStart": true,
            "WebId": "256c4f0f-e372-47b4-a891-b4888e829e20"
        }
    ]
}

The response above formatted as table to read easily.

Notes:

• Audiences include details such as email addresses, IDs, and titles when applicable. In cases with no audiences, the field is marked as “None.”
• Targeted License Type indicates the targeted user license category:
  • 0 for Everyone,
  • 1 for Frontline Workers,
  • 2 for Information Workers.

PnP and CLI for M365 PowerShell cmdlets

The PnP and CLI for M365 PowerShell cmdlets currently need improvements to work seamlessly with the latest changes to the Home Site feature in Viva Connections Experiences.

Available PnP PowerShell Cmdlets

PnP PowerShell provides several cmdlets to manage Home Sites:

• Add-PnPHomeSite

Read more from Add-PnPHomeSite

• Set-PnPHomeSite
• Remove-PnPHomeSite
• Get-PnPHomeSite

Licensing Requirements

You must have an Enterprise (E), Frontline (F), or Academic (A) license type to create a Viva Connections experience. Users with a Microsoft 365 subscription (E, F, or A license) are limited to creating and using one experience. If you want to create or use two or more experiences (up to 50), then every user in your tenant must have a Microsoft Viva Suite or Viva Communications and Communities license. See Microsoft Viva plans and pricing for more info.

Testing and Feedback

I have tested these endpoints against multiple Viva Connections experiences, not just a single experience. If you are using a single experience, I would be happy to hear your feedback on whether the endpoints used behind the scenes are the same.

Conclusion

The REST API endpoints discussed above can be used within any scripting or coding platform, as well as within Power Automate using the HTTP action. These endpoints provide a flexible way to manage Viva Connections Home Sites until the PowerShell cmdlets within SPO, PnP, and CLI for M365 are updated to accommodate the latest changes.

References

Viva Connections set up Set-SPOHomeSite

• Viva Connections Experiences
• REST API
• Home Site
• SharePoint