Export (0) Print
Expand All

Office 365 Service Communications API Overview

The Office 365 Service Communications API enables administrators 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.

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.

Figure 1 API Calls

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:

Office 365 Role

Method

Description

Tenant Administrator

Register

Authenticates the tenant (domains) and generates a token to be used for subsequent calls to the other two methods (GetServiceInformation and GetEvents).

GetServiceInformation

Retrieves the list of workloads and features that are part of the Office 365 subscription.

GetEvents

Retrieves the list of events and Message Center communications that impact the domains of your Office 365 subscription.

Partner (AOBO) (administers for other domains)

Register

Authenticates the call and generates a token to be used for subsequent calls to the other methods (GetServiceInformationForTenantDomains and GetEventsForTenantDomains).

GetServiceInformationForTenantDomains

Retrieves the list of workloads and features that are part of the tenant’s Office 365 subscription.

GetEventsForTenantDomains

Retrieves the list of events and Message Center communications that impact the tenant domains.

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

Term

Definition

Service (Workload)

An Office 365 offering that is part of the subscription associated with your domain or the domains that you manage on behalf of your customers. For example: Lync Online, Exchange Online, and so forth.

Service Incident

An event that impacts the health of an Office 365 workload.

Maintenance Event

A planned maintenance activity for an Office 365 workload.

Tenant

Owner of an active Office 365 subscription.

AOBO (Administer on Behalf of)

Refers to scenarios where you administer the domain(s) of your customers’ subscriptions on their behalf.

Message Center Message

An Office 365 communication sent to the Message Center section of the administrator’s portal about new service features and/or actions needed from the administrator.

To get started, you need the following:

  • Valid Office 365 subscription with Administrator rights.

    Note 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

Authenticates the Office 365 domain administrators based on their administrator user ID and password.

Returns a RegistrationInfo object that includes a cookie valid for two days. This cookie is used in subsequent calls to the other API methods.

Parameters

The JSON used in the HTTP POST call to the method passes the user ID and password information in this format:

"username":"","password":""

Example:

"userName":"testuser@test.com","password":"password1234"

Return value

A registration token of type RegistrationInfo that contains the cookie used for subsequent API calls.

Error codes

HTTP Error Code

Description

400

Malformed request.

401

  • The user ID is invalid.

  • The password is invalid or expired.

  • The user account is expired.

  • An administrator enabled Azure AD Multi-Factor Authentication.

  • The username value is not a Syndicated Partner. This applies to the AOBO scenario.

403

The user ID passed as the parameter does not have Administrator rights.

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 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

Returns the list of events and Message Center communications that impact the domain(s) of the authenticated Office 365 tenant. It also updates the cookie that it receives as a parameter. Subsequent calls to GetEvents with the updated cookie retrieve incremental updates.

Parameters

The JSON used in the HTTP POST call to the method passes the following: the cookie from the RegistrationInfo; the preferred event type (which indicates whether you query for Service Incidents, Maintenance Events or Message Center communications that impact your domains); a locale; and the number of (past) days for the requested information. This is the format:

""lastCookie":"","preferredEventTypes":[],"locale":","pastDays":""

Notes:

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

  • For the preferredEventTypes parameter, pass "0" to represents a Service Incident, "1" to represent a Maintenance Event, and "2" to represent a Message Center communication.

Example:

"lastCookie":"cookiedata", "preferredEventTypes":[0,1,2], "locale":"en-us", "pastDays":"10"

Return value

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

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.

500

The server is unavailable when the number of requests exceeds the throttling limits (25 requests/IP client/second, or 5 requests/user account/minute.)

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 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

Returns the list of events and Message Center communications that impact the domain(s) of your customers. It also updates the cookie that it receives as a parameter.

Parameters

The JSON used in the HTTP POST call to the method passes the following: the cookie from the RegistrationInfo; the preferred event type (which indicates whether you query for Service Incidents, Maintenance Events or Message Center communications that impact your domains); the list of domains; a locale; and the number of (past) days for the requested information. This is the format:

""lastCookie":"","preferredEventTypes":[], "tenantDomains":[],"locale":","pastDays":""

Notes:

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

  • For the preferredEventTypes parameter, pass "0" to represents a Service Incident, "1" to represent a Maintenance Event, and "2" to represent a Message Center communication.

Return value

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

Error codes

HTTP Error Code

Description

400

The cookie passed as a parameter has been tampered with.

401

Unauthorized exception if any of the domains is not managed by the tenant administrator.

The server is unavailable when the number of requests exceeds the throttling limits (25 requests/IP client/second, or 5 requests/user account/minute.)

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).

Show:
© 2014 Microsoft