Office 365 Service Communications API Overview

The Office 365 Service Communications API enables tenants and partners that have administrator roles to retrieve real-time service health information as well as Message Center communications for the domain(s) they own or manage on behalf of their customers. This actionable information provides the following benefits that enable these tenants and partners to proactively manage the Office 365 service experience:

• Real-time service health monitoring - Query for status updates for new or ongoing service incidents or planned maintenance events that impact your subscription services (or those of your customers).

• Message Center communications - Find Office 365 communications—related to your domains or those of your customers—that were sent to your Message Center.

• Early knowledge of planned maintenance - Know about planned maintenance so as to avoid unnecessary stress on your operations or those of your customers, thus allowing for development of appropriate communications and operational strategies.

• Domain-specific information - Information is scoped to the domain(s) that tenant administrators have access to. This decreases the signal-to-noise ratio and enables tenant administrators to take timely action on issues that impact their customers.

You can interact with this API as either:

• An Office 365 administrator - Administer your own domain(s).

• A partner who has Office 365 delegated administrator rights - Administer the domain(s) of one or more tenants on their behalf.

Clients interact with the Office 365 Service Communications API by using HTTPS calls. Requests and responses are in JSON format.

By default, requests are throttled as follows for GetEvents and GetEventsForTenantDomains:

• 25 calls per second per client IP at maximum

• 5 calls per minute per user account at maximum

The data is refreshed every 30 seconds.

You can query this API to obtain information on the Office 365 services for a subscription (yours or that of your customers), or on the service health of one or more domain(s) (yours or those of your customers), or both.

Figure 1 provides an overview of the API calls.

You can use this API to obtain:

• The list of Office 365 workloads for a subscription. Follow these steps:

  1. Authenticate and obtain the token to use for subsequent API calls (Register). The token expires after 2 days.

  2. Query for Office 365 services for your domain (GetServiceInformation) or those that you manage on behalf of your customers (GetServiceInformationForTenantDomains).

• Service health information: the list of events and Message Center communications that impact the health of a subscription’s workloads. Follow these steps:

  1. Authenticate and obtain the token to use for subsequent API calls (Register). The token expires after 2 days.

  2. Query for service health information and Message Center communications for your domains (GetEvents) or those that you manage on behalf of your customers (GetEventsForTenantDomains).

• The list of workloads and service health events as well as Message Center communications for an Office 365 subscription that you administer. Follow these steps:

  • Authenticate and obtain the token to use for subsequent API calls (Register). The token expires after 2 days.

  • Query for Office 365 services for your domain (GetServiceInformation) or those that you manage on behalf of your customers (GetServiceInformationForTenantDomains).

  • Query for service health information and Message Center communications for your domains (GetEvents) or those that you manage on behalf of your customers (GetEventsForTenantDomains).

Depending on your Office 365 role—Administrator or AOBO (Administer on Behalf of), here are the methods that you need for your implementation:

Here is a list of terms that may be useful when reading this document.

To get started, you need the following:

• Valid Office 365 subscription with Administrator rights.

  Note
  If you administer the domains on behalf of your customers (AOBO scenario), you need Administrator rights for the domains that you request by means of API calls.

• Visual Studio 2012

• The Office 365 Service Communications API code samples.

All URLs referenced in this document have the following base:

Service URL: https://api.admin.microsoftonline.com/shdtenantcommunications.svc

As indicated in the preceding overview, there are five API methods in the Microsoft.Exchange.ServiceStatus.TenantCommunication.Data namespace that allow you to query for Office 365 service information and/or service health information.

Register

GetServiceInformation

Returns the list of Office 365 workloads that the user is subscribed to.

Parameters

The JSON used in the HTTP POST call to the method passes the cookie from the RegistrationInfo and a locale, in this format:

"lastCookie":"","locale":""

Note
If the value you pass for locale does not match existing options, it defaults to US English. Example "lastCookie":"cookiedata","locale":"en-us"

Return value

The list of Office 365 workloads for the authenticated domain(s), of type ServiceInformation

Error codes

HTTP Error Code	Description
400	The cookie passed as a parameter has been tampered with.
401	The cookie passed as a parameter is expired.

GetEvents

GetServiceInformationForTenantDomains

Returns the list of Office 365 workloads for the domains that you manage on behalf of your customer.

Parameters

The JSON used in the HTTP POST call to the method passes the cookie from the RegistrationInfo, the list of domains of your customer(s), and a locale, in this format:

""lastCookie":"","companydomains":[],"locale":""

Note
If the value you pass for locale does not match existing options, it defaults to US English.

Example:

"lastCookie":"cookiedata", "companydomains":["domain1.com", "domain2.com"], "locale":"en-us"

Return value

The list of Office 365 workloads for the authenticated domain(s), of type:

Dictionary<String, ServiceInformation []>

Error codes

HTTP Error Code	Description
400	The cookie passed as a parameter has been tampered with.
401	The cookie passed as a parameter is expired.

GetEventsForTenantDomains

The methods of the Office 365 Service Communications API return objects in JSON format. Alternatively, you can use the DLL available for download to return structured classes instead of JSON. These classes, also in the Microsoft.Exchange.ServiceStatus.TenantCommunication.Data namespace, are documented in a separate reference (Microsoft.Exchange.ServiceStatus.TenantCommunications.Data).

• Microsoft.Exchange.ServiceStatus.TenantCommunications.Data reference.