Office365Mon Subscription Management API

Transcription

1 Office365Mon Subscription Management API Office365Mon provides a set of APIs for managing subscriptions in our service. With it you can do things like create a subscription, change the details about the subscription, modify the list of administrators and notifications for a subscription, and configure the resources being monitored for the subscription. You can also use it to periodically update the access token that Office365Mon uses when issuing probes against your monitored resources. The access token expires every 90 days so it s important to keep it up to date. Using the subscription management API requires you to first create an application in your Azure Active Directory and add the Office365Mon applications to it. You ll then reference your application information when requesting an access token that you can use to work with the subscription management API. This process is explained and illustrated in great detail in our API documentation for accessing report data, which you can download from It s highly recommended to download that document first to ensure your environment is set up correctly before using this subscription management API. For resellers there are some special APIs just for you. You need to be registered with Office365Mon.Com to use the reseller APIs, which you can do by contacting us at

2 Once you re registered then you use the Reseller* APIs described at the end of this document to create new subscriptions and add and remove plans for those subscriptions. Once a subscription is actually created though, you can use the same Subscription Management APIs as everyone to manage it change the list of Admins, add or remove notification info, etc.

3 Contents Overview... 4 Subscriptions... 4 Create a Subscription... 5 Get a Subscription... 6 Get My Subscriptions... 8 Update Basic Subscription Details Administrators Get Subscription Administrators Add a Subscription Administrator Delete a Subscription Administrator Notifications Get Subscription Notifications Add a Subscription Notification Delete a Subscription Notification Get Outage Duration for Notifications Update Outage Duration for Notifications Resources Get Subscription Resources Add a Subscription Resource Update the Access Token for a Subscription Resource Delete a Subscription Resource Issue a Health Probe for a Resource Issue a Health Probe for any Office 365 Resource Resellers Create a Subscription Delete a Subscription Get Plans Add a Plan to a Subscription Delete a Plan from a Subscription Get Customer Plans... 41

4 Overview The subscription management API is designed to let you do all of the required steps to create and maintain Office365Mon subscriptions. The order of the document follows the same steps you go through when creating and/or managing a subscription in the web site at The basic steps you ll want to go through to create a new subscription are: 1. Create a subscription. 2. Add additional subscription administrators, if needed. If you re an Office 365 reseller you would typically add one or more accounts that you own, and at least one account in the new Office 365 tenant. 3. Add the notification options you want for the subscription e.g. the addresses and texting phone numbers that should be alerted in the event of an outage. 4. Add the resources that you want to be monitored by the subscription. When you add a resource you ll want to provide the credentials of an account that has permissions to the resource. However, that account has to located in an Azure Active Directory tenant that has already gone through the Azure consent process for the Office365Mon application, otherwise we won t be able to successfully get an access token for the resource. You can always set up the resources and then later after the account has gone through the Azure consent process, you can use the update an access token API to fetch a new access token for that resource. We ve also included additional APIs for the management of the subscription, such as changing any of the information described above, as well as manually issuing health probes to both a resource we are monitoring for you, as well as any Office 365 resource to which you have permission. Following is a list of actions you can do with the subscription management API. Subscriptions The operations in this section all have to do with managing general subscription details.

5 Create a Subscription Use this method to create a new subscription. DevSubscriptionId Guid The ID of your Office365Mon subscription that has UPN String The UPN for the initial administrator of the Office365Mon subscription. CompanyName String The company whose name the subscription is for. Contact String An address that can be used for pricing changes, feature changes, etc. for the subscription SubscriptionId Guid The subscription ID for the new Office365Mon subscription. If the call fails, the status code will be 409 Conflict. vals.add(new KeyValuePair<string, string>("upn", "[email protected]")); vals.add(new KeyValuePair<string, string>("companyname", "Contoso")); vals.add(new KeyValuePair<string, string>("contact ", "[email protected]")); //make the post to create the subscription HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "createsub");

