SharePoint People Picker REST API

This post will cover the people picker api available in the SharePoint 2013+ environments.

Overview

The SharePoint REST API has a people picker endpoint, which is pretty powerful. I haven’t found much documentation, but here is the research I have. There are two available methods which take the same query parameters.:
* clientPeoplePickerSearchUser(queryParameters)
* clientPeoplePickerResolveUser(queryParameters)

Client People Picker Query Parameters

  • AllowEmailAddresses – Allows valid email address to be resolved and used as values.
  • AllowMultipleEntities – Enabled for multiple user or group entities.
  • AllUrlZones – Searches across all url zones for a particular web application.
  • EnabledClaimProviders
  • ForceClaims
  • MaximumEntitySuggestions (Required) – The maximum number of entities to return.
  • PrincipalSource – The principal sources to search.
    • All (15) – Search all principal sources.
    • MembershipProvider (4) – Search the current membership provider.
    • None (0) – Search no principal sources.
    • RoleProvider (8) – Search the current role provider.
    • UserInfoList (1) – Search the user information list.
    • Windows (2) – Search active directory.
  • PrincipalType – The principal types to return.
    • All (15) – Return all entity types.
    • DistributionList (2) – Return distribution list entity types.
    • None (0) – Return no principal types.
    • SecurityGroup (4) – Return security group entity types.
    • SharePointGroup (8) – Return sharepoint group entity types.
    • User (1) – Return user entity types.
  • QueryString – The search term.
  • Required
  • SharePointGroupID – The SharePoint group id to limit the search to.
  • UrlZone – The url zone to search within a particular web application.
    • Custom (3) – Search the custom zone.
    • Default (0) – Search the default zone.
    • Extranet (4) – Search the extranet zone.
    • Internet (2) – Search the internet zone.
    • Intranet (1) – Search the intranet zone.
  • UrlZoneSpecified
  • WebRequired if you are limiting your search to a SharePoint group
  • WebApplicationID – The web application to limit the search to.

Demo

I will be using the gd-sprest framework to demonstrate the execution of the calls. For this example, I have the library referenced on the page and am using the browser’s console window to execute the available methods.

clientPeoplePickerSearchUser

For this example, I’m searching for myself in a SharePoint Online environment. This will target the “Display Name” of the user.

JS Code:
(new $REST.PeoplePicker()).clientPeoplePickerSearchUser({
    MaximumEntitySuggestions: 10,
    PrincipalSource: 15,
    PrincipalType: 15,
    QueryString: "Gunjan Datta"
}).executeAndWait();
Request

For those who don’t want to use the library, the request is a POST. The query parameters are passed in the body of the request:

{
    "queryParams": {
        "__metadata": {
            "type": "SP.UI.ApplicationPages.ClientPeoplePickerQueryParameters"
        },
        "MaximumEntitySuggestions":10,
        "PrincipalSource":15,
        "PrincipalType":15,
        "QueryString":"Gunjan Datta"
    }
}
Output

The output of the query returned the correct user account.

clientPeoplePickerResolveUser

For this example, I’m resolving a user by their email address.

JS Code:
(new $REST.PeoplePicker()).clientPeoplePickerResolveUser({
    AllowEmailAddresses: true,
    MaximumEntitySuggestions: 10,
    PrincipalSource: 15,
    PrincipalType: 15,
    QueryString: "me@dattabase.com"
}).executeAndWait();
Request

For those who don’t want to use the library, the request is a POST. The query parameters are passed in the body of the request:

{
    "queryParams": {
        "__metadata": {
            "type": "SP.UI.ApplicationPages.ClientPeoplePickerQueryParameters"
        },
        "AllowEmailAddresses":true,
        "MaximumEntitySuggestions":10,
        "PrincipalSource":15,
        "PrincipalType":15,
        "QueryString":"me@dattabase.com"
    }
}
Output

The output of the query returned the correct user account.

Leave a Reply

Your email address will not be published. Required fields are marked *