GetUserAvailability operation
Find information about the GetUserAvailability EWS operation.
The GetUserAvailability operation provides detailed information about the availability of a set of users, rooms, and resources within a specified time period.
Using the GetUserAvailability operation
The GetUserAvailability operation provides current user availability information at a specified level of detail. Client applications such as Outlook, Outlook Web Access, Outlook Mobile Access, and others use SMTP addresses to identify the requested user information.
The Availability service expands distribution lists to retrieve the free/busy status for each member of the list, as long as the number of mailboxes in the distribution list is less than 100, which is the maximum number of identities that the GetUserAvailability operation can request. The free/busy statuses of the members of the distribution list are merged into a single free/busy status for the whole distribution list.
Client application requests specify the time period of the availability query. The default time period for the requested information is 42 days. If the user's calendar contains appointments or meetings that are both within and outside the defined time period for the query, the appointment is returned.
The appointment and meeting times that are returned are in the same time zone as the client application that is requesting the meeting.
The Availability service processes the request for each client. The service expands all the recurring appointments and returns the maximum number of calendar details that the requesting client has permission to receive.
Note
If the target mailbox is unavailable or cannot be found, a MailRecipientNotFoundException exception is thrown. The client receives an error message that states that the mail recipient is not found in the Active Directory directory service or Active Directory Domain Services (AD DS).
GetUserAvailability operation SOAP headers
The GetUserAvailability operation can use the SOAP headers that are listed in the following table.
| Header | Element | Description |
|---|---|---|
| Impersonation |
ExchangeImpersonation |
Identifies the user whom the client is impersonating. This header is applicable to a request. |
| RequestVersion |
RequestServerVersion |
Identifies the schema version for the operation request. This header is applicable to a request. |
| ServerVersion |
ServerVersionInfo |
Identifies the version of the server that responded to the request. This header is applicable to a response. |
| TimeZoneContext |
TimeZoneContext |
Specifies a SOAP header that identifies the time zone to be used for all responses from the server. All times that are returned from the server will be converted to the specified time zone. This header is applicable to a response. |
GetUserAvailability request example: Get availability information
The following example of a GetUserAvailability operation request shows how to get detailed availability information for two users in the Pacific Time time zone.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<soap:Body>
<GetUserAvailabilityRequest xmlns="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<t:TimeZone xmlns="http://schemas.microsoft.com/exchange/services/2006/types">
<Bias>480</Bias>
<StandardTime>
<Bias>0</Bias>
<Time>02:00:00</Time>
<DayOrder>5</DayOrder>
<Month>10</Month>
<DayOfWeek>Sunday</DayOfWeek>
</StandardTime>
<DaylightTime>
<Bias>-60</Bias>
<Time>02:00:00</Time>
<DayOrder>1</DayOrder>
<Month>4</Month>
<DayOfWeek>Sunday</DayOfWeek>
</DaylightTime>
</t:TimeZone>
<MailboxDataArray>
<t:MailboxData>
<t:Email>
<t:Address>user1@example.com</t:Address>
</t:Email>
<t:AttendeeType>Required</t:AttendeeType>
<t:ExcludeConflicts>false</t:ExcludeConflicts>
</t:MailboxData>
<t:MailboxData>
<t:Email>
<t:Address>user2@example.com</t:Address>
</t:Email>
<t:AttendeeType>Required</t:AttendeeType>
<t:ExcludeConflicts>false</t:ExcludeConflicts>
</t:MailboxData>
</MailboxDataArray>
<t:FreeBusyViewOptions>
<t:TimeWindow>
<t:StartTime>2006-10-16T00:00:00</t:StartTime>
<t:EndTime>2006-10-16T23:59:59</t:EndTime>
</t:TimeWindow>
<t:MergedFreeBusyIntervalInMinutes>60</t:MergedFreeBusyIntervalInMinutes>
<t:RequestedView>DetailedMerged</t:RequestedView>
</t:FreeBusyViewOptions>
</GetUserAvailabilityRequest>
</soap:Body>
</soap:Envelope>
For more information about retrieving suggested meetings by using the SuggestionsViewOptions element, see the schema in the EWS virtual directory.
The request SOAP body contains the following elements:
Successful GetUserAvailability operation response
The following example shows a successful response to the GetUserAvailability operation request.
Note
The calendar event identifiers have been shortened to preserve readability.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<t:ServerVersionInfo MajorVersion="8" MinorVersion="0" MajorBuildNumber="665" MinorBuildNumber="7"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" />
</soap:Header>
<soap:Body>
<GetUserAvailabilityResponse xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
<FreeBusyResponseArray>
<FreeBusyResponse>
<ResponseMessage ResponseClass="Success">
<ResponseCode>NoError</ResponseCode>
</ResponseMessage>
<FreeBusyView>
<FreeBusyViewType xmlns="http://schemas.microsoft.com/exchange/services/2006/types">DetailedMerged</FreeBusyViewType>
<MergedFreeBusy xmlns="http://schemas.microsoft.com/exchange/services/2006/types">000002220220000000000000</MergedFreeBusy>
<CalendarEventArray xmlns="http://schemas.microsoft.com/exchange/services/2006/types">
<CalendarEvent>
<StartTime>2006-10-16T06:00:00-07:00</StartTime>
<EndTime>2006-10-16T06:30:00-07:00</EndTime>
<BusyType>Busy</BusyType>
<CalendarEventDetails>
<ID>14B6414B0</ID>
<Subject>Meet with Contoso Account Executives</Subject>
<Location />
<IsMeeting>false</IsMeeting>
<IsRecurring>false</IsRecurring>
<IsException>false</IsException>
<IsReminderSet>false</IsReminderSet>
<IsPrivate>false</IsPrivate>
</CalendarEventDetails>
</CalendarEvent>
<CalendarEvent>
<StartTime>2006-10-16T07:00:00-07:00</StartTime>
<EndTime>2006-10-16T08:00:00-07:00</EndTime>
<BusyType>Busy</BusyType>
<CalendarEventDetails>
<ID>E14B6414B0B</ID>
<Subject>Pick up my groceries</Subject>
<Location />
<IsMeeting>false</IsMeeting>
<IsRecurring>false</IsRecurring>
<IsException>false</IsException>
<IsReminderSet>false</IsReminderSet>
<IsPrivate>false</IsPrivate>
</CalendarEventDetails>
</CalendarEvent>
<CalendarEvent>
<StartTime>2006-10-16T09:40:00-07:00</StartTime>
<EndTime>2006-10-16T10:10:00-07:00</EndTime>
<BusyType>Busy</BusyType>
<CalendarEventDetails>
<ID>14B6414B0B1</ID>
<Subject>Meet with doctor</Subject>
<Location>Kirkland</Location>
<IsMeeting>false</IsMeeting>
<IsRecurring>false</IsRecurring>
<IsException>false</IsException>
<IsReminderSet>false</IsReminderSet>
<IsPrivate>false</IsPrivate>
</CalendarEventDetails>
</CalendarEvent>
</CalendarEventArray>
<WorkingHours xmlns="http://schemas.microsoft.com/exchange/services/2006/types">
<TimeZone>
<Bias>480</Bias>
<StandardTime>
<Bias>0</Bias>
<Time>02:00:00</Time>
<DayOrder>5</DayOrder>
<Month>10</Month>
<DayOfWeek>Sunday</DayOfWeek>
</StandardTime>
<DaylightTime>
<Bias>-60</Bias>
<Time>02:00:00</Time>
<DayOrder>1</DayOrder>
<Month>4</Month>
<DayOfWeek>Sunday</DayOfWeek>
</DaylightTime>
</TimeZone>
<WorkingPeriodArray>
<WorkingPeriod>
<DayOfWeek>Monday Tuesday Wednesday Thursday Friday</DayOfWeek>
<StartTimeInMinutes>480</StartTimeInMinutes>
<EndTimeInMinutes>1020</EndTimeInMinutes>
</WorkingPeriod>
</WorkingPeriodArray>
</WorkingHours>
</FreeBusyView>
</FreeBusyResponse>
<FreeBusyResponse>
<ResponseMessage ResponseClass="Success">
<ResponseCode>NoError</ResponseCode>
</ResponseMessage>
<FreeBusyView>
<FreeBusyViewType xmlns="http://schemas.microsoft.com/exchange/services/2006/types">FreeBusyMerged</FreeBusyViewType>
<MergedFreeBusy xmlns="http://schemas.microsoft.com/exchange/services/2006/types">000000001100000000000000</MergedFreeBusy>
<CalendarEventArray xmlns="http://schemas.microsoft.com/exchange/services/2006/types">
<CalendarEvent>
<StartTime>2006-10-16T09:00:00-07:00</StartTime>
<EndTime>2006-10-16T10:00:00-07:00</EndTime>
<BusyType>Tentative</BusyType>
</CalendarEvent>
</CalendarEventArray>
<WorkingHours xmlns="http://schemas.microsoft.com/exchange/services/2006/types">
<TimeZone>
<Bias>480</Bias>
<StandardTime>
<Bias>0</Bias>
<Time>02:00:00</Time>
<DayOrder>5</DayOrder>
<Month>10</Month>
<DayOfWeek>Sunday</DayOfWeek>
</StandardTime>
<DaylightTime>
<Bias>-60</Bias>
<Time>02:00:00</Time>
<DayOrder>1</DayOrder>
<Month>4</Month>
<DayOfWeek>Sunday</DayOfWeek>
</DaylightTime>
</TimeZone>
<WorkingPeriodArray>
<WorkingPeriod>
<DayOfWeek>Monday Tuesday Wednesday Thursday Friday</DayOfWeek>
<StartTimeInMinutes>480</StartTimeInMinutes>
<EndTimeInMinutes>1020</EndTimeInMinutes>
</WorkingPeriod>
</WorkingPeriodArray>
</WorkingHours>
</FreeBusyView>
</FreeBusyResponse>
</FreeBusyResponseArray>
</GetUserAvailabilityResponse>
</soap:Body>
</soap:Envelope>
The availability information for each user appears in a unique FreeBusyResponse element. The order of users in the GetUserAvailability operation request determines the order of availability data for each user in the response.
An error will be returned to the client if the number of appointments in the time period that is defined in the query is greater than the administrator-specified maximum number. The default maximum number of appointments is 10,000 single instances and expanded recurrence items. This property can be configured only by an administrator.
The following elements are used in the response: