Use the Microsoft Search API to search people
Microsoft Graph applications can use the Microsoft Search API to retrieve the people who are most relevant to a user. Relevance is determined by the user’s communication and collaboration patterns and business relationships. People can be local contacts or from an organization’s directory or people from recent communications.
Along with generating this insight, search also provides fuzzy matching search support and the ability to retrieve the list of users relevant to another user in the signed-in user's organization.
People APIs
You can use the following APIs to search for people inside an organization.
- /search
- /people
Note
We recommended that users call the /search endpoint instead of the /people endpoint. Going forward, all future investments will only be available in the /search endpoint; the /people endpoint is in maintenance mode.
Returned people properties
The people API returns the following set of properties.
| Property | Type |
|---|---|
| additionalOfficeLocation | String |
| companyName | String |
| department | String |
| displayName | String |
| emailAddress | String |
| givenName | String |
| hitId | String |
| imAddress | String |
| jobTitle | String |
| officeLocation | String |
| personType | String |
| phones | String |
| rank | Integer |
| summary | String |
| surname | String |
| userPrincipalName | String |
Person types
The following table shows people types and subtypes supported in the people API.
| Supported people, groups, and rooms variations | Recipient type details | Mailbox | Directory | People type | People subtype | Notes |
|---|---|---|---|---|---|---|
| Organization user | UserMailbox, MailUser | Y | Y | Person | OrganizationUser | A user who belongs to the organization. |
| Organization user without email address | User | Y (Off by default) | Y (Off by default) | Person | OrganizationUser | A user who belongs to the organization. |
| Organization contact | MailContact, Contact | N | Y | Person | OrganizationContact | A contact explicitly added to the global address list (GAL) by the tenant admin, but that isn't part of the organization. |
| Private contact | Contact | Y | N/A | Person | PersonalContact | A contact explicitly created by the user that doesn't belong to the organization. If the user manually adds to its contacts someone part of the organization, it will still be classified as OrganizationUser. |
| Private contact without email address | Contact | Y (Off by default) | N/A | Person | PersonalContact | A contact explicitly created by the user that doesn't belong to the organization. If the user manually adds to its contacts someone part of the organization, it will still be classified as OrganizationUser. |
| Implicit contact from communication history | Contact | Y | N/A | Person | ImplicitContact | A contact inferred from communication history (email and chat) that we don't have enough information about to determine if it is a person, group, etc. On business accounts, this will always be an outside organization contact, as inside organization contacts found in the communication history will always be classified as OrganizationUser. For consumer accounts, anything that is not a PersonalContact is classified as ImplicitContact. |
| Implicit contact from chat history | Contact | Y | N/A | Person | ChatImplicitContact | Same as ImplicitContact, but when the communication history is exclusively from chat. |
| Room | Rooms | Y | Y | Other | Room | |
| Guest | GuestUser | Y | Y | Other | Guest | |
| Hidden guest | GuestUser | Y (Off by default) | Y (Off by default) | Other | Guest | |
| Modern group | Group | Y | Y | Group | UnifiedGroup | Group known as: Exchange 365 Group, Modern Groups, Microsoft 365 Groups. For more information about Microsoft 365 Groups, see Learn about Microsoft 365 Groups. |
| Teams group | Group | Y | Y | Group | UnifiedGroup | Same as Microsoft 365 Groups, but represents internally a team in Microsoft Teams. |
| Hidden Teams group | Group | Y (Off by default) | Y | Group | UnifiedGroup | Hidden Teams group. |
| Distribution list | Group | Y | Y | Group | PublicDistributionList | Classic Exchange distribution list or mail enabled security group. |
| Personal distribution list | Contact | Y (Off by default) | N/A | Group | PersonalDistributionList | A virtual distribution group created by the user as a helper to send emails to multiple contacts in an easy way. Used only for Outlook on the web compose as a UX feature, not returned for other callers. |
| Hidden object of any type except Guest and Teams group | N | N |
Request details
Make the results of the people API more specific by giving additional details when you make a request. The following are a few ways to make the requests more specific.
Example 1: Mailbox results only
"Provenances": ["Mailbox"]
Example 2: Results from both sources
"Provenances": ["Mailbox", "Directory"]
Source of results
People results come from two sources, mailbox or directory. By default, the results will come from both sources with conflicts being removed, which ensures that same values won't be returned.
Note: In case of a conflict, directory sources are preferred.
Mailbox results consist of:
- People who sent you email
- People who you sent email to
- People you had meeting with
- People you had Teams chat with
- People in your manager's org chart
- Public contacts of the above people
Relevant aspects for the use case when a directory source searches in the global addressing list in Microsoft Entra ID:
- Not applicable for consumer users
- People who are not in the caller's global addressing list will not be returned
- People who are hidden by IBP (information barrier protocol) will not be returned
- People who are hidden in the address list will not be returned
Get more results
Specify the size to get more results. By default, 25 results or less will be returned based on the search query matches.
"Size": 25
Specify the minimum index for paging
Set the minimum index for paging to specify the initial page of results. By default, the minimum index for paging is 0 and the first result is the most relevant.
"From": 0
Select the fields to return
The API returns a set of default properties, but you can customize a request to return a specific number of properties. The following example limits the response to the DisplayName, EmailAddresses, and phones properties.
"Fields": ["DisplayName", "EmailAddresses", "phones"]
Use a filter to limit the response
Use the Filter object to limit the response to specific values. Possible filter values are: PeopleType, PeopleSubType.
The following examples show requests that use the Filter object to return people whose record contains the specified criteria.
Example 1: Filter to person suggestions
The following example limits the response to only person suggestions. The response contains both private and organization contacts.
"Filter": {
"And": [
{
"Term": {
"PeopleType": "Person"
}
}
]
},
Example 2: Filter to person suggestions within the organization
The following example limits the reponse only to business users.
"Filter": {
"And": [
{
"Term": {
"PeopleType": "Person"
}
},
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
}
]
},
Example 3: Filter to all users, distribution lists, or modern distribution list in the organization
The following example limits the response to different categories of PeopleSubtype.
"Filter": {
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "PublicDistributionList"
}
},
{
"Term": {
"PeopleSubtype": "UnifiedGroup"
}
}
]
},
Example 4: Filter to organization users and meeting rooms
The following example limits the response to organization users and meeting rooms.
"Filter": {
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "Rooms"
}
}
]
},
Example 5: Filter to organization users and guests
The following example limits the response to organization users and guests.
"Filter": {
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "Guest"
}
}
]
},
Example 6: Combine multiple filters
The following example combines multiple filters to limit the response to the specified criteria.
"Filter": {
"And": [
{
"Or": [
{
"Term": {
"PeopleType": "Person"
}
},
{
"Term": {
"PeopleType": "Other"
}
}
]
},
{
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "Guest"
}
}
]
}
]
},
Full request
Example: Search person by name
The following request gets the people most relevant to the signed-in user, based on communication and collaboration patterns and business relationships.
Request
POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"person"
],
"query": {
"queryString": "contoso"
},
"from": 0,
"size": 25
}
]
}
Response
The following is an example of the response, which contains one message that matches the search criterion.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.searchResponse",
"value": [
{
"hitsContainers": [
{
"total": 1,
"moreResultsAvailable": false,
"hits": [
{
"hitId": "fc138b85-18ac-48e0-80a4-633ae4b594e0@41f988bf-86f1-53af-91ab-2d7cd034db47",
"rank": 1,
"summary": "",
"resource": {
"@odata.type": "#microsoft.graph.person",
"displayName": "Example User",
"givenName": "User",
"surname": "User",
"department": "Finance",
"officeLocation": "London",
"userPrincipalName": "example.user@contoso.com",
"emailAddresses": [
{
"address": "example.user@contoso.com",
"rank": 1
}
],
"phones": [
{
"type": "business",
"number": "+44 (20) 12345678"
}
]
}
}
]
}
]
}
]
}