Educational Networks Mobile API

0. Notes

ALL requests are GET requests. All parameters go in the request string.
All responses, except for some error responses, are of "application/json; charset=UTF-8" content type.
'Response Parameters' describes what each parameter is. 'Response Structure' shows how they are laid out in JSON
Unless specified, value of each parameter is trimmed, quotes escaped, \r, \r\n, <br>, </p> replaced by \n and other tags stripped.
All listed request parameters are required and response parameters will be present, unless specified otherwise.
Responses to API calls only describe successful ones (200 OK). For error responses, refer to 1. Error Handling
With the exception of the initial setup requests which are made to www.educationalnetworks.net, all requests are to the WWWSiteURL of the school provided in the school verification response.

1.1. Security

API security is imposed by two headers in every request made to our servers. Failure to meet the security requirements outlines here will lead to the standard error response with a '403 Forbidden' response code, '999' error code and a descriptive error message.

user-agent
This header must be set to 'EducationalNetworksMobile vX_Y/Z' with X being the platform, Y being the version of the app and /Z being the brandedWebsiteID when available. The platform should start with the either 'Android' or 'iOS' followed by the exact version number. For example, the current Beta version of the Android app running on a device with Android 4.0.1 installed should set this to 'EducationalNetworksMobile vAndroid4.0.1_Beta'.
Our loggers will log this information so we can use it to identify what devices our app is being used on and for statistics/abuse purposes. Our traffic monitors can use this header to possibly rate limit the requests originating from a single device/IP, if the need arises.
Authorization (Request checksum verification)
Although the user agent limits obvious abusive traffic coming from browsers/crawlers/bots, it is easily faked and hence there is a need for a digest unique to each request.
Authorization Digest

Algorithm:
MD5(LOWERCASE(REQUEST_METHOD:WWWSiteURL:END_POINT_WITHOUT_ANY_PARAMETERS))

Example:
For a request to get the list of pages in a department of Brooklyn Technical High School, you'd make a request to this URL: https://www.bths.edu/m/api/pages/list.jsp?uREC_ID=18384&type;=d

The way to calculate the digest would be:
```
MD5(LOWERCASE(GET:www.bths.edu:/m/api/pages/list.jsp))

MD5(get:www.bths.edu:/m/api/pages/list.jsp)

D1CFF56C57F4ACD1690E499EE9FDBF3D
```
X-Auth (Logged In Services)
Every API end point that provides a X-Auth header in the request will have the server reciprocate it with a X-Auth header in the response. This can be used to verify the validity of a user session token on each request. End points that provide logged-in services would be able to use the same header for the creation and identification of a session, as well as throwing an error when the information is missing.

Client Auth Sequence:
IF (HAS_CACHED_TOKEN) Make request with X-Auth header set to TOKEN IF (TOKEN IS GOOD) - Server sends response appropriate to the request with X-Auth header set to 'Success;USER_DETAILS_LAST_UPDATE_TS' ELSE - Server sends response appropriate to the request with X-Auth header set to 'Failed'. Depending on the end point, the content of the request can be a success response if it doesn't require a user logged in (like dashboard) or in cases where the end point requires a logged in user, can be an error response. - Purge local TOKEN and user information. Prompt user for credentials, when applicable. ELSE Ask user for username and password. Make request to login endpoint (18.1) with X-Auth header set to Basic authentication of username & password IF (CREDENTIALS ARE GOOD) - Server sends user details as outlined in 18.1 along with the X-Auth header set to a session TOKEN. - Cache the TOKEN and user details. ELSE - Server responds with error response as outlined in 18.1. - Purge local TOKEN and user information, if any. Prompt user for credentials, when applicable.
X-prop-version
X-prop-version is added to response header on every API except verify. The value will be updated every time when there are any changes in settings. So that mobile client will call verify API to get the updated settings info.
Example:
```
Response Headers
Connection: Keep-Alive
Content-Type: application/json;charset=UTF-8
Date: Tue, 16 Oct 2018 08:25:04 GMT
Keep-Alive: timeout=5, max=100
Server: Apache
X-prop-version: 1539676694877
```

1.2. Error Handling

The absence of a '200 OK' HTTP Response Code indicates that there is an error. Error responses for all of the API calls can be of two types.

For server issues that transcend the API like:
- If our servers are under attack or unreachable
- Routing issues on the user's mobile network
- Our database is unreachable
- There's an unforeseen unhandled exception to one of the API calls
- An image at a URL that was cached by the mobile app no longer exists
- Other similar situations that have nothing to do with the API itself
You should expect a standard HTTP response instead of a JSON one. This response doesn't neccessarily originate from our servers depending on the situation. So, you should not rely on the response body to determine what the error is as this will most likely be a HTML error page and instead use the HTTP Response Status Code.
Sample Response

Status Code:
503 Service Temporarily Unavailable

Response body:
```
Service Temporarily Unavailable
The server is temporarily unable to service your request due to maintenance downtime or capacity problems. Please try again later.
```

For limitations imposed by the API
Limitations imposed by the API all have a non-success HTTP Response Code and a JSON response body indicating what the error is.

Response

Status Code:
4xx or 5xx response code appropriate to the situation.

Content Type:
application/json; charset=UTF-8

Response Parameters:

error.code	An alphanumeric code for internal use.
error.message	A descriptive message that can be displayed directly to the user.

Response Structure:

{
	"error": {
		"code": "",
		"message": ""
	}
}

Sample Response

Status Code:
403 Forbidden

Response body:

{
	"error": {
		"code": "1000",
		"message": "Method not supported on www.bths.edu. Please make this request to www.educationalnetworks.net instead."
	}
}

1.3. API Availability

API availability is dependent on the school's branding preferences and settings, and also on the version of the app. A school can choose to be enabled/disabled on the Educational Networks Unbranded App, School District's App and it's own branded app.

As mentioned in 1.2, the user-agent header must be set to 'EducationalNetworksMobile vX_Y/Z' with X being the platform, Y being the version of the app and /Z being the brandedWebsiteID when available. The version number of the app as well as the brandedWebsiteID will be used by the API to determine if the API response should be available or not.

When the API is not available, the response will be the standard error response as below:

Errors:

Code	Message	Notes
998	Mobile App is currently disabled for this school.
997	Mobile App version is too old.
996	Mobile App is no longer available for this school.	For requests coming from a Branded App and branded app is Disabled by us.

1.4. Staging & Troubleshooting

Staging is implemented by a combination of app-side and server side checks. Central to the interaction is the X-Test header that communicates the intent of the app and server and makes sure both sides are in sync by throwing appropriate errors.

Server behavior

A specific tomcat that is appropriately configured (with replica DB) can be marked as a staging server by setting en.mobileapi.staging=true in catalina.properties. When this property is set to true, FinderValve responds to all /m/api requests by setting the X-Test header to 1.
A list of test devices is specified as a comma separated list in the properties table under projectID=SYSTEM and pName=en.mobileapi.staging.devices. These are the only devices that are allowed to make requests to a staging server.
Requests will return a 403 status with a standard error response if:
- A request is made to a live server with X-Test header set, with the exception of www.educationalnetworks.net/m/api/verify.jsp
- A request is made to the staging servers with X-Test header not set, X-Push header not set (or) X-Push header set with a device id that is not a recognized test device
The server informs a device if it can turn on debugging features by responding with a 200 OK status to www.educationalnetworks.net/m/api/canitest.jsp
The www.educationalnetworks.net/m/api/verify.jsp API call directs the apps to staging by using the WWWSiteURL parameter. The app communicates the intent to test by specifying the X-Test header in the request to www.educationalnetworks.net/m/api/verify.jsp.
If the X-Test header is present in the request and the device is allowed to test, the WWWSiteURL will be set to the staging servers.
If the X-Test header is absent, the WWWSiteURL will be set to the live servers

Mobile App behavior

On all compiled apps, in debug mode or not, running in an emulator or device, installed from an apk or from the store, the primary mechanism by which the device identifies itself as available for testing is by making a request to www.educationalnetworks.net/m/api/canitest.jsp. This request must be made at initialization (and) any time the request has a X-Test header and the response is an error or does not reciprocate with the X-Test header set in the response. There is no need to check for whether the app is in 'debug' mode from the platform since we are checking for the device id on the server. Having the ability to turn this mode on and off on live devices from the server will be useful.
If available for testing, in addition to other mechanisms for testing, also show an icon in the navigation drawer for 'Developer' that shows a screen with options to enable / disable test mode, manually clear caches, and prints out information about platform, device id, app package name, user agent, current notification token, current active session id, current navigation menu version, current user info version and any other information that may become relevant in the future.
If test mode is turned on, every http request that the app is making must have the X-Test header set to 1.
If the response of any request doesn't have the X-Test header set to 1, the app must turn off test mode.
Any time the test mode is toggled, all caches would need to be invalidated for each school and new verify request to get the school details must be made.

2. School Lookup and Info

Schools are looked up by providing keywords to match the school's name and the state of the school. You can use this api call to verify that a school indeed exists and obtain information about the school and it's mobile app configuration.

The mobile app configuration, at this moment, includes the list of modules to be shown on the homescreen. This and other settings can be updated by the school staff by going to Settings > Mobile App.

List of schools that are good testing candidates for the entire app.
Website Name	URL	Configuration (LIVE DATA!!!)
Doral Academy Preparatory	www.doralacademyprep.org	Settings
Somerset Academy	www.somersetacademy.com	Settings
Saint Joseph High School	www.saintjoehigh.com	Settings
Mater Academy Charter Middle/ High	www.matermiddlehigh.org	Settings
Gloucester County Institute of Technology	www.gcit.org	Settings
Pinecrest Preparatory Middle-High School	www.ppmhcharterschool.org	Settings
Camden City School District	www.camden.k12.nj.us	Settings
The Bronx High School of Science	www.bxscience.edu	Settings
Brooklyn Technical High School	www.bths.edu	Settings
Rancocas Valley Regional High School	www.rvrhs.com	Settings
Pueblo County School District 70	www.district70.org	Settings
Susan E. Wagner High School	www.wagnerhigh.net	Settings
South Dade Senior High	www.sdshs.net	Settings
Pine Grove Area School District	www.pgasd.com	Settings
Cardinal Spellman High School	www.cardinalspellman.org	Settings
Forest Hills High School	www.foresthillshs.org	Settings
Benjamin N. Cardozo High School	www.cardozohigh.com	Settings
Kenwood Academy High School	www.kenwoodacademy.org	Settings
Stuyvesant High School	stuy.enschool.org	Settings
Amundsen High School	www.amundsenhs.org	Settings
Saint Joseph High School	www.stjoes.org	Settings
Our Lady of Mercy Academy	www.olma.org	Settings
Gloucester Township Public Schools	www.gloucestertownshipschools.org	Settings
Iona Preparatory School K-12	www.ionaprep.org	Settings
Appoquinimink School District	www.apposchooldistrict.com	Settings

Usage Notes

The information obtained about a school via this request should be cached in the app.
When this call provides multiple results, a list of schools with the website name and url must be shown to the user for selection.
Periodic calls to this same URL using the full website name (from having cached this from a previously successful match), schoolState and websiteID will provide any updates made to the school information or to the configuration. Using the full school name with the state and websiteID is guaranteed to return only one result.

Under construction websites (previously needing EduNetDevMode Header)

When this request is made from a branded app, the responses for search will also include Under Construction websites as opposed to just Live websites. The header is no longer required.

X-Push Header: Push Notifications token validity test

