Attention: breaking changes coming to the Microsoft Graph userPurpose API (beta) 

Microsoft Graph team

We’re announcing some upcoming breaking changes to the Microsoft Graph userPurpose API (beta). This API enables developers to differentiate the purpose of a mailbox in Exchange Online. For example, a mailbox may belong to a single user, multiple users, a conference room or even a piece of equipment.  

We are planning to take the userPurpose API offline for some pre-production updates. During this time, calls to the API will fail. We are aware of several apps taking a dependency on this beta API. To mitigate the impact of this downtime, we are making another *temporary* API called userPurposeV2 available to minimize disruption to these apps. We anticipate that our updates will take up to twelve weeks and we will provide the community with an update when we’ve established a firm work completion date. After we have deployed our planned updates, developers must switch back to the userPurpose API. We will then deprecate the *temporary* userPurposeV2 API in 60 days’ time.

These changes will be rolling out to the Microsoft Graph beta endpoint on August 24, 2021. 

We would like to again remind our developers that we do not encourage usage of beta APIs in production applications as they are subject to such breaking changes. 

What is the change? 

The beta userPurpose API is scheduled to undergo fixes which must happen offline. During the maintenance interval all calls to the API will fail with the following error.  

Bad Request - 400 


    "error": { 

        "code": "BadRequest", 

        "message": "Resource not found for the segment 'userPurpose'.", 

        "innerError": { 

            "date": "…", 

            "request-id": "…", 

            "client-request-id": "…" 




Apart from internal fixes, the permission model needed to access the API will undergo some changes going forward. 

What do I need to do? 

If you are dependent on the functionality provided by this API, please update your code to call the *temporary* userPurposeV2 API instead (GET The temporary API will provide the same response as the current userPurpose API.  

You can use the following code-snippet to catch the exception: 



        Uri Uri = new Uri("<Id>/mailboxSettings/UserPurpose"); 

        httpResult = httpClient.GetStringAsync(Uri).Result; 


catch (AggregateException e) 


    System.Net.Http.HttpRequestException innerException = e.InnerException as System.Net.Http.HttpRequestException; 

    if (innerException?.StatusCode == System.Net.HttpStatusCode.BadRequest) 


            Uri Uri = new Uri("<Id>/mailboxSettings/UserPurposeV2"); 

            httpResult = httpClient.GetStringAsync(Uri).Result; 



Once the original userPurpose API is fixed and back up, you will need to switch back to the original API. 

Testing new features for your apps using beta APIs like this one on the Microsoft Graph API? Help us shape its future.  The Microsoft Graph CPx team runs a Fellowship of the Graph TAP (Technology Adoption Program). This group is a combination of Microsoft Valuable Professionals (MVPs), Regional Directors (RDs), and Independent Software Vendors (ISVs) actively working with Microsoft Graph. If you want to be part of the TAP and receive notifications around changes like this, please complete the TAP submission form for consideration.



Feedback usabilla icon