Upcoming changes to the FindMeetingTimes (Preview) API

  • Article

I wanted to give you all a heads up on some changes that are coming to the FindMeetingTimes (Preview) API which is available in preview. 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.

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.

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:

Metadata definition

 <ComplexType Name="MeetingTimeCandidatesResult">
  <Property Name="MeetingTimeSlots" Type="Collection(Microsoft.OutlookServices.MeetingTimeCandidate)" />
  <Property Name="EmptySuggestionsHint" Type="Edm.String" />
</ComplexType>

This 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":"https://outlook.office.com /api/beta/$metadata#Microsoft.OutlookServices.MeetingTimeCandidatesResult",    
  "MeetingTimeSlots": [ ],    
  "EmptySuggestionsHint": "AttendeesUnavailableOrUnknown" 
}

And if there are suggestions returned, the EmptySuggestionsHint property would be empty:

 {
  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Microsoft.OutlookServices.MeetingTimeCandidatesResult",
  "MeetingTimeSlots": [
    {
      "MeetingTimeSlot": {
        "Start": {
          "Date": "2016-04-20",
          "Time": "11:00:00.0000000",
          "TimeZone": "Eastern Standard Time"
        },
        "End": {
          "Date": "2016-04-20",
          "Time": "12:00:00.0000000",
          "TimeZone": "Eastern Standard Time"
        }
      },
      "Confidence": 50.0,
      "OrganizerAvailability": "Free",
      "AttendeeAvailability": [
        {
          "Attendee": {
            "Type": "Required",
            "EmailAddress": {
              "Address": "sarad@contoso.com"
            }
          },
          "Availability": "Busy"
        },
        {
          Attendee": {
            "Type": "Required",
            "EmailAddress": {
              "Address": "garthf@contoso.com"
            }
          },
          "Availability": "Free"
        }
      ],
      "Locations": [],
      "SuggestionHint": "Suggested because it is one of the nearest times when most attendees are available."
    }
  ],
  "EmptySuggestionsHint": ""
}

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 https://developer.microsoft.com/en-us/outlook/ for the latest news and updates.