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.

2 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.

Leave a Reply

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