Update insightsSettings

Article
10/05/2022
11 minutes to read

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Update the privacy settings to display or return the specified type of insights in an organization. The type of settings can be contact insights, item insights, or people insights.

To learn more about customizing insights privacy for your organization, see:

Permissions

To update settings for contact insights, one of the following permissions is required to call this API. To learn more, including how to choose permissions, see permissions.

Permission type	Permissions (from least to most privileged)
Delegated (work or school account)	Organization.ReadWrite.All
Delegated (personal Microsoft account)	Not supported.
Application	Not supported.

To update settings for item insights or people insights, one of the following permissions is required to call this API. To learn more, including how to choose permissions, see permissions.

Permission type	Permissions (from least to most privileged)
Delegated (work or school account)	User.ReadWrite.All
Delegated (personal Microsoft account)	Not supported.
Application	Not supported.

Note: Using delegated permissions for this operation to update insights for contacts, item, or people requires the signed-in user to have a global administrator role.

HTTP request

To update settings for contact insights:

PATCH /organization/{organizationId}/settings/contactInsights

To update settings for item insights:

PATCH /organization/{organizationId}/settings/itemInsights

To update settings for people insights:

PATCH /organization/{organizationId}/settings/peopleInsights

Request headers

Header	Value
Authorization	Bearer {token}. Required.
Content-Type	application/json

Request body

In the request body, supply the values for relevant fields that should be updated. Existing properties that are not included in the request body will maintain their previous values or be recalculated based on changes to other property values. For best performance you shouldn't include existing values that haven't changed.

Property	Type	Description
isEnabledInOrganization	Boolean	`true` if the specified type of insights are enabled for the organization; `false` if the specified type of insights are disabled for all users without exceptions. Default is `true`. Optional.
disabledForGroup	String	The ID of an Azure AD group, of which the specified type of insights are disabled for its members. Default is `empty`. Optional.

Note: This operation does not verify the disabledForGroup property value if you include it in the request body. If you set the disabledForGroup property to a string, this operation does not check the existence of the corresponding Azure AD group. This means, if you set disabledForGroup to an Azure AD group that does not exist or is deleted afterwards, this operation will not be able to identify any group membership and disable item or people insights for any specific users. If isEnabledInOrganization is set to true, the operation will enable the specified type of insights for all the users in the organization.

Response

If successful, this method returns a 200 OK response code and insightsSettings object in the response body.

Examples

Example 1: Update settings for contact insights

Request

The following is an example of a request that shows how an admin updates isEnabledInOrganization to enable contact insights for the specified organization; the default for isEnabledInOrganization is false, disabling contact insights. The example also sets the disabledForGroup privacy setting to prohibit displaying user's contact insights in a particular Azure AD group.

PATCH https://graph.microsoft.com/beta/organization/{organizationId}/settings/contactInsights
Content-type: application/json

{
  "isEnabledInOrganization": true,
  "disabledForGroup": "edbfe4fb-ec70-4300-928f-dbb2ae86c981"
}


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var insightsSettings = new InsightsSettings
{
	IsEnabledInOrganization = true,
	DisabledForGroup = "edbfe4fb-ec70-4300-928f-dbb2ae86c981"
};

await graphClient.Organization["{organization-id}"].Settings.ContactInsights
	.Request()
	.UpdateAsync(insightsSettings);

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

const insightsSettings = {
  isEnabledInOrganization: true,
  disabledForGroup: 'edbfe4fb-ec70-4300-928f-dbb2ae86c981'
};

await client.api('/organization/{organizationId}/settings/contactInsights')
	.version('beta')
	.update(insightsSettings);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

InsightsSettings insightsSettings = new InsightsSettings();
insightsSettings.isEnabledInOrganization = true;
insightsSettings.disabledForGroup = "edbfe4fb-ec70-4300-928f-dbb2ae86c981";

graphClient.organization("{organizationId}").settings().contactInsights()
	.buildRequest()
	.patch(insightsSettings);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestBody := graphmodels.NewInsightsSettings()
isEnabledInOrganization := true
requestBody.SetIsEnabledInOrganization(&isEnabledInOrganization) 
disabledForGroup := "edbfe4fb-ec70-4300-928f-dbb2ae86c981"
requestBody.SetDisabledForGroup(&disabledForGroup) 

result, err := graphClient.OrganizationById("organization-id").Settings().ContactInsights().Patch(context.Background(), requestBody, nil)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Identity.DirectoryManagement

$params = @{
	IsEnabledInOrganization = $true
	DisabledForGroup = "edbfe4fb-ec70-4300-928f-dbb2ae86c981"
}

Update-MgOrganizationSettingContactInsight -OrganizationId $organizationId -BodyParameter $params

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestBody = new InsightsSettings();
$requestBody->setIsEnabledInOrganization(true);

$requestBody->setDisabledForGroup('edbfe4fb-ec70-4300-928f-dbb2ae86c981');



$requestResult = $graphServiceClient->organizationById('organization-id')->settings()->contactInsights()->patch($requestBody);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

The following is an example of the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
  "isEnabledInOrganization": true,
  "disabledForGroup": "edbfe4fb-ec70-4300-928f-dbb2ae86c981"
}

