Microsoft Graph findMeetingTimes API update

Hi all, we want to give you a heads up on some changes that are coming to the FindMeetingTimes API which is available in preview in Microsoft Graph. We are making these changes to further improve the API based on feedback, and these changes will be widely deployed over the next few weeks. The updated API will continue to be available only in preview.

In summary, the changes are as follows:

  1. The score property will be removed.
  2. The return type for the API will now be a meetingTimeCandidatesResult complex type with the following metadata definition:
<ComplexType Name="meetingTimeCandidatesResult">
<Property Name="meetingTimeSlots" Type="Collection(microsoft.graph.meetingTimeCandidate)" /> 
<Property Name="emptySuggestionsHint" Type="Edm.String" />


The meetingTimeCandidatesResult complex type has two properties. The first property, meetingTimeSlots, is a collection of meetingTimeCandidates, which is a list of best possible meeting times as calculated by the API. This is the same list that was returned in the earlier version of the API. The second is a string property called emptySuggestionsHint. This property provides the reason why the meetingTimeCandidates collection is null. Using this, an app or user can understand more about why the suggestions collection was null, and call the API again with a different set of parameters.

And here is a sample to show you what the new API response would look like, when there are no suggestions returned:

{  "@odata.context":"$metadata#microsoft.graph.meetingTimeCandidatesResult",      
"meetingTimeSlots": [ ],      
"emptySuggestionsHint": "attendeesUnavailableOrUnknown" }

And if there are suggestions returned, the emptySuggestionsHint property would be empty.

Please note that this is a breaking change, and if your app uses the FindMeetingTimes (Preview) API, the app needs to be updated to accommodate these changes. Once the changes have been fully deployed worldwide (4-6 weeks), your app can start using the new schema via the “FindMeetingTimes” API. In the meantime, users might experience intermittent issues when accessing the API through your app. We have also made the old schema available to you through the ‘FindMeetingTimesOld’ API. The ‘FindMeetingTimesOld’ API will be available through the deployment period and will be retired after the schema changes are fully deployed.

More extensive documentation on the new functionality is coming soon in our API reference documentation page. Please let us know if you have any questions, and visit for more information on APIs available.


Shreedevi Padmasini on behalf of the Microsoft Graph and Outlook teams