People API available in Microsoft Graph v1.0

Microsoft Graph team

We’d like to give you a heads-up on some changes coming to the People API. We have incorporated valuable feedback from customers during the preview period and will start rolling out the changes over the next couple of weeks to Microsoft Graph v1.0 and beta endpoints.

Update: The People API is now available in Microsoft Graph v1.0. To learn more about how to use the People API in v1.0, see our reference documentation and the article Get information about relevant people.

The updates described in this post are breaking changes. If you are using the People API in your app, you’ll need to update it to accommodate these changes.

Important: The updates described in this post will begin to roll out to the Microsoft Graph beta endpoint on September 7. If you have not already done so, we recommend that you start using the People API in Microsoft Graph v1.0 to avoid any issues caused by the breaking changes.

Permissions

The API now requires one of two scopes: People.Read or People.Read.All.

  • People.Read will continue to be required for general People API calls, for example https://graph.microsoft.com/beta/me/people/. People.Read will require end user consent.
  • We are introducing People.Read.All; which will be required to retrieve the people most relevant to a specified user in the signed-in user’s organization (https://graph.microsoft.com/v1.0/users(‘{id}’)/people) calls. People.Read.All will require admin consent.

Person resource

  1. We have consolidated the personType, mailboxType and sources properties into one property called personType.
  2. The new personType property consists of two strings, class and subclass:
    <ComplexType Name="personType">
        <Property Name="class" Type="Edm.String"/>
        <Property Name="subclass" Type="Edm.String"/>
    </ComplexType>

The following are the possible values for class and subclass.

class

subclass

Description

Person

 

 

 

OrganizationUser

User in the signed-in user’s organization.

 

PersonalContact

Contact added to the signed-in user’s address book.

 

OrganizationContact

Contact added to the organization’s address book.

 

ImplicitContact

Entity deemed relevant to the signed-in user based on communication, collaboration, or business signals.

 

Unknown

 

Group

 

 

 

UnifiedGroup

Azure Active Directory group, such as an Office 365 group

 

ImplicitGroup

Entity group deemed relevant to the signed-in user based on communication, collaboration, or business signals.

 

PublicDistributionList

Public contact list in the signed-in user’s organization.

 

PersonalDistributionList

Contact list in the signed-in user’s address book.

 

Unknown

 

Other

 

 

 

Room

Room mailbox in the signed-in user’s organization.

 

Guest

Azure Active Directory business-to-business (B2B) collaboration user.

 

Unknown

 

3. Renamed the title property to jobTitle to align more closely with other APIs.

4. Renamed the emailAddresses property to scoredEmailAddresses, which is now a collection of scoredEmailAddresses.

5. Replaced the rankedEmailAddresses entity type by scoredEmailAddress type, which consists of two properties, address and relevanceScore.

Updated schema

The following is the schema that includes all the changes described in this post.

<EntityType Name="person" BaseType="microsoft.graph.entity">
    <Property Name="displayName" Type="Edm.String" />
    <Property Name="givenName" Type="Edm.String" />
    <Property Name="surname" Type="Edm.String" />
    <Property Name="birthday" Type="Edm.String" />
    <Property Name="personNotes" Type="Edm.String" />
    <Property Name="imAddress" Type="Edm.String" />
    <Property Name="isFavorite" Type="Edm.Boolean" />
    <Property Name="scoredEmailAddresses" Type="Collection(microsoft.graph.scoredEmailAddress)" />
    <Property Name="phones" Type="Collection(microsoft.graph.phone)" />
    <Property Name="postalAddresses" Type="Collection(microsoft.graph.location)" />
    <Property Name="websites" Type="Collection(microsoft.graph.website)" />
    <Property Name="jobTitle" Type="Edm.String" />
    <Property Name="companyName" Type="Edm.String" />
    <Property Name="yomiCompany" Type="Edm.String" />
    <Property Name="department" Type="Edm.String" />
    <Property Name="officeLocation" Type="Edm.String" />
    <Property Name="profession" Type="Edm.String" />
    <Property Name="personType" Type="microsoft.graph.personType" />
    <Property Name="userPrincipalName" Type="Edm.String" />
 </EntityType>
 <ComplexType Name="scoredEmailAddress">
    <Property Name="address" Type="Edm.String" />
    <Property Name="relevanceScore" Type="Edm.Double" />
 </ComplexType>
 <ComplexType Name="personType">
    <Property Name="class" Type="Edm.String" />
    <Property Name="subclass" Type="Edm.String" />
 </ComplexType>

As a reminder, the updates described in this post are breaking changes. If you are using the People API in your app, you’ll need to update it to accommodate these changes.

After the changes are fully deployed in the next couple of weeks, you can start using the new schema in your app. We will also update our API documentation to reflect these changes. Please leave questions in the comment section below and happy coding!

Feedback usabilla icon