Unless notifications are turned off on the device, every call to /m/api/verify.jsp should include the 'X-Push' header. The server doesn't complain if it's missing.
The value of 'X-Push' header must be DEVICE_ID::DEVICE_TYPE::TOKEN
When 'X-Push' is present in the request, the verify.jsp call checks the status of the latest notification pushed to the token.
If the status is successful, the response will NOT include a 'X-Push' header.
If the status is unsuccessful, the response will include a 'X-Push' header with the recommended provisioning 'fn' task.

Request

URL:
https://www.educationalnetworks.net/m/api/verify.jsp

Request Parameters:

websiteName	Either the full school name or keywords to match the school name
schoolState	Two letter state name
websiteID (optional)	websiteID of the school
version (optional)	version number of the properties you currently have.

If version number and websiteID are specified and the provided version is greater than or equal to the latest version of properties for the website, the response will be a 304 Not Modified.

Response

Response Parameters:

version	Version number of the current set of properties for the school including dashboard and menu.
websiteID	Unique code identifying the website used by various modules. Not the same as the verification code.
WWWSiteURL	The live site URL of the school. All API requests, images, file attachments etc. are relative to this URL.
websiteName	Full name of the school.
displayName	Preferred name of the school for the mobile app, for branding and display.
schoolPhone	Main phone number of the school. No spaces or separators.
schoolAddress.lat	Geo latitude of the school. (optional)
schoolAddress.lon	Geo longitude of the school. (optional)
schoolAddress.schoolAddress1	Street address of the school.
schoolAddress.schoolCity	City in which the school is located
schoolAddress.schoolState	State in which the school is located.
schoolAddress.schoolZIP	Zip code of the school's location
qrcodeEnabled	Boolean flag to show if QR code is enabled/disabled.
pushNotificationTopics	An array of push notification topics for the school. This will never be empty.
pushNotificationTopics[].mnrtREC_ID	Unique REC_ID for the push notification topic.
pushNotificationTopics[].mnrtName	Name for the push notification topic that can be displayed to users.
homescreen_items	An array of homescreen item descriptions. This will never be empty.
homescreen_items[].title	Label to use in the app for this item. This can be different from the actual name of the section and can be edited from the settings screen in the CMS.
homescreen_items[].module	Module identifier. The list of possible values are: NEWS EVENTS_CALENDAR BULLETIN_BOARD PHOTO_ALBUM STAFF SPOTLIGHT CLASSES_AND_HOMEWORK DEPARTMENTS VIDEO BELL_SCHEDULES LINKS WEBLINK
homescreen_items[].params[]	Additional parameters to identify sub-sections or to filter results for the module. Will be a array of hashes This will be present only if there are additional parameters specified.
themeStyle.colorAccent	Hex color code of Accent color. This can be edited from the settings screen in the CMS. The default accent color is #ff4081.
themeStyle.colorPrimary	Hex color code of Primary color. This can be edited from the settings screen in the CMS. The default primary color is #2196f3.
themeStyle.colorPrimaryDark	Hex color code of Primary Dark Color. This can be edited from the settings screen in the CMS. The default primary dark color is #1976d2.
themeStyle.colorPrimaryLight	Hex color code of Primary Light Color. This can be edited from the settings screen in the CMS. The default primary light color is #bbdefb.
themeStyle.colorSecondary	Hex color code of Secondary Color. This can be edited from the settings screen in the CMS. The default secondary color is #123456.
publicAccounts.allowStudentSignup	School allows student registration
publicAccounts.allowParentSignup	School allows parent registration
publicAccounts.allowAlumniSignup	School allows alumni registration
publicAccounts.allowOtherSignup	School allows other members registration
publicAccounts.isStudentIDActive	School allows to provide studentID while student registration

Response Structure:
Array of website info hashes.

[
{
	"version" : <>,
	"websiteID" : "",
	"WWWSiteURL" : "",
	"websiteName" : "",
	"displayName" : "",
	"schoolPhone" : "",
	"schoolAddress" : {
		"lat": "",
		"lon": "",
		"schoolAddress1" : "",
		"schoolCity" : "",
		"schoolState" : "",
		"schoolZIP" : ""
	},
	"qrcodeEnabled": true|false,
	"pushNotificationTopics": [
		{ 
			"mnrtREC_ID": "",
			"mnrtName": "" 
		}
	],
	"homescreen_items" : [
		{
			"title": "",
			"module": "",
			"params": [
			 	{
			 	},
			 	...
			]
		}
	],
	"themeStyle": {
		"colorAccent" : "",
		"colorPrimary" : "",
		"colorPrimaryDark" : "",
		"colorPrimaryLight" : "",
		"colorSecondary" : ""
	},
	"publicAccounts": {
		"allowStudentSignup": true|false,
		"allowParentSignup": true|false,
		"allowAlumniSignup": true|false,
		"allowOtherSignup": true|false,
		"isStudentIDActive": true|false
	}
},
...
]

Errors:

Code	Message
1001	No school found.
1002	Please enter more specific search terms.

Notes:
This call tries to match the full school name with the provided websiteName parameter. If there is no exact match, it matches the school name with the keywords, after removing common stop words like 'school', 'preparatory', 'of', 'the' etc. If the number of results matching the input after removing the stop words are >9 or 0, an error response is returned asking for more specific keywords.

Sample Response (generic keywords provided)

URL:
https://www.educationalnetworks.net/m/api/verify.jsp?websiteName=High%20School&schoolState;=FL

Response body:

{
	"error": {
		"code": "1002",
		"message": "Please enter more specific search terms."
	}
}

Sample Response (New version of properties available)

URL:
https://www.educationalnetworks.net/m/api/verify.jsp?websiteName=Greentech%20High%20School&schoolState;=NY&websiteID;=GTECH-RED&version;=1234

Response body:

[
{
	"version" : 1494929213464,
	"websiteID" : "GTECH-RED",
	"WWWSiteURL" : "www.greentechhs.org",
	"websiteName" : "GreenTech High School",
	"displayName" : "GreenTech High School",
	"schoolPhone" : "8665260200",
	"schoolAddress" : {
		"schoolAddress1" : "80 Broad St.",
		"schoolCity" : "New York",
		"schoolState" : "NY",
		"schoolZIP" : "10004"
	},
	"pushNotificationTopics": [
		{ 
			"mnrtREC_ID": 0,
			"mnrtName": "main" 
		}
	],
	"homescreen_items" : [
		{
			"title": "Events Calendar",
			"module": "EVENTS_CALENDAR",
			"params": [
				{
					"id": "0"
				}
			] 
		},
		{
			"title": "News and Announcements",
			"module": "NEWS",
			"params": [
				{
					"id": "0"
				}
			] 
		},
		{
			"title": "Bulletin Board",
			"module": "BULLETIN_BOARD"
		},
		{
			"title": "Photo Album",
			"module": "PHOTO_ALBUM"
		},
		{
			"title": "Student of the Month",
			"module": "SPOTLIGHT",
			"params": [
				{
					"categoryREC_ID": "2628"
				}
			] 
		},
		{
			"title": "Classes",
			"module": "CLASSES_AND_HOMEWORK"
		},
		{
			"title": "Departments",
			"module": "DEPARTMENTS"
		},
		{
			"title": "Video Gallery",
			"module": "VIDEO"
		},
		{
			"title": "Staff Directory",
			"module": "STAFF"
		},
		{
			"title": "Academic Events",
			"module": "EVENTS_CALENDAR",
			"params": [
				{
					"id": "1"
				}
			] 
		},
		{
			"title": "Google",
			"module": "WEBLINK",
			"params": [
				{
					"webViewURL": "https://www.google.com"
				}
			] 
		}
	],
	"themeStyle": {
		"colorAccent": "#ff4081",
		"colorPrimary": "#2196f3",
		"colorPrimaryDark": "#1976d2",
		"colorPrimaryLight": "#bbdefb",
		"colorSecondary": "#123456"
	}
}
]

Sample Response

URL:
https://www.educationalnetworks.net/m/api/verify.jsp?websiteName=Doral%20Academy&schoolState;=FL

Response body:

[
{
	"version" : 123,
	"websiteID" : "DORALHS",
	"WWWSiteURL" : "www.doralacademyprep.org",
	"websiteName" : "Doral Academy Preparatory",
	"displayName" : "Doral Academy Prep",
	"schoolPhone" : "3055910020",
	"schoolAddress" : {
		"schoolAddress1" : "11100 NW 27th Street",
		"schoolCity" : "Doral",
		"schoolState" : "FL",
		"schoolZIP" : "33172"
	},
	"pushNotificationTopics": [
		{ 
			"mnrtREC_ID": 0,
			"mnrtName": "main" 
		}
	],
	"homescreen_items" : [
		{
			"title": "News and Announcements",
			"module": "NEWS",
			"params": "id=0"
		},
		{
			"title": "Events Calendar",
			"module": "EVENTS_CALENDAR",
			"params": "id=0"
		},
		{
			"title": "Bulletin Board",
			"module": "BULLETIN_BOARD"
		},
		{
			"title": "Photo Album",
			"module": "PHOTO_ALBUM"
		},
		{
			"title": "Staff Directory",
			"module": "STAFF"
		},
		{
			"title": "Classes",
			"module": "CLASSES_AND_HOMEWORK"
		},
		{
			"title": "Departments",
			"module": "DEPARTMENTS"
		},
		{
			"title": "Video Gallery",
			"module": "VIDEO"
		}
	],
	"themeStyle" : {
		"colorAccent" : "#ff4081", 
		"colorPrimary" : "#2196f3", 
		"colorPrimaryDark" : "#1976d2", 
		"colorPrimaryLight" : "#bbdefb", 
		"colorSecondary" : "#123456" 
	}
},
{
	"version" : 456,
	"websiteID" : "DORALES",
	"WWWSiteURL" : "www.doralacademyes.org",
	"websiteName" : "Doral Academy Elementary School",
	"displayName" : "Doral Academy Elementary School",
	"schoolPhone" : "3055979999",
	"schoolAddress" : {
		"schoolAddress1" : "2450 NW 97 Avenue",
		"schoolCity" : "Doral",
		"schoolState" : "FL",
		"schoolZIP" : "33172"
	},
	"pushNotificationTopics": [
		{ 
			"mnrtREC_ID": 0,
			"mnrtName": "main" 
		}
	],
	"homescreen_items" : [
		{
			"title": "News and Announcements",
			"module": "NEWS",
			"params": "id=0"
		},
		{
			"title": "Events Calendar",
			"module": "EVENTS_CALENDAR",
			"params": "id=0"
		},
		{
			"title": "Bulletin Board",
			"module": "BULLETIN_BOARD"
		},
		{
			"title": "Photo Album",
			"module": "PHOTO_ALBUM"
		},
		{
			"title": "Staff Directory",
			"module": "STAFF"
		},
		{
			"title": "Classes",
			"module": "CLASSES_AND_HOMEWORK"
		},
		{
			"title": "Departments",
			"module": "DEPARTMENTS"
		},
		{
			"title": "Video Gallery",
			"module": "VIDEO"
		}
	],
	"themeStyle" : {
		"colorAccent" : "#ff4081", 
		"colorPrimary" : "#2196f3", 
		"colorPrimaryDark" : "#1976d2", 
		"colorPrimaryLight" : "#bbdefb", 
		"colorSecondary" : "#123456" 
	}
},
{
	"version" : 799999,
	"websiteID" : "DORALCOLLEGE",
	"WWWSiteURL" : "www.doralcollege.com",
	"websiteName" : "Doral College",
	"displayName" : "Doral College",
	"schoolPhone" : "3054637210",
	"schoolAddress" : {
		"schoolAddress1" : "11100 NW 27th Street, Bldg C-109",
		"schoolCity" : "Doral",
		"schoolState" : "FL",
		"schoolZIP" : "33172"
	},
	"pushNotificationTopics": [
		{ 
			"mnrtREC_ID": 0,
			"mnrtName": "main" 
		}
	],
	"homescreen_items" : [
		{
			"title": "News and Announcements",
			"module": "NEWS",
			"params": "id=0"
		},
		{
			"title": "Events Calendar",
			"module": "EVENTS_CALENDAR",
			"params": "id=0"
		},
		{
			"title": "Bulletin Board",
			"module": "BULLETIN_BOARD"
		},
		{
			"title": "Photo Album",
			"module": "PHOTO_ALBUM"
		},
		{
			"title": "Staff Directory",
			"module": "STAFF"
		},
		{
			"title": "Classes",
			"module": "CLASSES_AND_HOMEWORK"
		},
		{
			"title": "Departments",
			"module": "DEPARTMENTS"
		},
		{
			"title": "Video Gallery",
			"module": "VIDEO"
		}
	],
	"themeStyle" : {
		"colorAccent" : "#ff4081", 
		"colorPrimary" : "#2196f3", 
		"colorPrimaryDark" : "#1976d2", 
		"colorPrimaryLight" : "#bbdefb", 
		"colorSecondary" : "#123456" 
	}
},
{
	"version" : 0,
	"websiteID" : "DORALACADINC",
	"WWWSiteURL" : "www.doralacademyschools.org",
	"websiteName" : "Doral Academy, Inc.",
	"displayName" : "Doral Inc",
	"schoolPhone" : "3056692906",
	"schoolAddress" : {
		"schoolAddress1" : "6340 Sunset Drive",
		"schoolCity" : "Miami",
		"schoolState" : "FL",
		"schoolZIP" : "33143"
	},					
	"pushNotificationTopics": [
		{ 
			"mnrtREC_ID": 0,
			"mnrtName": "main" 
		}
	],					
	"homescreen_items" : [
		{
			"title": "News and Announcements",
			"module": "NEWS",
			"params": "id=0"
		},
		{
			"title": "Events Calendar",
			"module": "EVENTS_CALENDAR",
			"params": "id=0"
		},
		{
			"title": "Bulletin Board",
			"module": "BULLETIN_BOARD"
		},
		{
			"title": "Photo Album",
			"module": "PHOTO_ALBUM"
		},
		{
			"title": "Staff Directory",
			"module": "STAFF"
		},
		{
			"title": "Classes",
			"module": "CLASSES_AND_HOMEWORK"
		},
		{
			"title": "Departments",
			"module": "DEPARTMENTS"
		},
		{
			"title": "Video Gallery",
			"module": "VIDEO"
		}
	],
	"themeStyle" : {
		"colorAccent" : "#ff4081", 	
		"colorPrimary" : "#2196f3",
		"colorPrimaryDark" : "#1976d2", 
		"colorPrimaryLight" : "#bbdefb", 
		"colorSecondary" : "#123456" 
	}
}
]