6 string results = await hrm.content.readasstringasync(); //this is used to convert our JSON data into a dictionary of values JavaScriptSerializer jss = new JavaScriptSerializer(); //set the maximum length value because some of the data, //especially health pings, can be quite long jss.maxjsonlength = int.maxvalue; var data = jss.deserialize<dictionary<string, object>>(results); string SubscriptionId = data["subscriptionid"].tostring(); //the operation failed Get a Subscription Use this method to get subscription details. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being queried. CompanyName String The name of the company for the subscription. Contact String The address that will be used to contact the subscription owner in the case of pricing changes, feature changes, licensing changes, general announcements, etc. DateCreated DateTime The date the subscription was created. IsActive Int An integer representing the active state of the subscription.

7 Active State Code Inactive 0 Active 1 MonitorVersions Int An integer describing whether version changes for Office 365 resources should be monitored Monitoring State Code Don t monitor for and 0 notify me of changes in the version of my Office 365 resources. Do monitor for and 1 notify me of changes in the version of my Office 365 resources. If the call fails, the status code will be 409 Conflict. vals.add(new KeyValuePair<string, string>("subscriptionid", " //make the post to get the subscription HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "getsub"); string subdata = await hrm.content.readasstringasync(); //this is used to convert our JSON data into a dictionary of values JavaScriptSerializer jss = new JavaScriptSerializer(); //set the maximum length value because some of the data, //especially health pings, can be quite long jss.maxjsonlength = int.maxvalue; var data = jss.deserialize<dictionary<string, object>>(subdata); string CompanyName = data["companyname"].tostring(); string Contact = data["contact "].tostring(); DateTime DateCreated DateTime.Parse(data["DateCreated"]); string IsActive = data["isactive"].tostring(); string MonitorVersions = items ["MonitorVersions"].ToString();

8 //the operation failed Get My Subscriptions Use this method to get details of all subscriptions on which you are a subscription administrator. DevSubscriptionId Guid The ID of your Office365Mon subscription that has An array of information about each subscription: CompanyName String The name of the company for the subscription. Contact String The address that will be used to contact the subscription owner in the case of pricing changes, feature changes, licensing changes, general announcements, etc. DateCreated DateTime The date the subscription was created. IsActive Int An integer representing the active state of the subscription. Active State Code Inactive 0 Active 1 MonitorVersions Int An integer describing whether version changes for Office 365 resources should be monitored Monitoring State Don t monitor for and notify me of changes in Code 0

9 the version of my Office 365 resources. Do monitor for and notify me of changes in the version of my Office 365 resources. 1 If the call fails, the status code will be 409 Conflict. //make the post to get the subscription HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + " mysubs"); string subdata = await hrm.content.readasstringasync(); //this is used to convert our JSON data into a dictionary of values JavaScriptSerializer jss = new JavaScriptSerializer(); //set the maximum length value because some of the data, //especially health pings, can be quite long jss.maxjsonlength = int.maxvalue; Array data = jss.deserializeobject(subdata) as Array; foreach (var sub in data) Dictionary<string, object> items = sub as Dictionary<string, object>; string CompanyName = items["companyname"].tostring(); string Contact = items ["Contact "].ToString(); DateTime DateCreated DateTime.Parse(items ["DateCreated"]); string IsActive = items ["IsActive"].ToString(); string MonitorVersions = items ["MonitorVersions"].ToString(); //the operation failed

10 Update Basic Subscription Details Use this method to update the company name and/or contact for a subscription. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being modified. CompanyName String The company whose name the subscription is for. Contact String An address that can be used for pricing changes, feature changes, etc. for the subscription MonitorVersions Int A value of 0 means don t monitor for and notify me of changes in the version of my Office 365 resources; a value of 1 means notify me. Nothing. If the call works, the Http Status Code in the response will be 200. If it fails, the status code will be 409 Conflict. vals.add(new KeyValuePair<string, string>("subscriptionid", " vals.add(new KeyValuePair<string, string>("companyname", "Contoso")); vals.add(new KeyValuePair<string, string>("contact ", "[email protected]")); vals.add(new KeyValuePair<string, string>("monitorversions", "1")); //make the post to update the subscription HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "updatesub");

11 //the operation worked //the operation failed Administrators The operations in this section all have to do with managing administrators for a subscription. Get Subscription Administrators This method returns a semi-colon delimited list of administrators for the subscription. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being queried. AdminUPNs ArrayList An ArrayList of administrator UPNs for the subscription. If the call fails, the status code will be 409 Conflict.

12 vals.add(new KeyValuePair<string, string>("subscriptionid", " //make the post to get the subscription admins HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "getadmins"); string admins = await hrm.content.readasstringasync(); //this is used to convert our JSON data into a dictionary of values JavaScriptSerializer jss = new JavaScriptSerializer(); //set the maximum length value because some of the data, //especially health pings, can be quite long jss.maxjsonlength = int.maxvalue; var data = jss.deserialize<dictionary<string, object>>(admins); ArrayList adminlist = data["adminupns"] as ArrayList; foreach (var admin in adminlist) //admin = a UPN of an admin //the operation failed Add a Subscription Administrator Use this method to add a subscription administrator. DevSubscriptionId Guid The ID of your Office365Mon subscription that has the REST API Access feature enabled. SubscriptionId Guid The ID of the subscription being modified.

13 AdminUPNs String A JSON-formated array of UPNs to add as administrators of the subscription, i.e. ["[email protected]"] or ["[email protected]","[email protected]"]. Nothing. If the call works, the Http Status Code in the response will be 200. If it fails, the status code will be 409 Conflict. vals.add(new KeyValuePair<string, string>("subscriptionid", " //this is just one method for supporting adding multiple items at once; you can use //whatever method works for you string[] admins = new string[2] "[email protected]", "[email protected]" ; //this is used to convert a.net string array into a JSON-formatted single string for POST'ing JavaScriptSerializer jss = new JavaScriptSerializer(); vals.add(new KeyValuePair<string, string>("adminupns", jss.serialize(admins).tostring())); //make the post to add the admins HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "addadmins"); //the operation worked //the operation failed

14 Delete a Subscription Administrator Use this method to delete a subscription administrator. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being modified. AdminUPNs String The UPN of the admin to delete from the subscription. This accepts a single value only, not an array. Nothing. If the call works, the Http Status Code in the response will be 200. If it fails, the status code will be 409 Conflict. vals.add(new KeyValuePair<string, string>("subscriptionid", " vals.add(new KeyValuePair<string, string>("adminupns", "[email protected]")); //make the post to delete the admin HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "deleteadmin"); //the operation worked

15 //the operation failed Notifications The operations in this section all have to do with managing who or what is notified when there is an outage, such as addresses and phone numbers for text messages. Get Subscription Notifications Use this method to get all of the notification points for a subscription. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being queried. An array of objects that each contain information about one notification point: address, description, notification type description, and notification type code. Address String The address the notification should go to. It can be either an address, or a mobile phone number that can receive text messages. Description String A description of the notification endpoint. TypeDescription String A description of the notification type. TypeCode Int An int that represents the type of address it is. The possible TypeCodes are: Address Type Code 0 Text 1

16 If the call fails, the status code will be 409 Conflict. vals.add(new KeyValuePair<string, string>("subscriptionid", " //make the post to get the list of notifications HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "getnotifications"); string notifications = await hrm.content.readasstringasync(); //this is used to convert our JSON data into a dictionary of values JavaScriptSerializer jss = new JavaScriptSerializer(); //set the maximum length value because some of the data, //especially health pings, can be quite long jss.maxjsonlength = int.maxvalue; var data = jss.deserialize<dictionary<string, object>>(notifications); if (data.containskey("notificationlist")) ArrayList notelist = data["notificationlist"] as ArrayList; List<NotificationInfo> notificationinfos = new List<NotificationInfo>(); foreach (var note in notelist) Dictionary<string, object> noteinfo = note as Dictionary<string, object>; string address = noteinfo["address"].tostring(); string description = noteinfo["description"].tostring(); string typedescription = noteinfo["typedescription"].tostring(); int typecode = (int)noteinfo["typecode"]; //there aren t any

17 //the operation failed Add a Subscription Notification Use this method to add a notification endpoint to the subscription. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being modified. Address String The address the notification should go to. It can be either an address, or a mobile phone number that can receive text messages. Description String A description of the notification endpoint. TypeCode Int An int that represents the type of address it is. The possible TypeCodes are: Address Type Code 0 Text 1 Nothing. If the call works, the Http Status Code in the response will be 200. If it fails, the status code will be 409 Conflict.

18 vals.add(new KeyValuePair<string, string>("subscriptionid", " vals.add(new KeyValuePair<string, string>("address", vals.add(new KeyValuePair<string, string>("description", "Home address")); vals.add(new KeyValuePair<string, string>("typecode", "0")); //make the post to add the Address notification (because TypeCode = 0) HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "addnotification"); //the operation worked //the operation failed Delete a Subscription Notification Use this method to delete a notification endpoint for the subscription. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being modified. Address String The address the notification should go to. It can be either an address, or a mobile phone number that can receive text messages. Nothing. If the call works, the Http Status Code in the response will be 200. If it fails, the status code will be 409 Conflict.

19 vals.add(new KeyValuePair<string, string>("subscriptionid", " vals.add(new KeyValuePair<string, string>("address", //make the post to delete the notification HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "deletenotification"); //the operation worked //the operation failed Get Outage Duration for Notifications Use this method to get the duration, in minutes, that an outage must have before sending notifications. A value of 0 means that notifications are sent on every outage. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being queried. An integer value in minutes of the minimum outage duration before notifications are sent. If the call fails, the status code will be 409 Conflict.

20 vals.add(new KeyValuePair<string, string>("subscriptionid", " //make the post to get the list of notifications HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + " getoutageduration"); //this is used to convert our JSON data into a dictionary of values string notifications = await hrm.content.readasstringasync(); //you can convert this value into an integer //the operation failed Update Outage Duration for Notifications Use this method to update the duration, in minutes, that an outage must have before sending notifications. A value of 0 means that notifications are sent on every outage. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being updated. OutageDuration Int An int that represents how long an outage duration needs to run before notifications are sent out. If

21 the value is zero then notifications are sent on every outage, even if it s less than a minute. Nothing. If the call works, the Http Status Code in the response will be 200. If it fails, the status code will be 409 Conflict. vals.add(new KeyValuePair<string, string>("subscriptionid", " vals.add(new KeyValuePair<string, string>(" OutageDuration","2")); //make the post to get the list of notifications HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + " updateoutageduration"); //it worked! //the operation failed Resources The operations in this section all have to do with managing the resources that are going to be monitored for the subscription. Get Subscription Resources Use this method to get all of the resources being monitored for a subscription.

22 DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being queried. An array of objects that each contain information about one resource: address and resource type code. Address String The address of the resource. It can be either a SharePoint Online url, or an Exchange Online address. TypeCode Int An int that represents the type of resource it is. The possible TypeCodes are: If the call fails, the status code will be 409 Conflict. Address Type Code SharePoint Online 0 Exchange Online 1 vals.add(new KeyValuePair<string, string>("subscriptionid", " //make the post to get the resources HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "getnotifications");

23 string resources = await hrm.content.readasstringasync(); //this is used to convert our JSON data into a dictionary of values JavaScriptSerializer jss = new JavaScriptSerializer(); //set the maximum length value because some of the data, //especially health pings, can be quite long jss.maxjsonlength = int.maxvalue; var data = jss.deserialize<dictionary<string, object>>(resources); if (data.containskey("resourcelist")) ArrayList resourcelist = data["resourcelist"] as ArrayList; List<ResourceInfo> resourceinfos = new List<ResourceInfo>(); foreach (var resource in resourcelist) Dictionary<string, object> resourceinfo = resource as Dictionary<string, object>; string address = resourceinfo["address"].tostring(); int typecode = (int)resourceinfo["typecode"]; MessageBox.Show("No resources were found"); //the operation failed Add a Subscription Resource Use this method to add a resource to a subscription. NOTE: This method includes a username and password parameter. These parameters are NEVER stored; they are just used one time to get an access token. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being modified.

24 Address String The address of the resource to be monitored. It should be either a SharePoint Online url or an Exchange Online address. TypeCode Int An int that represents the type of address it is. The possible TypeCodes are: Address Type Code SharePoint Online 0 Exchange Online 1 Username String The username of an Azure Active Directory account that has rights to access the resource. NOTE: This information is NEVER stored; it is just used one time to get an access token. Password String The password for the Azure Active Directory account username. NOTE: This information is NEVER stored; it is just used one time to get an access token. TenantId Guid The tenant ID of the Azure Active Directory tenant to which the Username belongs. Nothing. If the call works, the Http Status Code in the response will be 200. If it fails, the status code will be 409 Conflict. vals.add(new KeyValuePair<string, string>("subscriptionid", " vals.add(new KeyValuePair<string, string>("address", " vals.add(new KeyValuePair<string, string>("typecode", "0")); vals.add(new KeyValuePair<string, string>("username", "[email protected]")); vals.add(new KeyValuePair<string, string>("password", "abcd1234")); vals.add(new KeyValuePair<string, string>("tenantid", " //make the post to add the SharePoint Online resource (because TypeCode = 0) HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "addresource");

25 //the operation worked //the operation failed Update the Access Token for a Subscription Resource Use this method to update the access token for a subscription resource. Access tokens are issued by Azure Active Directory and expire approximately every 90 days. If you do not refresh the access tokens in your subscription, Office365Mon will no longer be able to monitor those resources for you when the token expires. NOTE: This method includes a username and password parameter. These parameters are NEVER stored; they are just used one time to get an access token. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being modified. Address String The address of the resource whose access token is being updated. It should be either a SharePoint Online url or an Exchange Online address. TypeCode Int An int that represents the type of address it is. The possible TypeCodes are: Address Type Code SharePoint Online 0 Exchange Online 1 Username String The username of an Azure Active Directory account that has rights to access the resource. NOTE: This information is NEVER stored; it is just used one time to get an access token. Password String The password for the Azure Active Directory account username. NOTE: This information is

26 NEVER stored; it is just used one time to get an access token. TenantId Guid The tenant ID of the Azure Active Directory tenant to which the Username belongs. Nothing. If the call works, the Http Status Code in the response will be 200. If it fails, the status code will be 409 Conflict. vals.add(new KeyValuePair<string, string>("subscriptionid", " vals.add(new KeyValuePair<string, string>("address", " vals.add(new KeyValuePair<string, string>("typecode", "0")); vals.add(new KeyValuePair<string, string>("username", vals.add(new KeyValuePair<string, string>("password", "abcd1234")); vals.add(new KeyValuePair<string, string>("tenantid", " //make the post to add the SharePoint Online resource (because TypeCode = 0) HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "updateaccesstoken"); //the operation worked //the operation failed

27 Delete a Subscription Resource Use this method to delete a subscription resource. This means that the resource will no longer be monitored by Office365Mon, it does nothing to the resource itself, i.e. it will not delete a SharePoint Online site or Exchange Online mailbox. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being modified. TypeCode Int An int that represents the type of address to delete. The possible TypeCodes are: Address Type Code SharePoint Online 0 Exchange Online 1 Nothing. If the call works, the Http Status Code in the response will be 200. If it fails, the status code will be 409 Conflict. vals.add(new KeyValuePair<string, string>("subscriptionid", " vals.add(new KeyValuePair<string, string>("typecode", "0")); //make the post to delete the SharePoint Online resource (because TypeCode = 0) HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "deleteresource");

28 //the operation worked //the operation failed Issue a Health Probe for a Resource Use this method to manually issue a health probe against a resource and check the Http status code it returns. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being modified. TypeCode Int An int that represents the type of address to issue the probe against. The possible TypeCodes are: Address Type Code SharePoint Online 0 Exchange Online 1 StatusCode Int The Http status code that was returned from the health probe. StatusReason String The Http reason code returned in response to the health probe. If the call fails, the status code will be 409 Conflict.

29 vals.add(new KeyValuePair<string, string>("subscriptionid", " vals.add(new KeyValuePair<string, string>("typecode", "0")); //make the post to test the SharePoint Online resource (since TypeCode = 0) HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "issuehealthprobe"); string results = await hrm.content.readasstringasync(); //this is used to convert our JSON data into a dictionary of values JavaScriptSerializer jss = new JavaScriptSerializer(); //set the maximum length value because some of the data, //especially health pings, can be quite long jss.maxjsonlength = int.maxvalue; var data = jss.deserialize<dictionary<string, object>>(results); int statuscode = int.parse(data["statuscode"].tostring()); string statusreason = data["statusreason"].tostring(); //the operation failed Issue a Health Probe for any Office 365 Resource Use this method to manually issue a health probe against any Office 365 resource and check the Http status code it returns. You can use this for any site collection in a SharePoint Online tenant, or any mailbox in an Exchange Online tenant. The only real requirement is that you provide a set of credentials that can be used to access the resource you are trying to test. NOTE: This method includes a username and password parameter. These parameters are NEVER stored; they are just used one time to get an access token.

30 DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being modified. Address String The address of the resource being tested. It should be either a SharePoint Online url or an Exchange Online address. TypeCode Int An int that represents the type of address it is. The possible TypeCodes are: Address Type Code SharePoint Online 0 Exchange Online 1 Username String The username of an Azure Active Directory account that has rights to access the resource. NOTE: This information is NEVER stored; it is just used one time to get an access token. Password String The password for the Azure Active Directory account username. NOTE: This information is NEVER stored; it is just used one time to get an access token. TenantId Guid The tenant ID of the Azure Active Directory tenant to which the Username belongs. StatusCode Int The Http status code that was returned from the health probe. StatusReason String The Http reason code returned in response to the health probe. If the call fails, the status code will be 409 Conflict.

31 vals.add(new KeyValuePair<string, string>("subscriptionid", " vals.add(new KeyValuePair<string, string>("address", " vals.add(new KeyValuePair<string, string>("typecode", "0")); vals.add(new KeyValuePair<string, string>("username", vals.add(new KeyValuePair<string, string>("password", "abcd1234")); vals.add(new KeyValuePair<string, string>("tenantid"," //make the post to add the SharePoint Online resource (because TypeCode = 0) HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "testresource"); string results = await hrm.content.readasstringasync(); //this is used to convert our JSON data into a dictionary of values JavaScriptSerializer jss = new JavaScriptSerializer(); //set the maximum length value because some of the data, //especially health pings, can be quite long jss.maxjsonlength = int.maxvalue; var data = jss.deserialize<dictionary<string, object>>(results); int statuscode = int.parse(data["statuscode"].tostring()); string statusreason = data["statusreason"].tostring(); //the operation failed Resellers As mentioned in the beginning of this document, if you ve registered with Office365Mon as a reseller then there are a few additional APIs for you to use. To create or delete subscriptions you should only use the Reseller APIs. They are also the only APIs that you can use to add or remove plans from that subscription, where a plan is some collection of features that the customer is charged money for. All of the Reseller* APIs do the same basic validation check before attempting to process your request: Does the Dev Subscription have the Subscription Management API feature currently?

32 Is the user that authenticated to the REST endpoint an Admin on the Dev Subscription? Is the Dev Subscription registered as a reseller? If you are using one of the Reseller* APIs to modify a subscription such as deleting it, adding or deleting plans, or getting a list of plans for the subscription did you create that subscription? If any of the validation checks fail, then the request is not processed and the HTTP status code you will get in return is 401 Unauthorized. The ErrorMessage provides more details as to which of the validation tests failed. The Reseller* APIs also include a specific set of error numbers to provide you with as much information as possible when using them. These error numbers are used across all of the Reseller* APIs so are documented here at the beginning of the section. You can look at the status code of an HTTP request to determine the error number and message. Here s some generic sample code for parsing the return code using C# and the HttpResponseMessageClass (in the code below hrm is an HttpResponseMessage that was used to make a REST call to the Subscription Management API): //this worked - take the appropriate action //when there is an error you will get info about it in the results string results = await hrm.content.readasstringasync(); //this is used to convert our JSON data into a dictionary of values JavaScriptSerializer jss = new JavaScriptSerializer(); //set the maximum length value because some of the data, //especially health pings, can be quite long jss.maxjsonlength = int.maxvalue; var data = jss.deserialize<dictionary<string, object>>(results); //get the error number and message from the API int errnum = int.parse(data["errornumber"].tostring()); string errmsg = data["errormessage"].tostring(); //the HTTP response code is here: (int)hrm.statuscode //this DIDN'T work - take the appropriate action Here are the error codes used by the Reseller* APIs:

33 Error Number Description 100 Unexpected error A general error; details are included in the ErrorMessage. 110 Not a valid subscription The Subscription Management API is not currently an active feature in the Dev Subscription or the authenticated is not an Admin in the Dev Subscription. 120 Reseller not found The Dev Subscription ID is not registered as a reseller. Please contact [email protected] to discuss how you can become a reseller. 130 Missing required parameters One or more required parameters are missing. See the Error Message for a list of the required parameters. 140 Plan already exists for this You are trying to add a plan to a subscription that already subscription has that plan. 150 Add plan general error A general error adding a plan; details are included in the ErrorMessage. 160 Plan not configured Your Dev Subscription ID is not configured to sell this plan. Please contact [email protected] for assistance. 170 Add subscription general error A general error adding a subscription; details are included in the ErrorMessage. 180 Delete plan general error A general error deleting a plan; details are included in the ErrorMessage 190 Invalid plan The plan you are trying to add does not exist. 200 Delete subscription general error A general error deleting a subscription; details are included in the ErrorMessage 210 Subscription is not a premium You tried to add a subscription as a plan to a subscription. feature A subscription is not a plan though and cannot be added 220 Dev subscription did not create the subscription being modified as one. The subscription you are trying to modify by deleting it, adding or deleting a plan to it, or getting the list of plans for it, is not one that you created with your DevSubscriptionId. Create a Subscription Use this method to create a new subscription.

34 DevSubscriptionId Guid The ID of your Office365Mon subscription that has UPN String The UPN for the initial administrator of the Office365Mon subscription. CompanyName String The company whose name the subscription is for. Contact String An address that can be used for pricing changes, feature changes, etc. for the subscription SubscriptionId Guid The subscription ID for the new Office365Mon subscription. If the call fails, the status code will be 400 Bad Request. Examine the ErrorNumber and ErrorMessage for more details. vals.add(new KeyValuePair<string, string>("upn", vals.add(new KeyValuePair<string, string>("companyname", "My Company")); vals.add(new KeyValuePair<string, string>("contact ", //make the post to create the subscription HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "resellercreatesub"); string results = await hrm.content.readasstringasync(); //this is used to convert our JSON data into a dictionary of values JavaScriptSerializer jss = new JavaScriptSerializer(); //set the maximum length value because some of the data, //especially health pings, can be quite long jss.maxjsonlength = int.maxvalue; var data = jss.deserialize<dictionary<string, object>>(results);

35 string subscriptionid = data["subscriptionid"].tostring(); //this DIDN'T work - take the appropriate action Delete a Subscription Use this method to delete a subscription; this only works for subscriptions created with the Reseller API. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription being deleted. UPN String The UPN for the administrator of the Office365Mon subscription. Type Description true string Returns true if the call succeeded. If it fails then the HTTP status code upon return will be something other than 200 OK. If the call fails, the status code will be 400 Bad Request. Examine the ErrorNumber and ErrorMessage for more details.

36 vals.add(new KeyValuePair<string, string>("subscriptionid", " vals.add(new KeyValuePair<string, string>("upn", //make the post to create the subscription HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "resellerdeletesub"); string results = await hrm.content.readasstringasync(); //technically this should always be true; if it's not then //it should raise an error which you would catch below bool worked = bool.parse(results); //this DIDN'T work - take the appropriate action Get Plans Use this method to get the list of Plans that can be added and deleted from a subscription created with the Reseller API. DevSubscriptionId Guid The ID of your Office365Mon subscription that has List<ResellerFeaturePlan> A list of ResellerFeaturePlan items that contains information about each plan that can be added or deleted from a subscription.

37 If the call fails, the status code will be 400 Bad Request. Examine the ErrorNumber and ErrorMessage for more details. The ResellerFeaturePlan class is defined like this: public class ResellerFeaturePlan public string PlanId get; set; public string PlanName get; set; public List<PlanFeatures> Features get; set; public ResellerFeaturePlan() this.features = new List<PlanFeatures>(); public ResellerFeaturePlan(string PlanId, string PlanName) this.planid = PlanId; this.planname = PlanName; this.features = new List<PlanFeatures>(); public class PlanFeatures public Guid FeatureId get; set; public string FeatureName get; set; public PlanFeatures() public PlanFeatures(Guid FeatureId, string FeatureName) this.featureid = FeatureId; this.featurename = FeatureName; //make the post to create the subscription HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + "resellergetfeatureplans");

38 string results = await hrm.content.readasstringasync(); //this is used to convert our JSON data into a dictionary of values JavaScriptSerializer jss = new JavaScriptSerializer(); //set the maximum length value because some of the data, //especially health pings, can be quite long jss.maxjsonlength = int.maxvalue; var data = jss.deserialize<list<resellerfeatureplan>>(results); //this DIDN'T work - take the appropriate action Add a Plan to a Subscription Use this method to add a plan to a subscription; this only works for subscriptions created with the Reseller API. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription having a plan added. PlanId String The ID of the plan being added to the subscription. UPN String The UPN for the administrator of the Office365Mon subscription. Type Description true string Returns true if the call succeeded. If it fails then the HTTP status code upon return will be something other than 200 OK.

39 If the call fails, the status code will be 400 Bad Request. Examine the ErrorNumber and ErrorMessage for more details. vals.add(new KeyValuePair<string, string>("subscriptionid", " vals.add(new KeyValuePair<string, string>("planid", "ENTERPRISE_FEATURES")); vals.add(new KeyValuePair<string, string>("upn", //make the post to create the subscription HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + " reselleraddfeatureplan "); string results = await hrm.content.readasstringasync(); //technically this should always be true; if it's not then //it should raise an error which you would catch below bool worked = bool.parse(results); //this DIDN'T work - take the appropriate action Delete a Plan from a Subscription Use this method to delete a plan from a subscription; this only works for subscriptions created with the Reseller API.

40 DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription having a plan deleted. PlanId String The ID of the plan being deleted from the subscription. UPN String The UPN for the administrator of the Office365Mon subscription. Type Description true string Returns true if the call succeeded. If it fails then the HTTP status code upon return will be something other than 200 OK. If the call fails, the status code will be 400 Bad Request. Examine the ErrorNumber and ErrorMessage for more details. vals.add(new KeyValuePair<string, string>("subscriptionid", " vals.add(new KeyValuePair<string, string>("planid", "ENTERPRISE_FEATURES")); vals.add(new KeyValuePair<string, string>("upn", "[email protected]")); //make the post to create the subscription HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + " resellerdeletefeatureplan "); string results = await hrm.content.readasstringasync(); //technically this should always be true; if it's not then //it should raise an error which you would catch below bool worked = bool.parse(results); //this DIDN'T work - take the appropriate action

41 Get Customer Plans Use this method to get the list of Plans that a customer with a subscription created by the Reseller API has. DevSubscriptionId Guid The ID of your Office365Mon subscription that has SubscriptionId Guid The ID of the subscription for which you are getting the list of plans. List<CustomerPlan> A list of CustomerPlan items that contains information about each plan associated with the subscription. If the call fails, the status code will be 400 Bad Request. Examine the ErrorNumber and ErrorMessage for more details. The CustomerPlan class is defined like this: public class CustomerPlan public Guid SubscriptionId get; set; public string PlanId get; set; public string DisplayName get; set; public DateTime DateCreated get; set; public int Price get; set; public string CompanyName get; set; public string Contact get; set; Note that the Price property is for internal user and does not necessarily reflect the price that a reseller is charged for the plan.

42 vals.add(new KeyValuePair<string, string>("subscriptionid", " //make the post to create the subscription HttpResponseMessage hrm = await MakePostRequest(vals, BASE_REST_URL + " resellergetcustomerfeatureplans "); string results = await hrm.content.readasstringasync(); //this is used to convert our JSON data into a dictionary of values JavaScriptSerializer jss = new JavaScriptSerializer(); //set the maximum length value because some of the data, //especially health pings, can be quite long jss.maxjsonlength = int.maxvalue; var data = jss.deserialize<list<customerplan>>(results); //this DIDN'T work - take the appropriate action