Set up administrative search answers for users in an organization (preview)

Microsoft Search lets administrators associate search terms with meanings or web pages that are specific to their organizations and include these associations as search answers. For example, users in an organization may run into an unfamiliar acronym that represents an internal project name, or a team name that is associated with a team web page. Administrators can set up acronyms, bookmarks, or QnA in the Microsoft 365 admin center, under Search & intelligence. This enables users to use search to navigate and get familiarized with their work.

Administrators can also use the Microsoft Search API in Microsoft Graph to programmatically manage administrative search answers in the organization. These answers are displayed in Microsoft Search results when triggered by an acronym or keyword defined in the available search answer resource types: acronym, bookmark, and QnA resources.

When triggered by a defined acronym or keyword, these search answers appear at the top of the search results page in your organization.

Example 1: Create a new acronym

The following request creates a new acronym that will display on the search results page when a user searches for it.

Request

HTTP

POST https://graph.microsoft.com/beta/search/acronyms
Content-Type: application/json

{
  "displayName": "GDPR",
  "standsFor": "General Data Protection Regulation",
  "description": "A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas.",
  "webUrl": "http://contoso.com/GDPR",
  "state": "published"
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Models.Search;

var requestBody = new Acronym
{
	DisplayName = "GDPR",
	StandsFor = "General Data Protection Regulation",
	Description = "A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas.",
	WebUrl = "http://contoso.com/GDPR",
	State = AnswerState.Published,
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Search.Acronyms.PostAsync(requestBody);

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta search acronyms create --body '{\
  "displayName": "GDPR",\
  "standsFor": "General Data Protection Regulation",\
  "description": "A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas.",\
  "webUrl": "http://contoso.com/GDPR",\
  "state": "published"\
}\
'

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodelssearch "github.com/microsoftgraph/msgraph-beta-sdk-go/models/search"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodelssearch.NewAcronym()
displayName := "GDPR"
requestBody.SetDisplayName(&displayName) 
standsFor := "General Data Protection Regulation"
requestBody.SetStandsFor(&standsFor) 
description := "A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas."
requestBody.SetDescription(&description) 
webUrl := "http://contoso.com/GDPR"
requestBody.SetWebUrl(&webUrl) 
state := graphmodels.PUBLISHED_ANSWERSTATE 
requestBody.SetState(&state) 

acronyms, err := graphClient.Search().Acronyms().Post(context.Background(), requestBody, nil)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Java

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

Acronym acronym = new Acronym();
acronym.displayName = "GDPR";
acronym.standsFor = "General Data Protection Regulation";
acronym.description = "A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas.";
acronym.webUrl = "http://contoso.com/GDPR";
acronym.state = AnswerState.PUBLISHED;

graphClient.search().acronyms()
	.buildRequest()
	.post(acronym);

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const acronym = {
  displayName: 'GDPR',
  standsFor: 'General Data Protection Regulation',
  description: 'A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals\' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas.',
  webUrl: 'http://contoso.com/GDPR',
  state: 'published'
};

await client.api('/search/acronyms')
	.version('beta')
	.post(acronym);

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PHP

<?php

// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Acronym();
$requestBody->setDisplayName('GDPR');
$requestBody->setStandsFor('General Data Protection Regulation');
$requestBody->setDescription('A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals\' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas.');
$requestBody->setWebUrl('http://contoso.com/GDPR');
$requestBody->setState(new AnswerState('published'));

$result = $graphServiceClient->search()->acronyms()->post($requestBody)->wait();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PowerShell

Import-Module Microsoft.Graph.Beta.Search

$params = @{
	displayName = "GDPR"
	standsFor = "General Data Protection Regulation"
	description = "A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas."
	webUrl = "http://contoso.com/GDPR"
	state = "published"
}

New-MgBetaSearchAcronym -BodyParameter $params

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Python

# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY

graph_client = GraphServiceClient(credentials, scopes)

request_body = Acronym(
	display_name = "GDPR",
	stands_for = "General Data Protection Regulation",
	description = "A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas.",
	web_url = "http://contoso.com/GDPR",
	state = AnswerState.Published,
)

result = await graph_client.search.acronyms.post(request_body)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Response

Here is an example of the response.

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "id": "733b26d5-af76-4eea-ac69-1a0ce8716897"
}

Example 2: Create a new bookmark

The following request creates a new bookmark that will display on the search results page when a user searches for at least one of its keywords.

Request

HTTP

POST https://graph.microsoft.com/beta/search/bookmarks
Content-Type: application/json

{
  "displayName": "Contoso Install Site",
  "webUrl": "http://www.contoso.com/",
  "description": "Try or buy Contoso for Home or Business and view product information",
  "keywords":  {
    "keywords": ["Contoso", "install"],
    "reservedKeywords": ["Contoso"],
    "matchSimilarKeywords": true
  },
  "state": "published"
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Models.Search;

var requestBody = new Bookmark
{
	DisplayName = "Contoso Install Site",
	WebUrl = "http://www.contoso.com/",
	Description = "Try or buy Contoso for Home or Business and view product information",
	Keywords = new AnswerKeyword
	{
		Keywords = new List<string>
		{
			"Contoso",
			"install",
		},
		ReservedKeywords = new List<string>
		{
			"Contoso",
		},
		MatchSimilarKeywords = true,
	},
	State = AnswerState.Published,
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Search.Bookmarks.PostAsync(requestBody);

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta search bookmarks create --body '{\
  "displayName": "Contoso Install Site",\
  "webUrl": "http://www.contoso.com/",\
  "description": "Try or buy Contoso for Home or Business and view product information",\
  "keywords":  {\
    "keywords": ["Contoso", "install"],\
    "reservedKeywords": ["Contoso"],\
    "matchSimilarKeywords": true\
  },\
  "state": "published"\
}\
'

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodelssearch "github.com/microsoftgraph/msgraph-beta-sdk-go/models/search"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodelssearch.NewBookmark()
displayName := "Contoso Install Site"
requestBody.SetDisplayName(&displayName) 
webUrl := "http://www.contoso.com/"
requestBody.SetWebUrl(&webUrl) 
description := "Try or buy Contoso for Home or Business and view product information"
requestBody.SetDescription(&description) 
keywords := graphmodelssearch.NewAnswerKeyword()
keywords := []string {
	"Contoso",
	"install",
}
keywords.SetKeywords(keywords)
reservedKeywords := []string {
	"Contoso",
}
keywords.SetReservedKeywords(reservedKeywords)
matchSimilarKeywords := true
keywords.SetMatchSimilarKeywords(&matchSimilarKeywords) 
requestBody.SetKeywords(keywords)
state := graphmodels.PUBLISHED_ANSWERSTATE 
requestBody.SetState(&state) 

bookmarks, err := graphClient.Search().Bookmarks().Post(context.Background(), requestBody, nil)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Java

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

Bookmark bookmark = new Bookmark();
bookmark.displayName = "Contoso Install Site";
bookmark.webUrl = "http://www.contoso.com/";
bookmark.description = "Try or buy Contoso for Home or Business and view product information";
AnswerKeyword keywords = new AnswerKeyword();
LinkedList<String> keywordsList = new LinkedList<String>();
keywordsList.add("Contoso");
keywordsList.add("install");
keywords.keywords = keywordsList;
LinkedList<String> reservedKeywordsList = new LinkedList<String>();
reservedKeywordsList.add("Contoso");
keywords.reservedKeywords = reservedKeywordsList;
keywords.matchSimilarKeywords = true;
bookmark.keywords = keywords;
bookmark.state = AnswerState.PUBLISHED;

graphClient.search().bookmarks()
	.buildRequest()
	.post(bookmark);

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const bookmark = {
  displayName: 'Contoso Install Site',
  webUrl: 'http://www.contoso.com/',
  description: 'Try or buy Contoso for Home or Business and view product information',
  keywords: {
    keywords: ['Contoso', 'install'],
    reservedKeywords: ['Contoso'],
    matchSimilarKeywords: true
  },
  state: 'published'
};

await client.api('/search/bookmarks')
	.version('beta')
	.post(bookmark);

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PHP

<?php

// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Bookmark();
$requestBody->setDisplayName('Contoso Install Site');
$requestBody->setWebUrl('http://www.contoso.com/');
$requestBody->setDescription('Try or buy Contoso for Home or Business and view product information');
$keywords = new AnswerKeyword();
$keywords->setKeywords(['Contoso', 'install', 	]);
$keywords->setReservedKeywords(['Contoso', 	]);
$keywords->setMatchSimilarKeywords(true);
$requestBody->setKeywords($keywords);
$requestBody->setState(new AnswerState('published'));

$result = $graphServiceClient->search()->bookmarks()->post($requestBody)->wait();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PowerShell

Import-Module Microsoft.Graph.Beta.Search

$params = @{
	displayName = "Contoso Install Site"
	webUrl = "http://www.contoso.com/"
	description = "Try or buy Contoso for Home or Business and view product information"
	keywords = @{
		keywords = @(
			"Contoso"
			"install"
		)
		reservedKeywords = @(
			"Contoso"
		)
		matchSimilarKeywords = $true
	}
	state = "published"
}

New-MgBetaSearchBookmark -BodyParameter $params

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Python

# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY

graph_client = GraphServiceClient(credentials, scopes)

request_body = Bookmark(
	display_name = "Contoso Install Site",
	web_url = "http://www.contoso.com/",
	description = "Try or buy Contoso for Home or Business and view product information",
	keywords = AnswerKeyword(
		keywords = [
			"Contoso",
			"install",
		],
		reserved_keywords = [
			"Contoso",
		],
		match_similar_keywords = True,
	),
	state = AnswerState.Published,
)

result = await graph_client.search.bookmarks.post(request_body)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Response

Here is an example of the response.

HTTP/1.1 201 CREATED
Location: /733b26d5-af76-4eea-ac69-1a0ce8716897
Content-Type: application/json

{
  "id": "733b26d5-af76-4eea-ac69-1a0ce8716897"
}

Next steps

• Be familiar with the Search API scenarios and capabilities: Microsoft Search API overview.
• Explore the search APIs in Graph Explorer.
• Use the Microsoft Search API to manage administrative answers.