Sample Response

URL:
https://www.educationalnetworks.net/m/api/verify.jsp?websiteName=Doral%20Academy&schoolState;=FL&websiteID;=DORALCOLLEGE

Response body:

[
{
	"version" : 12345,
	"websiteID" : "DORALCOLLEGE",
	"WWWSiteURL" : "www.doralcollege.com",
	"websiteName" : "Doral College",
	"displayName" : "Doral College",
	"schoolPhone" : "3054637210",
	"schoolAddress" : {
		"schoolAddress1" : "11100 NW 27th Street, Bldg C-109",
		"schoolCity" : "Doral",
		"schoolState" : "FL",
		"schoolZIP" : "33172"
	},				
	"pushNotificationTopics": [
		{ 
			"mnrtREC_ID": 0,
			"mnrtName": "main" 
		}
	],					
	"homescreen_items" : [
		{
			"title": "News and Announcements",
			"module": "NEWS",
			"params": "id=0"
		},
		{
			"title": "Events Calendar",
			"module": "EVENTS_CALENDAR",
			"params": "id=0"
		},
		{
			"title": "Bulletin Board",
			"module": "BULLETIN_BOARD"
		},
		{
			"title": "Photo Album",
			"module": "PHOTO_ALBUM"
		},
		{
			"title": "Staff Directory",
			"module": "STAFF"
		},
		{
			"title": "Classes",
			"module": "CLASSES_AND_HOMEWORK"
		},
		{
			"title": "Departments",
			"module": "DEPARTMENTS"
		},
		{
			"title": "Video Gallery",
			"module": "VIDEO"
		}
	],
	"themeStyle" : {
		"colorAccent" : "#ff4081", 
		"colorPrimary" : "#2196f3", 
		"colorPrimaryDark" : "#1976d2", 
		"colorPrimaryLight" : "#bbdefb", 
		"colorSecondary" : "#123456" 
	}
}
]

3.0. Push Notification Payload

{
	"data": {
		"websiteID": ""
	},
	"notification": {
		"title": "",
		"body": "",
		"sound": "default"
	},
	"registration_ids": [
		"",
		...
	]
}

3.1. Number of new Notifications

With the exception of /m/api/verify.jsp and /m/api/push_notifications/list.jsp, if the following expanded X-Push header is present in the request, the response will include a X-Push header set to the number of new notifications.

Request Headers:

X-Push

Valid firebase token info and 'after' date in DEVICE_ID::DEVICE_TYPE::TOKEN::yyyy-MM-dd HH:mm:ss format

Response Headers:

X-Push

Number of new notifications after the 'after' date mentioned

3.2. Token Provisioning for Push Notifications

Request

Method:
POST

URL:
/m/api/push_notifications/provision.jsp

Request Parameters:

fn	Provisioning task. Possible values are 'Insert', 'Update' & 'Delete'
pnsDeviceName	Nickname of the user of the device (optional)
pnsDeviceId	Unique device id of the device.
pnsDeviceType	Type of the device. Possible values are: 'Android', 'iOS'
pnsToken	Firebase token for the combination of device and website
pnsWebsiteIDs	Comma separated website IDs list (only when request originates from branded app to the WWWSiteURL of the hardcoded brandedWebsiteID of the app, w/ appropriate header set)

Response

Response Parameters:
If successful, the body of this request will be empty and the response code will be a 200.

Errors:

Code	Message
3001	One or more required parameters are missing.
3002	Invalid provisioning request.
3003	Invalid device type.
3004	Could not complete provisioning request: {ERROR_MESSAGE_NOT_TO_BE_SHOWN_TO_THE_USER}.
3005	Multiple websiteIDs only supported on bundled version.

Usage Notes

