Share via

Upcoming breaking changes - FindMeetingTimes API on Outlook BETA endpoint

  • Article

We want to give you a heads up on some changes that are coming to the FindMeetingTimes API which has been available in preview in the Outlook set of APIs. 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 in /beta and subsequently in the /v2.0 endpoint as we make the feature generally available.

In summary, the changes are as follows:

  1. Names of the following complex types, properties and parameters are updated:
    Old Name New Name
    MeetingTimeCandidatesResult MeetingTimeSuggestionsResult
    MeetingTimeCandidate MeetingTimeSuggestion
    MeetingTimeSlots MeetingTimeSuggestions
    EmptySuggestionsHint EmptySuggestionsReason
    SuggestionHint SuggestionReason
    ReturnSuggestionHints ReturnSuggestionReasons
  2. The Timeslot parameter has been changed from type Microsoft.OutlookServices.TimeStamp to type Microsoft.OutlookServices.DateTimeTimeZone.
  3. A new  parameter MinimumAttendeePercentage is being added. This is an optional parameter that indicates the minimum percentage of available attendees required for the API to return suggestions. Input values for this parameter should be of type Double and can range from 0 to 100.

The complete schema looks like below:

 <Action Name="FindMeetingTimes" IsBound="true">
  <Parameter Name="bindingParameter" Type="Microsoft.OutlookServices.User"/>
  <Parameter Name="Attendees" Type="Collection(Microsoft.OutlookServices.AttendeeBase)"/>
  <Parameter Name="LocationConstraint" Type="Microsoft.OutlookServices.LocationConstraint"/>
  <Parameter Name="TimeConstraint" Type="Microsoft.OutlookServices.TimeConstraint"/>
  <Parameter Name="MeetingDuration" Type="Edm.Duration"/>
  <Parameter Name="MaxCandidates" Type="Edm.Int32"/>
  <Parameter Name="IsOrganizerOptional" Type="Edm.Boolean"/>
  <Parameter Name="ReturnSuggestionReasons" Type="Edm.Boolean"/>
  <Parameter Name="MinimumAttendeePercentage" Type="Edm.Double"/>
  <ReturnType Type="Microsoft.OutlookServices.MeetingTimeSuggestionsResult" Nullable="false"/>
</Action>

<ComplexType Name="MeetingTimeSuggestionsResult">
  <Property Name="MeetingTimeSuggestions" Type="Collection(Microsoft.OutlookServices.MeetingTimeSuggestion)"/>
  <Property Name="EmptySuggestionsReason" Type="Edm.String" Unicode="false"/>
</ComplexType>

<ComplexType Name="MeetingTimeSuggestion">
  <Property Name="MeetingTimeSlot" Type="Microsoft.OutlookServices.TimeSlot"/>
  <Property Name="Confidence" Type="Edm.Double"/>
  <Property Name="OrganizerAvailability" Type="Microsoft.OutlookServices.FreeBusyStatus"/>
  <Property Name="AttendeeAvailability" Type="Collection(microsoft.OutlookServices.AttendeeAvailability)"/>
  <Property Name="Locations" Type="Collection(Microsoft.OutlookServices.Location)"/>
  <Property Name="SuggestionReason" Type="Edm.String" Unicode="false"/>
</ComplexType>

<ComplexType Name="TimeSlot">
  <Property Name="Start" Type="Microsoft.OutlookServices.DateTimeTimeZone"/>
  <Property Name="End" Type="Microsoft.OutlookServices.DateTimeTimeZone"/>
</ComplexType>

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. 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 more information on the available APIs.

Thank you and happy coding.

-Shreedevi on behalf of the Outlook Team