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.

Principal Type

A great tip by Paul Tavares about the principal type value. It supports multiple flags by using bitwise. Setting the value to 13 or 1101 in binary, which translates as flags 1, 4, & 8 true set to true and flag 2 set to false. These flags relates to the Principal Type “User”, “SecurityGroup” and “SharePointGroup” flags to be selected.

React Component

The gd-sprest-react library contains SharePoint components, including a people picker component.

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:
$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:
$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.

7 thoughts on “SharePoint People Picker REST API”

  1. I’m not using the library and attempting to send the JSON request without any luck. Can you help me visualize what the entire request looks like?

  2. I believe this information has been provided, referring to the “Request” section. It shows the body of the request you would send to the JSON request. As stated, it would be a “POST” request. The url endpoint would be “[web url]/_api/SP.UI.ApplicationPages.ClientPeoplePickerWebServiceInterface”.

    Please let me know what other information you would need for the JSON request, and I’ll do my best to help.

  3. Thanks for this post Gunjan. It was very helpful to me in converting my people picker from SOAP calls to REST.
    One think I found out in the process, which is not mentioned above but other might find it useful, is that PrincipalType supports multiple values by using bitwise. you can observe this in SharePoint regular calls when you see PrincipalType being set to 13 which searches for User and Groups (bitwise 1|4|8). The support for bitwise combination is briefly mentioned here: https://msdn.microsoft.com/en-us/library/microsoft.sharepoint.client.utilities.principaltype.aspx?f=255&MSPPError=-2147217396

    Since this is a normal search for Lists whose Column has been set to “People and Groups” I figure I would mention it here in case it helps others.

    Thanks again for the great post. 🙂

Leave a Reply

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