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
- We have consolidated the personType, mailboxType and sources properties into one property called personType.
- 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!
