Sharepoint Rest Api Tips For Retrieving User Data

The Problem: Retrieving User Profiles

SharePoint stores user profile information such as names, contact details, departments, titles, and profile pictures in the User Profile Service application. This service maintains a database of user profiles that can be accessed through the SharePoint REST API. The REST API provides a programmatic way to retrieve user profile data for use in custom applications and scripts.

However, there are some key things to keep in mind when querying the user profile store through the REST API. Formatting profile requests correctly is essential for successful calls. You also need to handle common errors appropriately. This article will explore tips for retrieving SharePoint user profiles using the REST interface.

Basic API Syntax for User Profiles

Here is an example GET request for retrieving user profile information. We’ll break down the different parts of the URL:

GET https://tenant.sharepoint.com/sites/site/_api/SP.UserProfiles.PeopleManager/GetPropertiesFor(accountName=@v)?@v='i:0%23.f|membership|[email protected]'  

• Endpoint – The PeopleManager endpoint inside SP.UserProfiles provides access to user profiles.
• Account reference – The @v parameter contains the account name reference in a special encoded format.
• Account name – The accountName parameter matches the reference provided in @v. This specifies the user profile returned.
• Site context – While optional, providing a site context enables permission checks against the site.

These components combined allow you to query the profile store for a specific user. We’ll explore these in more detail next.

Key Components for Querying Profiles

When constructing REST API calls for user profiles, you need to understand these key parameters:

The @v account reference

The @v parameter contains a special reference to the user account prefixed with “i:0#.f|membership|”. A typical pattern is i:0#.f|membership|[email protected]. This registered string maps the REST request to an individual user account. Formatting this parameter correctly is key for successful profile queries.

The PeopleManager endpoint

All requests to retrieve user profiles should use the PeopleManager REST endpoint inside SP.UserProfiles. This endpoint provides access to read and update people and group profile data through the User Profile Service. PeopleManager will handle permissions checks when a site is provided in the URL.

The accountName parameter

The accountName parameter should match the reference string inside @v. This indicates which user profile to return properties for from the user profile store. By changing the @v reference and account name, different profile data can be retrieved in each request.

Retrieving Profile Properties

Once the basic call syntax is understood, user profile properties can be retrieved. Some common read-only properties available include:

• PictureUrl – Path to the user’s profile picture
• Department
• Title
• Email

For example, to retrieve a user’s title:

GET https://tenant.sharepoint.com/_api/SP.UserProfiles.PeopleManager/GetPropertiesFor(accountName=@v)?@v='i:0%23.f|membership|[email protected]'&$select=Title

Reference properties on people entities can also be expanded using the $expand parameter:

GET https://tenant.sharepoint.com/_api/SP.UserProfiles.PeopleManager/GetPropertiesFor(accountName=@v)?@v='i:0%23.f|membership|[email protected]'&$select=Title&$expand=UserUrl

This enables accessing additional metadata such as permissions and group associations.

Handling Errors

When working with the user profile REST endpoint, you may encounter errors such as:

• HTTP 403 Forbidden - The user may not have permission to access profiles. Check site permissions.
• HTTP 500 Server Error - Often indicates the @v parameter is formatted incorrectly. Double check the referencing pattern.

Always handle errors appropriately - never ignore them. Log the issue and provide clear messaging to the user if problems occur.

Example Code Snippets

Here are some code examples for retrieving common user profile properties with the SharePoint REST API using JavaScript:

// Retrieve user title 

const endpointUrl = `https://tenant.sharepoint.com/_api/SP.UserProfiles.PeopleManager/GetPropertiesFor(accountName=@v)?@v='i:0%23.f|membership|[email protected]'&$select=Title`;

fetch(endpointUrl, {
  headers: { 
    "Accept": "application/json;odata=verbose"
  }
})
.then(response => response.json())
.then(data => {
  // Access title in data.d.__metadata.Title
});

// Get profile picture

const endpointUrl = `https://tenant.sharepoint.com/_api/SP.UserProfiles.PeopleManager/GetPropertiesFor(accountName=@v)?@v='i:0%23.f|membership|[email protected]'&$select=PictureUrl`;

fetch(endpointUrl, {
  headers: { 
    "Accept": "application/json;odata=verbose"
  }  
})
.then(response => response.json())  
.then(data => {
 // Access picture URL in data.d.__metadata.PictureUrl
});

Summary

The SharePoint REST API provides programmatic access to read and update user profiles stored in the User Profile Service. Key things to remember include:

• Use the PeopleManager endpoint for profile data
• Format the @v parameter correctly with the user account reference
• Retrieve common properties like Title and PictureUrl
• Handle errors appropriately in code

With this foundation, user profile data can be safely accessed using the SharePoint REST API for use in custom solutions.