A new website addition in the unbranded app or first time access on the branded app should generate a 'Insert' request.
When a website is removed or the app is being removed or if for whatever reason, the notifications need to suppressed (e.g. user's preferences), a 'Delete' request must be generated.
Any time the app detects the token it has is invalid or if the server tells the app that the token is invalid (Refer to 'X-Push' header and verify.jsp), the app must generate a new token client side and send the new token with an 'Update' request.
When pnsWebsiteIDs is set, the 'fn' is performed on all websites mentioned in the list.

3.3. Notifications List

Get a list of push notifications.

If 'after' is specified, all notifications after the date will be returned. 'after' must be set to the date of the latest notification the client has.

Request

URL:
/m/api/push_notifications/list.jsp

Request Parameters:

after

Timestamp in yyyy-MM-dd HH:mm:ss format. (Optional)

Request Headers:

X-Push

Valid firebase token info in DEVICE_ID::DEVICE_TYPE::TOKEN format

Response

Response Parameters:

date	Timestamp on which the notification was sent out.
message	Content of the notification.
image	Full image path relative to the website url for the notification (optional)
imagesInfo	Hash of image information for the notification. (optional)
imagesInfo.path	Relative path of the image (optional)
imagesInfo.width	Width of the image (optional)
imagesInfo.height	Height of the image (optional)
imagesInfo.modified	Modified timestamp of the image (optional)
imagesInfo.size	File size on disk of the image (optional)
link	Absolute URL of the link for use with web view for the notification (optional)
pnREC_ID	Unique REC_ID for the notification.

Response Structure:
Array of notification item info hashes.

[
{
	"date": "",
	"message": "",
	"image": "",
	"imagesInfo": {
		"path": "",
		"width": "",
		"height": "",
		"modified": "",
		"size": ""
	},
	"link": "",
	"pnREC_ID": ""
},
...
]

Errors:

Code	Message	Response Header
3005	Invalid timestamp
3006	X-Push information missing	'X-Push' set to appropriate provisioning fn
3007	Invalid token

3.4. Notification Item

All information about a single notification item.

Request

URL:
/m/api/push_notifications/item.jsp

Request Parameters:

pnREC_ID

Unique pnREC_ID of the notification item

Response

Response Parameters:

date	Timestamp on which the notification was sent out.
message	Content of the notification.
image	Full image path relative to the website url for the notification (optional)
link	Absolute URL of the link for use with web view for the notification (optional)
pnREC_ID	Unique REC_ID for the notification.

Response Structure:
Notification item hash.

{
	"date": "",
	"message": "",
	"image": "",
	"link": "",
	"pnREC_ID": ""
}

Errors:

Code	Message	Response Header
3008	Notification does not exist.

4.1. News List

Get a list of news items for a specific news section. All the necessary parameters identifying a news section can be obtained from the module configuration for a specific website.

Request

URL:
/m/api/news/list.jsp

Request Parameters:

id	Numeric section if of the news section.
start	0-based index to show items from within the section. Default is 0.

Response

Response Parameters:

date	Last update date of the news item.
title	Title of the news item.
summary	News item summary (optional)
thumbnail	Thumbail path either relative to the website url or in case of pushed items, an absolute URL (optional)
hasMoreInfo	Boolean indicating whether the news item has more info that in the list.
hasHTMLContent	Boolean indicating whether the server was able to clean up the HTML without loss of content. If true, item should be shown in web view as opposed to natively.
webViewURL	URL to be used to show the individual item in a web view based on the hasHTMLContent flag
REC_ID	Unique REC_ID for this news item.

Response Structure:
Array of news item info hashes.

[
{
	"date" : "",
	"title" : "",
	"summary" : "",
	"hasMoreInfo" : true|false,
	"hasHTMLContent" : true|false,
	"webViewURL" : "",
	"REC_ID" : ""
},
...
]

Errors:

Code	Message
2001	News section corresponding to section id does not exist.
2002	start value is out of bounds. {0-#total-1} is valid range.

4.2. News Item

All information about a single news item belonging a known news section.

Request

URL:
/m/api/news/item.jsp

Request Parameters:

id	Numeric section if of the news item.
REC_ID	Unique REC_ID of the news item.

Response

Response Parameters:

date	Last update date of the news item.
title	Title of the news item.
summary	News item summary (optional)
news-date	Date of the occurance of the news (optional)
story	A full story associated with the news. (optional)
url	Web link associated with the news. (optional)
source	Source of the news item. (optional)
files	Hash for attachments to the news item. (optional: present only if there are files or images)
files.images	List of image filenames in the files.path directory. (optional)
files.imagesInfo	List of hash of image information in the files.path directory. (optional)
files.imagesInfo[].path	Relative path of the image (optional)
files.imagesInfo[].width	Width of the image (optional)
files.imagesInfo[].height	Height of the image (optional)
files.imagesInfo[].modified	Modified timestamp of the image (optional)
files.imagesInfo[].size	File size on disk of the image (optional)
files.other	List of non-image filenames in the files.path directory (optional)
files.path	Relative (or) absolute (for pushed news) URL to the directory path containing attachments to this news item.
REC_ID	Unique REC_ID for this news item.

Response Structure:

{
	"date" : "",
	"title" : "",
	"summary" : "",
	"news-date" : "",
	"story" : "",
	"url" : "",
	"source" : "",
	"files": {
		"images" : [
			"", 
			...
		],
		"imagesInfo": [
		 	{
		 		"path": "",
		 		"width": "",
		 		"height": "",
		 		"modified": "",
		 		"size": ""
		 	},
		 	...
		],
		"other" : [
			"", 
			...
		],
		"path": ""
	}
	"REC_ID" : ""
}

Errors:

Code	Message
2001	News section corresponding to section id does not exist.
2003	News item corresponding to the REC_ID does not exist.

5.1. Events List

Get a list of events for a specific events section, combination of event sections or for a department/staff/class.

Request

URL:
/m/api/events/list.jsp

Request Parameters:

cREC_ID	One or more REC_IDs of calendar sections. Multiple cREC_IDs may be ';' separated.
id	Alternative way to get events. For use with departments, staff and classes: d<uREC_ID> for departments, u<uREC_ID> for staff, cl<classREC_ID> for classes.
y	Year to get events, in yyyy format. Default is current year.
m	Month number to get events. 1 is January and 12 is December. Default is current month.
d	Date number to get events. Default is today.

Notes on pagination:
For the combination of parameters provided above, this request will return the events for the next 7 days starting from the day of the closest upcoming event. Meaning, if the next event is on 11/5/18, regardless of what date provided between now and that date, the returned results would be for 11/5/18 - 11/11/18

Notes on multi-day events:
For multi-day events, the event reappears for every day it spans with the appropriate set of flags set. For example, if an event spans from 11/5/18 - 11/11/18, you will see the event listed under the events[] for every single date between 11/5/18 and 11/11/18.

Response

Response Parameters:

date	Date of the events list.
events	List of events for the date.
events[].title	Title of the event
events[].date_from	Start date of the event in yyyy-mm-dd format
events[].date_to	End date of the event in yyyy-mm-dd format
events[].time_from	Start time of the event in HH:mm:ss format
events[].time_to	End time of the event in HH:mm:ss format
events[].location	Location info of the event (optional)
events[].thumbnail	Thumbail path either relative to the website url or in case of pushed items, an absolute URL (optional)
events[].imagesInfo	List of hash of image information in the files.path directory. (optional)
events[].imagesInfo.path	Relative path of the image (optional)
events[].imagesInfo.width	Width of the image (optional)
events[].imagesInfo.height	Height of the image (optional)
events[].imagesInfo.modified	Modified timestamp of the image (optional)
events[].imagesInfo.size	File size on disk of the image (optional)
events[].url	Link attached to the event (optional)
events[].description	Description of the event (optional)
events[].isAllDayEvent	Flag indicating if event is an all day event
events[].isRecurringgEvent	Flag indicating if event is a recurring event
events[].isMultiDayEvent	Flag indicating if event is part of a multi-day event
events[].isFirstDayOfMultiDayEvent	Flag indicating if event is first day for a multi- day event
events[].isLastDayOfMultiDayEvent	Flag indicating if event is last day for a multi- day event
events[].hasHTMLContent	Boolean indicating whether the server was able to clean up the HTML without loss of content. If true, item should be shown in web view as opposed to natively.
events[].webViewURL	URL to be used to show the individual item in a web view based on the hasHTMLContent flag
REC_ID	Unique REC_ID for this event item.

Response Structure:
Array of news item info hashes.

[
{
	"date": "", 
	"events": [
		{
			"title": "",
			"date_from": "",
			"date_to": "",
			"time_from": "",
			"time_to": "",
			"location": "",
			"thumbnail": "",
			"imagesInfo": {
				"path": "",
				"width": "",
				"height": "",
				"modified": "",
				"size": ""
			},
			"url": "",
			"description": "",
			"isAllDayEvent": true|false,
			"isRecurringgEvent": true|false,
			"isMultiDayEvent": true|false,
			"isFirstDayOfMultiDayEvent": true|false,
			"isLastDayOfMultiDayEvent": true|false,
			"hasHTMLContent" : true|false,
			"webViewURL" : "",
			"REC_ID": ""
		},
		...
	]
},
...
]

Errors:

Code	Message
N/A	Not available yet.

5.2. Event Item

All information about a single event item belonging a known events section.

Request

URL:
/m/api/events/item.jsp

Request Parameters:

cREC_ID	One or more REC_IDs of calendar sections. Multiple cREC_IDs may be ';' separated.
id	Alternative way to get events. For use with departments, staff and classes: d<uREC_ID> for departments, u<uREC_ID> for staff, cl<classREC_ID> for classes.
REC_ID	Unique REC_ID of the event item.

Response

Response Parameters:

title	Title of the event
date_from	Start date of the event in yyyy-mm-dd format
date_to	End date of the event in yyyy-mm-dd format
time_from	Start time of the event in HH:mm:ss format
time_to	End time of the event in HH:mm:ss format
location	Location info of the event (optional)
url	Link attached to the event (optional)
description	Description of the event (optional)
files	Hash for attachments to the events item. (optional: present only if there are files or images)
files.images	List of image filenames in the files.path directory. (optional)
files.imagesInfo	List of hash of image information in the files.path directory. (optional)
files.imagesInfo[].path	Relative path of the image (optional)
files.imagesInfo[].width	Width of the image (optional)
files.imagesInfo[].height	Height of the image (optional)
files.imagesInfo[].modified	Modified timestamp of the image (optional)
files.imagesInfo[].size	File size on disk of the image (optional)
files.other	List of non-image filenames in the files.path directory (optional)
files.path	Directory path containing attachments relative to the website url.
REC_ID	Unique REC_ID for this event item.

Response Structure:

{
	"title": "",
	"date_from": "",
	"date_to": "",
	"time_from": "",
	"time_to": "",
	"location": "",
	"url": "",
	"description": "",
	"files": {
		"images" : [
			"", 
			...
		],
		"imagesInfo": [
		 	{
		 		"path": "",
		 		"width": "",
		 		"height": "",
		 		"modified": "",
		 		"size": ""
		 	},
		 	...
		],
		"other" : [
			"", 
			...
		],
		"path": ""
	}
	"REC_ID" : ""
}

Errors:

Code	Message
N/A	Not available yet.

6.1. Bulletin Board List

Get a list of items in the bulletin board. There are no sections for bulletin board.

Request

URL:
/m/api/bulletin_board/list.jsp

Request Parameters:

start

0-based index to show items from. Default is 0.

Response

Response Parameters:

title	Title of the bulletin board item.
message	The message content (optional)
hasMoreInfo	Boolean indicating whether the bulletin board item has more info than just the title & message.
hasHTMLContent	Boolean indicating whether the server was able to clean up the HTML without loss of content. If true, item should be shown in web view as opposed to natively.
webViewURL	URL to be used to show the individual item in a web view based on the hasHTMLContent flag
REC_ID	Unique REC_ID for this bulletin board item.

Response Structure:
Array of bulletin board item info hashes.

[
{
	"title" : "",
	"message" : "",
	"hasMoreInfo" : true|false,
	"hasHTMLContent" : true|false,
	"webViewURL" : "",
	"REC_ID" : ""
},
...
]

Errors:

Code	Message
4001	start value is out of bounds. {0-#total-1} is valid range.

6.2. Bulletin Board Item

All information about a single bulletin board item.

Request

URL:
/m/api/bulletin_board/item.jsp

Request Parameters:

REC_ID

Unique REC_ID of the bulletin board item.

Response

Response Parameters:

title	Title of the bulletin board item.
message	The message content (optional)
files	Hash for attachments to the bulletin board item. (optional: present only if there are files or images)
files.images	List of image filenames in the files.path directory. (optional)
files.imagesInfo	List of hash of image information in the files.path directory. (optional)
files.imagesInfo[].path	Relative path of the image (optional)
files.imagesInfo[].width	Width of the image (optional)
files.imagesInfo[].height	Height of the image (optional)
files.imagesInfo[].modified	Modified timestamp of the image (optional)
files.imagesInfo[].size	File size on disk of the image (optional)
files.other	List of non-image filenames in the files.path directory (optional)
files.path	Directory path containing attachments relative to the website url.
contact	Hash for contact info attached to the bulletin board item. (optional: present only contact details are present)
contact.name	Name of the contact. (optional)
contact.phone	Pohne number of the contact. Stripped of all special characters (optional)
contact.email	Email address of the contact (optional).
REC_ID	Unique REC_ID for this bulletin board item.

Response Structure:

{
	"title" : "",
	"message" : "",
	"files": {
		"images" : [
			"", 
			...
		],
		"imagesInfo": [
		 	{
		 		"path": "",
		 		"width": "",
		 		"height": "",
		 		"modified": "",
		 		"size": ""
		 	},
		 	...
		],
		"other" : [
			"", 
			...
		],
		"path": ""
	},
	"contact": {
		"name" : "",
		"phone" : "",
		"email": ""
	},
	"REC_ID" : ""
}

Errors:

Code	Message
4002	Bulletin Board item corresponding to the REC_ID does not exist.

7. Photo Albums

List of albums, sub albums and photos for the entire photo albums module. Photo albums consists of three entities: folders, albums and photos. Folders can only have other folders and albums. Albums can only have photos. In the API, folders are treated just as albums containing other albums and folders (use albumIsFolder for distinction).

Request

URL:
/m/api/photo_album/list.jsp

Request Parameters:

albumREC_ID

Unique albumREC_ID of the album. Leave it blank to get the main album.

Response

Response Parameters:

albumName	Name of the album for the albumREC_ID. For the main album, it's 'Album Home'.
albumDesc	Description of the album (optional)
albumIsFolder	Boolean indicating if current album is an album or folder.
subAlbums	Array of sub album info hashes. (optional: present when albumIsFolder is true)
subAlbums[].albumName	Name of the sub album
subAlbums[].albumDesc	Description of the sub album
subAlbums[].albumIsFolder	Boolean indicating whether sub album is album or folder
subAlbums[].numSubAlbums	# of sub albums in this sub album. (optional: when albumIsFolder is true)
subAlbums[].numPhotos	# of photos in this sub album. (optional: when albumIsFolder is false.)
subAlbums[].albumCover	Cover image info for the sub album. (optional: when albumIsFolder is false.)
subAlbums[].albumCover.photoLocation	Full path relative to the website URL for the full sized cover image
subAlbums[].albumCover.photoCaption	Caption for the cover image of the album cover. (optional)
subAlbums[].folderCover	Array of cover images of sub albums of currnet sub album. Upto 4 sub album cover will be chosen at random. (optional: when albumIsFolder is true and there's one or more sub albums with a cover.)
subAlbums[].folderCover[].photoLocation	Full path relative to the website URL for the full sized cover image
subAlbums[].folderCover[].photoCaption	Caption for the cover image of the album cover. (optional)
subAlbums[].folderCover[].photoREC_ID	Unique REC_ID for the cover image of the album cover.
subAlbums[].albumREC_ID	Unique REC_ID of this sub album
photos	Array of photo info hashes (optiona: present when albumIsFolder is false)
photos[].photoLocation	Full path relative to the website URL for the full sized photo.
photos[].photoCaption	Caption for the photo. (optional)
photos[].photoREC_ID	Unique REC_ID for this photo.
albumREC_ID	Unique REC_ID for this album.

Response Structure:

{
	"albumName" : "",
	"albumDesc" : "",
	"albumIsFolder" : true|false,
	"subAlbums": [
	{
		"albumName": "",
		"albumDesc": "",
		"albumIsFolder": true|false,
		"albumCover" : {
			"photoLocation": "", 
			"photoCaption": "",
			"photoREC_ID": ""
		},
		"folderCover" : [
			{
				"photoLocation": "", 
				"photoCaption": "",
				"photoREC_ID": ""
			},
			...
		]
		"numSubAlbums": <>,
		"numPhotos": <>,
		"albumREC_ID" : ""
	},
	...
	],
	"photos": [
	{
		"photoLocation" : "",
		"photoCaption" : "",
		"photoREC_ID": ""
	},
	...
	],
	"albumREC_ID" : ""
}

Errors:

Code	Message
7001	Album corresponding to the albumREC_ID does not exist.

8. Bell Schedules

List of bell schedules for the school.

Request

URL:
/m/api/bell_schedules/list.jsp

Request Parameters:

bsREC_ID

Unique bsREC_ID of the album. Leave it blank to get all bell schedules for the school. When getting a list of all bell schedules, the order matters.

Response

Response Parameters:

title	Title of the bell schedules module. This is not the title of any individual schedule but the preferred name for the module for the school.
description	Description of the module. Often this is notes about when a schedule is active or not active (optional)
schedules	Array of individual bell schedule info hashes.
schedules[].title	Title of the bell schedule
schedules[].description	Description of the bell schedule (optional)
schedules[].items[]	List of individual items in the bell schedule. Order of this matters.
schedules[].items[].duration	Duration in minutes (optional)
schedules[].items[].start	Start time of this item. In 24 hour hh:mm:ss format. (optional)
schedules[].items[].end	End time of this item. In 24 hour hh:mm:ss format. (optional)
schedules[].items[].description	Description of this item
schedules[].bsREC_ID	Unique REC_ID for this bell schedule.

Response Structure:

{
	"title" : "",
	"description" : "",
	"schedules": [
	{
		"title": "",
		"description": "",
		"items": [
			"duration": "",
			"start": "",
			"end": "",
			"description": ""
		],
		"bsREC_ID" : ""
	},
	...
	]
}

Errors:

Code	Message
8001	Bell Schedule corresponding to the bsREC_ID does not exist, if one was provided.

9. Spotlight

By default get list of entries in a specific spotlight category belonging to the school. You can also get list of entries in a specific category belonging to a department or a course by providing a department REC_ID or a course REC_ID in the request parameters.

Request

URL:
/m/api/spotlight/list.jsp

Request Parameters:

categoryREC_ID	Unique categoryREC_ID of the spotlight category
y	Year for which to get the spotlight items within the category. (optional)
m	Month for which to get the spotlight items within the category. (optional)
d	Day for which to get the spotlight items within the category. (optional)
uREC_ID	Unique REC_ID of the Department. (optional)
courseREC_ID	Unique REC_ID of the Course. (optional)

Response

Response Parameters:

title	Title of the spotlight category
type	Type of the spotlight category. Values are: Daily Weekly Monthly Yearly Indefinite
description	Description of the spotlight category (optional)
spotlight_items	Array of item info hashes for the category
spotlight_items[].date	Human readable date appropriate for the type of the category. (optional: not present for indefinite category spotlight) Daily: MMMM dd, yyyy Weekly: MMMM dd, yyyy - MMMM dd, yyyy Monthly: MMMM yyyy Yearly: yyyy
spotlight_items[].items	Array of items in the specific date for the category.
spotlight_items[].items[].name	Name of the person
spotlight_items[].items[].image	Image for the person. 192px X 192px max dimensions.
spotlight_items[].items[].imagesInfo	List of hash of image information in the files.path directory. (optional)
spotlight_items[].items[].imagesInfo.path	Relative path of the image (optional)
spotlight_items[].items[].imagesInfo.width	Width of the image (optional)
spotlight_items[].items[].imagesInfo.height	Height of the image (optional)
spotlight_items[].items[].imagesInfo.modified	Modified timestamp of the image (optional)
spotlight_items[].items[].imagesInfo.size	File size on disk of the image (optional)
spotlight_items[].items[].description	Description for the entry (optional)
spotlight_items[].items[].personREC_ID	Unique REC_ID for this person entry.
categoryREC_ID	Unique REC_ID for this category.

Response Structure:

{
	"title" : "",
	"description" : "",
	"spotlight_items": [
	{
		"date": "",
		"items": [
			"name": "",
			"image": "",
			"imagesInfo": {
				"path": "",
				"width": "",
				"height": "",
				"modified": "",
				"size": ""
			},
			"description": "",
			"personREC_ID": ""
		]
	},
	...
	],
	"categoryREC_ID" : ""
}

Errors:

Code	Message
9001	Spotlight category corresponding to the categoryREC_ID does not exist.

Notes on pagination:
For all categories of type that is not Indefinite, the result contains upto three entries for the range. For yearly, for example, the spotlight items for the last three recent years. The pagination is obtained by making the same call with y,m,d obtained from the last result of the last response (similar to events). For any website, you can go to /apps/spotlight_persons/categories.jsp to obtain categoryREC_ID information and testing.

10. Departments List

Departments are organized into department types in our system. There are six standard types of departments.

* Academic Departments: Identified by the type 'tde'
These departments can have staff members assigned to them, classes assigned to them and have other modules, custom JSP pages.
Educational Support Departments: Identified by the type 'esd'
These departments can have staff members assigned to them, have other modules, custom JSP pages but no classes.
Athletic Departments: Identified by the type 'ath'
These departments can have staff members assigned to them, have other modules, custom JSP pages but no classes.
Clubs and Activities Departments: Identified by the type 'clu'
These departments can have staff members assigned to them, have other modules, custom JSP pages but no classes.
* Extra Sections: Identified by the type 'sec'
These departments are basically for organization purposes and a list of these modules doesn't make sense. They cannot have staff members assigned to them or classes but can have other modules, custom JSP pages.
Maintenance Departments: Identified by the type 'mde'
These departments can have staff members assigned to them, have other modules, custom JSP pages but no classes.

The name of the type of deparment can be modified by the school. For example, the school can call their 'Athletic Departments' type 'Athletic Clubs'.

Request

URL:
/m/api/departments/list.jsp

Request Parameters:

type	List of comma separated department types to show. When this parameter is empty, all types except 'sec' will be shown. To get 'sec' type (which there is really no reason to ever do), you should make a call with explicit 'sec' type specified. (optional)

Response

Response Parameters:

title	Title of the deparment type
type	Type identifier of the deparment.
departments	Array of info hashes for each individual deparment in the department type.
departments[].name	Name of the department
departments[].numStaff	Number of staff members assigned to this deparment (optional: depends on whether the school wants to show this info and if it is appropriate for the type).
departments[].numClasses	Number of active classes in this deparment (optional: depends on whether the school wants to show this info and if it is appropriate for the type).
departments[].numPages	Number of pages in this deparment.
departments[].REC_ID	Unique REC_ID for this department.

Response Structure:

[
{
	"title" : "",
	"type" : "",
	"departments": [
	{
		"name": "",
		"numStaff": <>,
		"numClasses": <>,
		"numPages": <>,
		"REC_ID": ""
	},
	...
	]
},
...
]

Errors:

Code	Message
10001	Invalid type of department specified in non-empty type parameter.

11. Pages List

Individual departments and staff members have a combinations of Rich text pages and modules as part of their content.

The module type of each item in the response must be used to make the decision of whether to show the web view or the native module. For natively implemented modules, all the existing api calls are applicable except with the parameter 'uREC_ID' and 'type' appended. For modules that are not natively available and for rich text pages, the url provided must be used to render the web view.

Request

URL:
/m/api/pages/list.jsp

Request Parameters:

type	Identifier the type. 'u' for user and 'd' for department.
uREC_ID	Unique REC_ID of the department in case of type 'd' or of staff member in case of type 'u'.

Response

Response Parameters:

module	The type of the item. Possible values are: page calendar classes (department only) staff (department only) album video links spotlight emaillists contact (staff only, depending on privacy settings)
title	The label to use to display the item
REC_ID (applicable only for type 'page' and type 'spotlight')	If type is 'page' , then it refers to the unique REC_ID of the page. For rich text pages, this would be the page REC_ID. If type is 'spotlight', then it refers to the CategoryREC_ID.
url	The URL to be used with the web view for rich text pages and for modules that are not implemented as of yet.

Response Structure:

[
{
	"module" : "",
	"title" : "",
	"REC_ID": "",
	"url": ""
},
...
]

Errors:

Code	Message
11001	Invalid type specified.
11002	Department does not exist.
11003	Staff member does not exist.

12.1. Classes List

A class in our system can be part of zero, one or more departments. A class can also belong to one or more staff members. And, a class can also have a limited set of modules as part of the class's content. By default it gives classes belonging to the school. You can get classes belonging to a department or a user by providing uREC_ID and type in the request parameters.

Similar to departments, the module type of each item in the response must be used to make the decision of whether to show the web view or the native module. For natively implemented modules, all the existing api calls are applicable except with the parameter 'classREC_ID'. For modules that are not natively available, the url provided must be used to render the web view.

Request

URL:
/m/api/classes/list.jsp

Request Parameters:

type	Identifier the type. 'u' for user and 'd' for department(optional).
uREC_ID	Unique REC_ID of the department in case of type 'd' or of staff member in case of type 'u' (optional).

Response

Response Parameters:

name	Name of the class
code	School assigned code for the class. (Optional)
location	Location information for the class. (Optional)
description	Description of the class. (Optional)
url	School assgined URL for the class. This is NOT the web view url. (Optional)
numAssignments	Number of currently active assignments for the class.
files	Hash for attachments to the class item. (optional: present only if there are files or images)
files.images	List of image filenames in the files.path directory. (optional)
files.imagesInfo	List of hash of image information in the files.path directory. (optional)
files.imagesInfo[].path	Relative path of the image (optional)
files.imagesInfo[].width	Width of the image (optional)
files.imagesInfo[].height	Height of the image (optional)
files.imagesInfo[].modified	Modified timestamp of the image (optional)
files.imagesInfo[].size	File size on disk of the image (optional)
files.other	List of non-image filenames in the files.path directory (optional)
files.path	Relative URL to the directory path containing attachments to this class.
departments	Hash of department info lists (This is only minimal information about the dept.).
departments[].name	Name of the department.
departments[].REC_ID	Unique REC_ID of the department.
staff	Hash of staff info lists (This is only minimal information about the staff member.).
staff[].name	Name of the staff member.
staff[].REC_ID	Unique REC_ID of the staff member.
items	Hash for module info for the content of the class.
items[].module	The type of the item. Possible values are: homework links album calendar spotlight
items[].title	The label to use to display the item
items[].url	The URL to be used with the web view for modules that are not implemented natively as of yet.
items[].courseREC_ID	courseREC_ID for module values of links, album, spotlight.
items[].classREC_ID	classREC_ID for module values of calendar, spotlight.
items[].categoryREC_ID	categoryREC_ID for module value of spotlight.
items[].numAlbums	Number of albums for module value of album.
subscribed	Boolean indicating whether the currently logged in user is subscribed to the class. (Only present when a user is authenticated)
hasHTMLContent	Boolean indicating whether the server was able to clean up the HTML without loss of content. If true, item should be shown in web view as opposed to natively.
webViewURL	URL to be used to show the individual item in a web view based on the hasHTMLContent flag
REC_ID	Unique REC_ID of the class.

Response Structure:

[
{
	"name": "",
	"code": "",
	"location": "",
	"description": "",
	"url": "",
	"numAssignments": <>,
	"files": {
		"images" : ["", ...],
		"imagesInfo": [
		 	{
		 		"path": "",
		 		"width": "",
		 		"height": "",
		 		"modified": "",
		 		"size": ""
		 	},
		 	...
		],
		"files" : ["", ...],
		"path" : ""
	},
	"departments": [
	{
		"name": "",
		"REC_ID": ""
	},
	...
	],
	"staff": [
	{
		"name": "",  
		"REC_ID": ""
	},
	...
	],
	"items": [
	{
		"module": "",
		"title": "",
		"courseREC_ID": "",
		"classREC_ID": "",
		"categoryREC_ID": "",
		"numAlbums": <>,
		"url": ""
	},
	...
	],
	"subscribed" : true|false,
	"hasHTMLContent" : true|false,
	"webViewURL" : "",
	"REC_ID": ""
},
...
]

12.2. My Classes

Returns a list of classes to which the user identified by the session ID in the X-Auth header is subscribed to.

Request

URL:
/m/api/classes/my.jsp
/servlet/mobileapi/teacher/class (for teacher login)

Response

Response Parameters:

name/className	Name of the class
code	School assigned code for the class. (Optional)
courseName	course related to class code. (in teacher login)
location	Location information for the class. (Optional)
description	Description of the class. (Optional)
url	School assgined URL for the class. This is NOT the web view url. (Optional)
numAssignments	Number of currently active assignments for the class.
numNewAssignments	Number of currently active new assignments for the class. (in teacher login)
files	Hash for attachments to the class item. (optional: present only if there are files or images)
files.images	List of image filenames in the files.path directory. (optional)
files.imagesInfo	List of hash of image information in the files.path directory. (optional)
files.imagesInfo[].path	Relative path of the image (optional)
files.imagesInfo[].modified	Modified timestamp of the image (optional)
files.imagesInfo[].size	File size on disk of the image (optional)
files.other	List of non-image filenames in the files.path directory (optional)
files.path	Relative URL to the directory path containing attachments to this class.
departments	Hash of department info lists (This is only minimal information about the dept.).
departments[].name	Name of the department.
departments[].REC_ID	Unique REC_ID of the department.
staff	Hash of staff info lists (This is only minimal information about the staff member.).
staff[].name	Name of the staff member.
staff[].REC_ID	Unique REC_ID of the staff member.
items	Hash for module info for the content of the class.
items[].module	The type of the item. Possible values are: homework links album calendar spotlight
items[].title	The label to use to display the item
items[].url	The URL to be used with the web view for modules that are not implemented natively as of yet.
items[].courseREC_ID	courseREC_ID for module values of links, album, spotlight.
items[].classREC_ID	classREC_ID for module values of calendar, spotlight.
items[].categoryREC_ID	categoryREC_ID for module value of spotlight.
items[].numAlbums	Number of albums for module value of album.
subscribed	Boolean indicating whether the currently logged in user is subscribed to the class. (Only present when a user is authenticated)
hasHTMLContent	Boolean indicating whether the server was able to clean up the HTML without loss of content. If true, item should be shown in web view as opposed to natively.
webViewURL	URL to be used to show the individual item in a web view based on the hasHTMLContent flag
REC_ID	Unique REC_ID of the class.

Response Structure:

[
{
	"name": "",
	"code": "",
	"location": "",
	"description": "",
	"url": "",
	"numAssignments": <>,
	"files": {
		"images" : ["", ...],
		"imagesInfo": [
		 	{
		 		"path": "",
		 		"width": "",
		 		"height": "",
		 		"modified": "",
		 		"size": ""
		 	},
		 	...
		],
		"files" : ["", ...],
		"path" : ""
	},
	"departments": [
	{
		"name": "",
		"REC_ID": ""
	},
	...
	],
	"staff": [
	{
		"name": "",  
		"REC_ID": ""
	},
	...
	],
	"items": [
	{
		"module": "",
		"title": "",
		"courseREC_ID": "",
		"classREC_ID": "",
		"categoryREC_ID": "",
		"numAlbums": <>,
		"url": ""
	},
	...
	],
	"subscribed" : true|false,
	"hasHTMLContent" : true|false,
	"webViewURL" : "",
	"REC_ID": ""
},
...
]

Errors:

Code	Message
12001	Invalid credentials.

12.3. Manage My Classes

Manage list of classes that the currnt logged in user identified by the session ID in the X-Auth header is subscribed to. This call allows for simulataneous addition and removal of a list of classes. If the entire batch of specified operations is successful, this call returns a 200 Success response. For error scenarios, refer to the errors section below.

Request

URL:
/m/api/classes/manage.jsp

Request Parameters:

add	Comma separated list of classREC_IDs to subscribe to (optional).
remove	Comma separated list of classREC_IDs to unsubscribe from (optional).

Errors:

Code	Message	Notes
12002	Invalid credentials.	User specified by the X-Auth header is invalid
12003	Please specify classes to add or remove.	'add' or 'remove' are optional, but at least one of them has to be specified.
12004	One or more classREC_IDs is invalid.	One or more classes specified in either the 'add' or 'remove' list is invalid.
12005	One or more classes specified doesn't exist.	One or more classes specified in either the 'add' or 'remove' list doesn't exist.
12006	Could not remove classes.	The 'remove' operation was not successful but the 'add' operation, if specified, was successful.
12007	Could not add classes.	The 'add' operation was not successful but the 'remove' operation, if specified, was successful.
12008	Could not add or remove classes.	Both the 'add' operation and 'remove' operation failed.

12.4. Class Student List

API returns list of students for a class.

Request

URL:
/servlet/mobileapi/teacher/StudentListByClass

Request Parameters:

classREC_ID

unique class id (mandatory)

Response

Response Parameters:

name	Name of user
emailId	Email Id of user
isSubscribed	Boolean for is user subscribed for mail
isVerified	Boolean for is user verified
graduationYear	Graduation complete year for user

Response Structure:

[
  {
    "name": "",
    "emailId": "",
    "isSubscribed": true|false,
    "isVerified": false|false,
    "graduationYear": ""
  },
  .....
]

Errors:

Code	Message
500 (HTTP status)	Internal server error

13.1 Homeworks

Homeworks in our system belong to courses and can be shared between individual sections/periods of classes. Each class can have a separate deadline date, but this should not need any special treatment as this is handled on the server side. This API call will provide the list of homeworks.

Request

URL:
/m/api/homework/list.jsp (used in student login)
/servlet/mobileapi/teacher/homework (used in teacher login)

Request Parameters:

classREC_ID	The Unique class REC_ID to fetch homework for.
start	0-based index to show items from. Default is 0.
showAll	If set to true, will return all assignments instead of just the upcoming due assignments. Default is false.

Response

Response Parameters:

due	The due date of the assignment
last_modified	The last modified date of the assignment
description	The description of assignment
links[]	List of URLs in reference to the homework (optional)
files	Hash for attachments to the assignment. (optional: present only if there are files or images)
files.images	List of image filenames in the files.path directory. (optional)
files.imagesInfo	List of hash of image information in the files.path directory. (optional)
files.imagesInfo[].path	Relative path of the image (optional)
files.imagesInfo[].width	Width of the image (optional)
files.imagesInfo[].height	Height of the image (optional)
files.imagesInfo[].modified	Modified timestamp of the image (optional)
files.imagesInfo[].size	File size on disk of the image (optional)
files.other	List of non-image filenames in the files.path directory (optional)
files.path	Relative URL to the directory path containing attachments to this assignment.
hasHTMLContent	Boolean indicating whether the server was able to clean up the HTML without loss of content. If true, item should be shown in web view as opposed to natively.
webViewURL	URL to be used to show the individual item in a web view based on the hasHTMLContent flag
REC_ID	Unique REC_ID of the assignment.

Response Structure:

[
{
	"due": "",
	"last_modified": "",
	"links": [
		"",
		...
	],
	"files": {
		"images" : ["", ...],
		"imagesInfo": [
		 	{
		 		"path": "",
		 		"width": "",
		 		"height": "",
		 		"modified": "",
		 		"size": ""
		 	},
		 	...
		],
		"files" : ["", ...],
		"path" : ""
	},
	"hasHTMLContent" : true|false,
	"webViewURL" : "",
	"REC_ID": ""
},
...
]

Errors:

Code	Message
13001	Class does not exist.

13.2. Homework Submission List (Student)

API returns list of submissions with details for user identified by the session ID in the X-Auth header. Apart from submission basic details,response contains file attachment info,staff,discussion logs and assignment details as well.

Request

URL:
/servlet/mobileapi/homework/submission

Request Parameters:

vREC_ID	unique submission id (optional) [required if need to fetch particular submission details]
start	0-based index to show items from. Default is 0.

Response

Response Parameters:

vREC_ID	The unique submission id
classREC_ID	The unique class record id
className	Class name
assignmentDueDate	The due date for assignment
submissionDate	The submission date for assignment
description	The description for assignment
submissionText	The text while posting submission
files	Hash for attachments to the assignment. (optional: present only if there are files or images)
files.path	Relative URL to the directory path containing attachments to this assignment.
staff	The details about staff.
staff.REC_ID	The unique record id.
staff.name	Staff name.
staff.link	Staff profile link.
staff.image	Staff profile image path.
staff.thumbnail	Staff thumbnail image path.
staff.isThumbnailRound	Boolean for thumbnail is round(true/false)
discussions	The details of discussion logs
discussions.name	Name of person for this discussion log
discussions.date	The date for this discussion log
discussions.message	The message for this discussion log
discussions.files	Hash for attachments to the assignment. (optional: present only if there are files or images)
discussions.files.images	List of image filenames in the files.path directory. (optional)
discussions.files.imagesInfo	List of hash of image information in the files.path directory. (optional)
discussions.files.imagesInfo[].path	Relative path of the image (optional)
discussions.files.imagesInfo[].width	Width of the image (optional)
discussions.files.imagesInfo[].height	Height of the image (optional)
discussions.files.imagesInfo[].modified	Modified timestamp of the image (optional)
discussions.files.imagesInfo[].size	File size on disk of the image (optional)
discussions.files.path	Relative URL to the directory path containing attachments to this assignment.
homeworkAssignment	The details of homework assignment.
homeworkAssignment.REC_ID	The details of homework assignment.
homeworkAssignment.description	The details of homework assignment.
homeworkAssignment.links	The details of homework assignment.
homeworkAssignment.due	The details of homework assignment.
homeworkAssignment.lastModified	The last modified time for assignment.
homeworkAssignment.webViewUrl	The details of web view url for assignment page.
homeworkAssignment.noOfSubmissions	The number of submission for assignment.
homeworkAssignment.isDigitalSubmitAllowed	Boolean for is digital submission allowed for assignment.
discussionCount	The count of discussion logs.

Response Structure:

[
  {
    "vREC_ID": "",
    "classREC_ID": "",
    "className": "",
    "assignmentDueDate": "",
    "submissionDate": "",
    "description": "",
    "submissionText": "",
    "files": {
      "images": ["",...],
      "imagesInfo": [
        {
          "path": "",
          "width": ,
          "height": ,
          "modified": ,
          "size": 
        }
      ],
      "path": ""
    },
    "staff": [
      {
        "REC_ID": "",
        "name": "",
        "link": "",
        "image": "",
        "thumbnail": "",
        "isThumbnailRound": true|false
      },
      ....
    ],
    "discussions": [
            {
                "name": "",
                "date": "",
                "message": ""
            },
            {
                "name": "",
                "date": "",
                "message": "",
                "files": {
                    "images": [
                        "",...
                    ],
                    "imagesInfo": [
                        {
                            "path": "",
                            "width": ,
                            "height": ,
                            "modified": ,
                            "size": 
                        }
                    ],
                    "path": ""
                }
            },
            ....
    ],
    "homeworkAssignment": {
      "REC_ID": "",
      "description": "",
      "links": ["",""],
      "due": "",
      "lastModified": "",
      "webViewURL": "",
      "noOfSubmissions": "",
      "isDigitalSubmitAllowed": true|false,
      "files": {
        "files": ["",...],
        "images": ["",...],
        "imagesInfo": [
          {
            "path": "",
            "width": ,
            "height": ,
            "modified": ,
            "size": 
          }
        ],
        "path": ""
      }
    },
    "discussionCount":
  }
]

Errors:

Code	Message
500 (HTTP status)	Internal server error

13.3. Homework Submission List (Teacher)

API returns list of submissions with details for a particular homework for teacher. Response also contains detail of user submitting assignment.

Request

URL:
/servlet/mobileapi/teacher/submissions

Request Parameters:

assignmentREC_ID

unique assignment id to fetch discussion for (mandatory)

Response

Response Parameters:

vREC_ID	The unique generated submission id
classREC_ID	The unique class REC_ID
submissionDate	The submission date of homework
submissionText	The submission text with homework submission
submissionStatus	The submission status
assignmentREC_ID	The unique assignment REC_ID
user	The details about user.
user.REC_ID	The unique record id for user.
user.fname	First name for user.
user.lname	Last name for user.
files	Hash for attachments to the assignment. (optional: present only if there are files or images)
files.path	Relative URL to the directory path containing attachments to this assignment.
discussionCount	The number of discussion logs count over this submission

Response Structure:

[
  {
    "vREC_ID": "",
    "classREC_ID": "",
    "submissionDate": "",
    "submissionText": "",
    "submissionStatus": "",
    "assignmentREC_ID": "",
    "user": {
      "REC_ID": "",
      "fName": "",
      "lName": ""
    },
    "files": {
      "files": [
        "",...
      ],
      "path": ""
    },
    "discussionCount": 3
  },
 ......
]

Errors:

Code	Message
500 (HTTP status)	Internal server error

13.4. Homework Submission Post

API is used to post homework submission by student.

Request [POST]

URL:
/servlet/mobileapi/homework/submission

Form Parameters:

classREC_ID	unique class id (mandatory)
assignmentREC_ID	unique assignment id (mandatory)
vText	homework description (optional/mandatory) [based on isUploadOptional property in verify.jsp API]
file	attachments(optional/mandatory) [based on isUploadOptional property in verify.jsp API]

Response

Response Parameters:

vREC_ID

The unique generated vault id for submission

Response Structure:

{"success":{"vREC_ID":"2"}}

Errors:

Code	Message
13005	Submission for past date is not allowed
13003	No attachment(s) or message found
13004	No attachment(s) found
500 (HTTP status)	Internal server error

13.5. Homework Submission Delete

API is used to delete homework submission by student.

Request [DELETE]

URL:
/servlet/mobileapi/homework/submission

Request Parameters:

vREC_ID

unique submission id (mandatory)

Errors:

Code	Message
500 (HTTP status)	Internal server error

13.6. Homework Submit Message

API is used to submit message over homework submission by student/teacher.

Request [POST]

URL:
/servlet/mobileapi/homework/discussion

Form Parameters:

uREC_ID	unique user id (student id) related to a assignment (Only pass when message posted by teacher)
vREC_ID	unique submission id
dlText	text to be posted
file	attached file(optional)

Errors:

Code	Message
13007	No comment found
13009	No submission found for vREC_ID
500 (HTTP status)	Internal server error

13.7. Homework Submission Review

API is used to review homework submission by teacher.

Request [PUT]

URL:
/servlet/mobileapi/teacher/submissions

Request Parameters:

vREC_ID	unique submission id (mandatory)
uREC_ID	unique user REC_ID (mandatory)
vStatus	submission status (0,1,2)(mandatory)

Errors:

Code	Message
13012	No submission found for vREC_ID
500 (HTTP status)	Internal server error

13.8. Add Homework

API is used to create homework by teacher.

Request [POST]

URL:
/servlet/mobileapi/teacher/homework

Form Parameters:

classDateArray	class id:due date (comma separated multiple values in this format) (mandatory)
hwDesc	homework description (mandatory)
hwLink1	any link (optional)
hwLink2	any link (optional)
canSubmitHomework	allow(1)/do not allow(0) digital homework submissions. (mandatory)
file	attachements(optional)

Response

Response Parameters:

assignmentREC_ID

The unique generated assignmnet REC_ID

Response Structure:

{"success":{"assignmentREC_ID":"2"}}

Errors:

Code	Message
500 (HTTP status)	Internal server error

13.9. Homework Discussion Log (Teacher Login)

API returns all discussion log details over a particular assignment submission by a student.

Request

URL:
/servlet/mobileapi/teacher/submissions

Request Parameters:

uREC_ID	unique user id (student id who submitted this assignment) (mandatory)
classREC_ID	unique class id to fetch discussion for (mandatory)
assignmentREC_ID	unique assignment id to fetch discussion for (mandatory)

Response

Response Parameters:

name	The name of person in this discussion log.
date	The date for this discussion log.
message	The message in this discussion log.
files	Hash for attachments to the assignment. (optional: present only if there are files or images)
files.images	List of image filenames in the files.path directory. (optional)
files.imagesInfo	List of hash of image information in the files.path directory. (optional)
files.imagesInfo[].path	Relative path of the image (optional)
files.imagesInfo[].width	Width of the image (optional)
files.imagesInfo[].height	Height of the image (optional)
files.imagesInfo[].modified	Modified timestamp of the image (optional)
files.imagesInfo[].size	File size on disk of the image (optional)
files.path	Relative URL to the directory path containing attachments to this assignment.

Response Structure:

[
  {
    "name": "",
    "date": "",
    "message": ""
    "files": {
      "images": [
                    "",...
                    ],
                    "imagesInfo": [
                        {
                            "path": "",
                            "width": ,
                            "height": ,
                            "modified": ,
                            "size": 
                        }
                    ],
            "files": [
                ""
            ],
            "path": ""
  },
  .....
]

Errors:

Code	Message
500 (HTTP status)	Internal server error

14.1. Link Categories

Links in our system are organized into categories and each category can have links. This call will provide with a list of categories. By default, it gives the categories belonging to the school. We can also get categories specific to a department or a user or a course by providing the appropriate sREC_ID in the request parameters. The labels in this result can be used to then get a list of links using 14.2

Request

URL:
/m/api/links/categories.jsp

Request Parameters:

sREC_ID

For department, prepend unique department REC_ID by 'd'.
For user, prepend unique user REC_ID by 'u'.
For course, prepend unique course REC_ID by 'c'.
(optional)

Response

Response Structure:

[
	"label",
	...
]

14.2. Link List

Request

URL:
/m/api/links/list.jsp

Request Parameters:

linkLabel	The label to get the links for.
start	0-based index to show items from within the category. Default is 0.
show	No of items to show from within the category. Default is 10.
sREC_ID	For department, prepend unique department REC_ID by 'd'. For user, prepend unique user REC_ID by 'u'. For course, prepend unique course REC_ID by 'c'. (optional)

Response

Response Parameters:

title	Title of the link
url	Destination URL of the link entry
description	Description of the link (optional).
params	Params of the link (optional).
REC_ID	Unique REC_ID of the link.

Response Structure:

[
{
	"title": "",
	"url": "",
	"description": "",
	"params": "",
	"REC_ID": ""
},
...
]

Errors:

Code	Message
14001	The category corresponding to the linkLabel does not exist.

15.1. Staff List

Request

URL:
/m/api/staff/list.jsp

Request Parameters:

staffCatREC_ID	REC_IDs of staff categories separated by semicolon (optional).
uREC_ID	Unique REC_ID of the department (optional).
excludePlaceholders	If set to true, resopnse will not include thumbnail or image parameters for records that don't have an uploaded image. If set to false, will include placeholder images. Default is false (optional).

Response

Response Parameters:

link	Destination URL for the staffCatREC_ID or the department.
title	Staff category or department name.
items	An array of staff members.
items[].link	Destination URL for the staff.
items[].title	Proper salutation of the staff.
items[].position	Position of the staff (optional).
items[].isThumbnailRound	If the thumbnail of the profile picture is round then true otherwise false.
items[].thumbnail	Location of the thumbnail (Optional based on excludePlaceholders and thumbnail availability)
items[].image	Location of the full image (Optional based on excludePlaceholders and image availability)
items[].email	Email of the staff (Optional based on the school's privacy settings)
items[].REC_ID	Unique REC_ID of the staff.

Response Structure:

[
{
	"link": "",
	"title": "",
	"items": [
			{
				"link" : "",
				"title" : "",
				"position" : "",
				"isThumbnailRound" : "",
				"thumbnail" : "",
				"image" : "",
				"email" : "",
				"REC_ID" : ""
			},
			...
	]
},
...
]

15.2. Staff contact

Request

Method:
POST

URL:
/m/api/staff/contact.jsp

Request Parameters:

staffREC_ID	Unique REC_ID of the staff member
name	Name of the person sending the email to the staff member
email	Email address of the person sending the email to the staff member
subject	Subject of the email
message	Message of the email

Response

Response Parameters:
If successful, the body of this request will be empty and the response code will be a 200.

Errors:

Code	Message
15001	One or more fields empty.
15002	One or more fields did not pass our abuse filters.
15003	Staff member not found.
15004	Staff member does not have associated email.
15005	Mail could not be sent: {ERROR_MESSAGE_NOT_TO_BE_SHOWN_TO_THE_USER}.

16. Video List

Request

URL:
/m/api/video/list.jsp

Request Parameters:

start	0-based index to show items from. Default is 0.
orderby	Possible values: newest\|oldest\|popular\|relevance\|custom. Default is custom. Only valid when categoryREC_ID and userREC_ID not specified. (Optional)
q	Keyword to search title and description. Only valid when categoryREC_ID and userREC_ID not specified. (Optional)
categoryREC_ID	Unique department REC_ID. In videos, categories are school's departments. (Optional)
userREC_ID	Unique REC_ID of user. (Optional)

Response

Response Parameters:

videoLink	URL of the mp4 video.
title	Title of the video.
date	Uploaded date of the video.
duration	Duration of the video in string format.
thumbnail	URL of cover/thumbnail for the video.
featured	Boolean representing whether the video is a featured video or not.
description	Description of the video.
by	Info hash of the user who uploaded the video. (Optional)
by.name	Name of the user who uploaded the video.
by.userREC_ID	Unique REC_ID of the user who uploaded the video.
categories	Hash of info of all categories to which the video belongs.
categories[].name	Name of the category.
categories[].categoryREC_ID	Unique REC_ID of the category/department.

Response Structure:

[
{
	"videoLink": "",
	"title": "",
	"date": "",
	"duration": "",
	"thumbnail": "",
	"featured": true|false,
	"description": "",
	"by": {
		"name": "",
		"userREC_ID": ""
	}, 
	"categories": [
		{
			"name": "",
			"categoryREC_ID": ""
		},
		...
	]
},
...
]

18.1 User Login/Info

This endpoint serves two purposes:
- Establishing a new session for a user, when username and password are provided as Basic Authentication in X-Auth header (1.1.3)
- Providing information about an authenticated user identified by a valid session TOKEN in X-Auth header.

Request

URL:
/m/api/users/login.jsp

Response

Response Parameters:

username	Username of the authenticated user.
title	Title of the authenticated user. (Optional)
fName	First name of the authenticated user.
mName	Middle name of the authenticated user. (Optional)
lName	Last name of the authenticated user.
tel	Phone number of the authenticated user. (Optional)
email	Email of the authenticated user.
activationPendingEmail	Email address that is pending activation (after an update to the email address). (optional)
isStudent	Set to true if the user is a student
studentGradYear	Graduation year of the student. (Optional + if isStudent is true)
studentID	Student ID of the authenticated user. (Optional + if isStudent is true)
verificationCode	Verification code, if the unverified student. (Optional)
isParent	Set to true if the user is a parent
childGradYear	Graduation year of the parent's child. (Optional + if isParent is true)
isAlumnus	Set to true if the user is an alumnus
alumnusGradYear	Graduation year of the Alumnus. (Optional + if isAlumnus is true)
isOther	Set to true if the user belongs to Other Individuals community
REC_ID	Unique REC_ID of the authenticated user.

Response Structure:

{
	"username" : "",
	"title" : "",
	"fName" : "",
	"mName" : "",
	"lName" : "",
	"tel" : "",
	"email" : "",
	"activationPendingEmail" : "",
	"isStudent" : true|false,
	"studentGradYear" : "",
	"studentID" : "",
	"verificationCode" : "",
	"isParent" : true|false,
	"childGradYear" : "",
	"isAlumnus" : true|false,
	"alumnusGradYear" : "",
	"isOther" : true|false,
	"REC_ID" : ""
}

Errors:

Code	Message
18001	Invalid credentials.

18.2 User logout

End the validity of a user TOKEN provided in the X-Auth header. If successful, returns an empty 200 success response.(Required authentication.)

Request

URL:
/m/api/users/logout.jsp

Errors:

Code	Message
18002	No user to logout.

18.3 Forgot Password

Invokes the forgot password process. The process starts by specifying the email (username) to this endpoint. The API checks for a valid existing user and if one exists, sends an email containing a link to setup a new password.

If the forgot password flow was invoked successfully, the request returns with a 200 status and blank response body.

Request

URL:
/m/api/users/forgot_password.jsp

Request Parameters:

Email address to invoke forgot password flow

Errors:

Code	Message
18003	Invalid Email.
18004	Invalid user.

18.4 User Signup

If creation of a user is successful, returns an empty 200 success response. For possible error cases and validation requirements, refer to the errors section below.

Request

URL:
/m/api/users/signup.jsp

Request Parameters:

title	Title/Salutation for the user (optional).
fName	First name of the user
mName	Middle name of the user (optional)
lName	Last name of the user
tel	Telephone number of the user (optional)
email	Email address of the user. This will also be the username that will be used for login.
password	Password of the user
isStudent	Set to true if the user account belongs to a student. (optional)
studentGradYear	Graduation year of student (required if isStudent is set to true)
studentID	Student ID of the user (optional)
isParent	Set to true if the user account belongs to a parent. (optional)
childGradYear	Graduation year of child of the parent (required if isParent is set to true)
isAlumnus	Set to true if the user account belongs to an alumnus. (optional)
alumnusGradYear	Graduation year of Alumnus (required if isAlumnus is set to true)
isOther	Set to true if the user account belongs to 'Other users' of the schools. (optional)

Errors:

Code	Message	Notes
18005	One or more required fields missing.	This includes conditionally required fields based on optional flags
18006	Registration type(s) not allowed.	Schools don't always allow all user account types. The verify call should provide these flags. This error will be returned if one of the flags is violated (or) Student accounts cannot also be Alumnus or Parent. If isStudent is set along with isParent or isAlumus.
18007	Invalid graduation year.	If one of the graduation years violates these rules: - studentGradYear and childGradYear must be at least: * the current year if the month is <July * next year if month >= July = alumnusGradYear cannot be greater than current year.
18008	Invalid email.	Email address is invalid
18009	User already exists.	An activated current user account with the email already exists
18010	Could not create new user.	---
18012	Please signout before attempting sign up.	---

Notes:
Multiple attempts to signup with a specific email would go through successfully, until one of the attempts is succesfully activated via the email. Activating an account with multiple signup attempts clears the pending attempts.

18.5 User Details Update

If updating details of a user is successful, returns an empty 200 success response. For possible error cases and validation requirements, refer to the errors section below.

This request requires that a user be logged in by a valid X-Auth session. With the exception of email and password, all changes are updated immediately.

- When the 'email' is changed, the request needs to provide the 'oldPassword' property in the request. If the request is successful, the existing credentials will still be valid and an activation email is sent to the new email provided. Upon activation, the email is updated in the database and ALL sessions invalidated.
- When the 'password' is changed, the request needs to provide the 'oldPassword' property in the request. If the request is successful, the password will be updated and all sessions EXCEPT the current session will be invalidated.

Request

URL:
/m/api/users/update.jsp

Request Parameters:

title	Title/Salutation for the user (optional).
fName	First name of the user
mName	Middle name of the user (optional)
lName	Last name of the user
tel	Telephone number of the user (optional)
email	Email address of the user. This will also be the username that will be used for login. If the email address is changed, the 'oldPassword' field must be set after prompting the user for it.
password (optional)	If present, this should be the new password and the 'oldPassword' field must be set after prompting the user for it.
oldPassword (optional)	If the email is changed or the password updated, the current valid passsword must be set as oldPassword after prompting the user.
isStudent	Set to true if the user account belongs to a student. (optional)
studentGradYear	Graduation year of student (required if isStudent is set to true)
studentID	Student ID of the user (optional)
isParent	Set to true if the user account belongs to a parent. (optional)
childGradYear	Graduation year of child of the parent (required if isParent is set to true)
isAlumnus	Set to true if the user account belongs to an alumnus. (optional)
alumnusGradYear	Graduation year of Alumnus (required if isAlumnus is set to true)
isOther	Set to true if the user account belongs to 'Other users' of the schools. (optional)

Errors:

Code	Message	Notes
18005	One or more required fields missing.	This includes conditionally required fields based on optional flags
18006	Registration type(s) not allowed.	Schools don't always allow all user account types. The verify call should provide these flags. This error will be returned if one of the flags is violated (or) Student accounts cannot also be Alumnus or Parent. If isStudent is set along with isParent or isAlumus.
18007	Invalid graduation year.	If one of the graduation years violates these rules: - studentGradYear and childGradYear must be at least: * the current year if the month is <July * next year if month >= July = alumnusGradYear cannot be greater than current year.
18008	Invalid email.	Email address is invalid
18009	User already exists.	An activated current user account with the email already exists
18010	Could not create new user.	---
18011	Invalid credentials.	---

18.6 User Change Password

If updating password of a user is successful, returns an empty 200 success response. For possible error cases and validation requirements, refer to the errors section below.

This request requires that a user be logged in by a valid X-Auth session. With the exception of email and password, all changes are updated immediately.

If the request is successful, the password will be updated and all sessions EXCEPT the current session will be invalidated.

Request

URL:
/m/api/users/change_password.jsp

Request Parameters:

password	This should be the new password for the user
oldPassword	This should be the current valid password for the user

Errors:

Code	Message	Notes
18005	One or more required fields missing.	This includes conditionally required fields based on optional flags
18011	Invalid credentials.	---
18013	Invalid Password.	If old password is wrong.
18014	Password length is too short.	If new password length is less than 6 characters.
18015	User does not exist.	If we try to change the password of a user which does not exist.
18016	Could not change the password.	---

18.7 User Delete Account

If deleting account of a user is successful, returns an empty 200 success response. For possible error cases and validation requirements, refer to the errors section below.

This request requires that a user be logged in by a valid X-Auth session. With the exception of email and password.

Request

Method:
POST

URL:
/servlet/mobileapi/user

Errors:

Code	Message	Notes
18011	Invalid credentials.	---
18015	User does not exist. REC_ID: <user-rec-id>	If we try to delete the user which does not exist.
18017	Not a web user. REC_ID: <user-rec-id>	If the user is not a web user or more privileged user
18018	Unknown user type. REC_ID: <user-rec-id>	If the user type is not determined.
18019	Error occurred. Please try again later. REC_ID: <user-rec-id>	If any error occured while deleting the user account.

18.8 Verify Student

API is used to verify student.

Request

URL:
/servlet/mobileapi/teacher/verifyAccount

Request Parameters:

uREC_ID	unique user id (mandatory)
vCode	verification code (mandatory)

Errors:

Code	Message
19014	Invalid verification code
19013	Invalid user
500 (HTTP status)	Internal server error

19 Food Menu

Get a list of monthly food menu data.

Request

URL:
/servlet/mobileapi/foodmenu

Request Parameters:

y	Yearin yyyy format. Int type, Default is current year. (Optional)
m	Month in mm format. Int type, Default is current month. (Optional)
w	Show weekend. Boolan type. Default is false. (Optional)
showEmptyDate	Provide true if you want to show the date which has empty data. Boolean type, Default is false. (Optional)

Response

Response Structure:

[
    {
        "year": "",
        "month": "",
        "date": "",
        "dayOfWeek": "",
        "maxDate": "",
        "isToday": true|false,
        "foodTypes": [
            {
                "type": "",
                "value": ""
            },
            {
                "type": "",
                "value": ""
            },
            {
                "type": "afternoonSnack",
                "value": "Fruit or Juice\\nMilk"
            },
            {
                "type": "",
                "value": ""
            }
        ]
    },
    ...
]

Errors:

500 (HTTP status)

Internal server error

20 QR Code

Save the record after event QR code is scanned.

Request

Method:
POST

URL:
/servlet/mobileapi/qrcode

Request Parameters(JSON):

{
"data" : "<base 64 encoded string of below request json structure>"
}
{
"staffREC_ID": "",
"staffFirstName": "",
"staffLastName": "",
"staffEmail": "",
"qrcodeRecords": [
	{
		"studentId": "",
		"studentName": "",
		"scannedDateTime": "yyyy-MM-dd HH:mm:ss",
		"qrcodeCreationDateTime": "yyyy-MM-dd HH:mm:ss",
		"attendeeREC_ID": "",
		"attendeeFirstName": "",
		"attendeeLastName": "",
		"attendeeEmail": "",
		"deviceType": "",
		"deviceModel": "",
		"osVersion": "",
		"appVersion": ""
	},
	.....
]
}

Response

Response Structure:

[
{
	"studentId": "",
	"status": true|false
},
{
	"studentId": "",
	"status": true|false
}
]

Errors:

20001	One or more required parameters are missing.
20002	Error while saving the data.

21 Quick Poll

submit vote for the poll

Request

Method:
POST

URL:
/servlet/mobileapi/poll

Request Parameters:

pollResponseREC_ID

unique poll response REC_ID (mandatory)

Response

Response Structure: Success response will be all the poll options with updated vote number and percentage.

[
    {
        "pollResponseREC_ID": "",
        "pollResponse": "",
        "pollResponseCounter": "",
        "pollResponseCounterPercentage": ""
    },
    {
        "pollResponseREC_ID": "",
        "pollResponse": "",
        "pollResponseCounter": "",
        "pollResponseCounterPercentage": ""
    }
]

Errors:

21001	Invalid pollResponseREC_ID.
21002	Invalid Poll Response:
21003	Error Occurred while submitting the vote.

Educational Networks Mobile API

0. Notes

1.1. Security

Authorization Digest

1.2. Error Handling

Sample Response

Service Temporarily Unavailable

Response

Sample Response

1.3. API Availability

1.4. Staging & Troubleshooting

2. School Lookup and Info

Request

Response

Sample Response (generic keywords provided)

Sample Response (New version of properties available)

Sample Response

Sample Response

3.0. Push Notification Payload

3.1. Number of new Notifications

3.2. Token Provisioning for Push Notifications

Request

Response

3.3. Notifications List

Request

Response

3.4. Notification Item

Request

Response

4.1. News List

Request

Response

4.2. News Item

Request

Response

5.1. Events List

Request

Response

5.2. Event Item

Request

Response

6.1. Bulletin Board List

Request

Response

6.2. Bulletin Board Item

Request

Response

7. Photo Albums

Request

Response

8. Bell Schedules

Request

Response

9. Spotlight

Request

Response

10. Departments List

Request

Response

11. Pages List

Request

Response

12.1. Classes List

Request

Response

12.2. My Classes

Request

Response

12.3. Manage My Classes

Request

12.4. Class Student List

Request

Response

13.1 Homeworks

Request

Response

13.2. Homework Submission List (Student)

Request

Response

13.3. Homework Submission List (Teacher)