Example 2: Update settings for item insights

Request

Here is an example request that shows how an admin updates "disabledForGroup" privacy setting in order to prohibit displaying item insights of users in a particular Azure AD group.

PATCH https://graph.microsoft.com/beta/organization/{organizationId}/settings/itemInsights
Content-type: application/json

{
  "disabledForGroup": "edbfe4fb-ec70-4300-928f-dbb2ae86c981"
}


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var insightsSettings = new InsightsSettings
{
	DisabledForGroup = "edbfe4fb-ec70-4300-928f-dbb2ae86c981"
};

await graphClient.Organization["{organization-id}"].Settings.ItemInsights
	.Request()
	.UpdateAsync(insightsSettings);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

const insightsSettings = {
  disabledForGroup: 'edbfe4fb-ec70-4300-928f-dbb2ae86c981'
};

await client.api('/organization/{organizationId}/settings/itemInsights')
	.version('beta')
	.update(insightsSettings);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

InsightsSettings insightsSettings = new InsightsSettings();
insightsSettings.disabledForGroup = "edbfe4fb-ec70-4300-928f-dbb2ae86c981";

graphClient.organization("{organizationId}").settings().itemInsights()
	.buildRequest()
	.patch(insightsSettings);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestBody := graphmodels.NewInsightsSettings()
disabledForGroup := "edbfe4fb-ec70-4300-928f-dbb2ae86c981"
requestBody.SetDisabledForGroup(&disabledForGroup) 

result, err := graphClient.OrganizationById("organization-id").Settings().ItemInsights().Patch(context.Background(), requestBody, nil)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Identity.DirectoryManagement

$params = @{
	DisabledForGroup = "edbfe4fb-ec70-4300-928f-dbb2ae86c981"
}

Update-MgOrganizationSettingItemInsight -OrganizationId $organizationId -BodyParameter $params

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestBody = new InsightsSettings();
$requestBody->setDisabledForGroup('edbfe4fb-ec70-4300-928f-dbb2ae86c981');



$requestResult = $graphServiceClient->organizationById('organization-id')->settings()->itemInsights()->patch($requestBody);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

Here is an example of the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
  "disabledForGroup": "edbfe4fb-ec70-4300-928f-dbb2ae86c981"
}

Example 3: Update settings for people insights

Request

The following is an example of a request that shows how an admin updates "disabledForGroup" privacy setting in order to prohibit displaying people insights of users in a particular Azure AD group.

PATCH https://graph.microsoft.com/beta/organization/{organizationId}/settings/peopleInsights
Content-type: application/json

{
  "isEnabledInOrganization": true,
  "disabledForGroup": "edbfe4fb-ec70-4300-928f-dbb2ae86c981"
}


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var insightsSettings = new InsightsSettings
{
	IsEnabledInOrganization = true,
	DisabledForGroup = "edbfe4fb-ec70-4300-928f-dbb2ae86c981"
};

await graphClient.Organization["{organization-id}"].Settings.PeopleInsights
	.Request()
	.UpdateAsync(insightsSettings);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

const insightsSettings = {
  isEnabledInOrganization: true,
  disabledForGroup: 'edbfe4fb-ec70-4300-928f-dbb2ae86c981'
};

await client.api('/organization/{organizationId}/settings/peopleInsights')
	.version('beta')
	.update(insightsSettings);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

InsightsSettings insightsSettings = new InsightsSettings();
insightsSettings.isEnabledInOrganization = true;
insightsSettings.disabledForGroup = "edbfe4fb-ec70-4300-928f-dbb2ae86c981";

graphClient.organization("{organizationId}").settings().peopleInsights()
	.buildRequest()
	.patch(insightsSettings);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestBody := graphmodels.NewInsightsSettings()
isEnabledInOrganization := true
requestBody.SetIsEnabledInOrganization(&isEnabledInOrganization) 
disabledForGroup := "edbfe4fb-ec70-4300-928f-dbb2ae86c981"
requestBody.SetDisabledForGroup(&disabledForGroup) 

result, err := graphClient.OrganizationById("organization-id").Settings().PeopleInsights().Patch(context.Background(), requestBody, nil)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Identity.DirectoryManagement

$params = @{
	IsEnabledInOrganization = $true
	DisabledForGroup = "edbfe4fb-ec70-4300-928f-dbb2ae86c981"
}

Update-MgOrganizationSettingPersonInsight -OrganizationId $organizationId -BodyParameter $params

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestBody = new InsightsSettings();
$requestBody->setIsEnabledInOrganization(true);

$requestBody->setDisabledForGroup('edbfe4fb-ec70-4300-928f-dbb2ae86c981');



$requestResult = $graphServiceClient->organizationById('organization-id')->settings()->peopleInsights()->patch($requestBody);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

The following is an example of the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
  "isEnabledInOrganization": true,
  "disabledForGroup": "edbfe4fb-ec70-4300-928f-dbb2ae86c981"
}

Update insightsSettings

Permissions

HTTP request

Request headers

Request body

Response

Examples

Example 1: Update settings for contact insights

Request

Response

Example 2: Update settings for item insights

Request

Response

Example 3: Update settings for people insights

Request

Response

Feedback

Additional resources

Additional resources