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

Returned people properties

The people API returns the following set of properties.

Person types

The following table shows people types and subtypes supported in the people API.

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": "[email protected]",
                                "emailAddresses": [
                                    {
                                        "address": "[email protected]",
                                        "rank": 1
                                    }
                                ],
                                "phones": [
                                    {
                                        "type": "business",
                                        "number": "+44 (20) 12345678"
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

Next steps

• Use the Microsoft Search API to query data