Engrade API

Introduction

The EngradePro API allows approved development partners to integrate our leading class management tools with district student information systems and partner services. If you would like connect your software to Engrade, please contact us with a description of your application and goals.

Technical Overview

Engrade offers a REST API allowing qualified apps to send data to our servers via HTTP POST requests and retrieve data in either XML, JSON, or serialized PHP format. This API is in BETA.

Input fields vary depending on the request, but most API requests must have at least 3 fields:
apitask - will determine what data to input or output
apikey - provided by Engrade
ses - will be the session token created by first sending a login request.

Optionally you can specify the format of your output by adding the field api to your request:
api=xml will return XML (default)
api=json will return JSON
api=ser will return serialized PHP

Example Successful Request

***** Request *****
POST /api/ HTTP/1.1
Host: api.engrade.com
Content-length: x

apikey=1234&apitask=login&usr=jondoe&pwd=Password123


***** Response *****
HTTP/1.0 200 OK
Date: Sat, 15 Jan 2000 14:37:12 GMT
Content-Type: text/xml
Content-Length: x

<?xml version="1.0" encoding="utf-8" ?>
<engrade>
<success>true</success>
<values>
<usr>jondoe</usr>
<pwd>Password123</pwd>
<ses>9888304868921308840o4h07chple88d7a863c1n724pfa697emf2bfnof3hd11a</ses>
</values>
<time>1286222925</time>
</engrade>

Example Failed Request

***** Request *****
POST /api/ HTTP/1.1
Host: api.engrade.com
Content-length: x

apikey=1234&apitask=login&usr=jondoe&pwd=WrongPassword


***** Response *****
HTTP/1.0 200 OK
Date: Sat, 15 Jan 2000 14:37:12 GMT
Content-Type: text/xml
Content-Length: x

<?xml version="1.0" encoding="utf-8" ?>
<engrade>
<success>false</success>
<values>
<usr>teacher</usr>
<pwd>WrongPassword</pwd>
</values>
<errors>
<pwd>Invalid password</pwd>
</errors>
<time>1286229374</time>
</engrade>

Login / New Session

In order to use any other API calls, you will first need to make a call to the login in order to create a session token which you will then include in your later calls.

URL: https://api.engrade.com/api/

Input Fields:
apitask = login
apikey = contact us for your API key
usr = the user's Engrade account username
pwd = the user's Engrade account password

Output Fields:
ses - The new session token ID

***** Request *****
POST /api HTTP/1.1
Host: api.engrade.com
Content-length: x

apitask=login&usr=jondoe&pwd=Password123


***** Response *****
HTTP/1.0 200 OK
Date: Sat, 15 Jan 2000 14:37:12 GMT
Content-Type: text/xml
Content-Length: x

<?xml version="1.0" encoding="utf-8" ?>
<engrade>
<success>true</success>
<values>
<usr>jondoe</usr>
<pwd>Password123</pwd>
<ses>9888304868921308840o4h07chple88d7a863c1n724pfa697emf2bfnof3hd11a</ses>
</values>
<time>1286222925</time>
</engrade>

Get or Edit User Info

Get Account Info
URL: https://api.engrade.com/api/

Input fields:
apitask - profile
apikey - contact us for your API key
ses - The session token ID

Output fields:
uid - Account user ID
usr - Account username
type - 2 for student, 3 for teacher, 4 for admin
status - 2 for active, 0 for blocked
created - Unix timestamp of when account was created
lastlog - Unix timestamp of user's last login
email - Email address
name - Owner's name as it appears in account
pic - 1 if the user has uploaded a profile pic, 0 if he hasn't
mailmail - 1 to receive email notifications of new message or 0 for no emails

***** Request *****
POST /api/ HTTP/1.1
Host: api.engrade.com
Content-length: x


apikey=1234&apitask=profile&ses=123456789


***** Response *****
HTTP/1.0 200 OK
Date: Sat, 15 Jan 2000 14:37:12 GMT
Content-Type: text/xml
Content-Length: x

<?xml version="1.0" encoding="utf-8" ?>
<engrade>
<values>
<uid>1000002975618</uid>
<usr>teacher</usr>
<type>3</type>
<status>2</status>
<created>1078034461</created>
<lastlog>1286222925</lastlog>
<email>holtlabs@gmail.com</email>
<name>Mr. Teacher</name>
<pic>1</pic>
<mailmail>1</mailmail>
</values>
<time>1286227728</time>
</engrade>


Edit Account Info
URL: https://api.engrade.com/api

Input Fields:
apitask = profile
ses = The session token ID
usr = Account username (required)
name = Owner's name as it appears in account (required)
email = Email address (required)
mailmail = Enter 1 to receive email notifications of new message or 0 for no emails (required)
pwd = New account password (or leave leave blank to keep same)
pwd2 = Confirm new account password (or leave blank to keep same)
pwdconf = Current account password (required)

***** Request *****
POST /api HTTP/1.1
Host: api.engrade.com
Content-length: x

apitask=profile&usr=teacher&name=Mr.%20Teacher&email=teacher%40email.com&mailmail=1&pwdconf=Password123&ses=123456789


***** Response *****
HTTP/1.0 200 OK
Date: Sat, 15 Jan 2000 14:37:12 GMT
Content-Type: text/xml
Content-Length: x

<?xml version="1.0" encoding="utf-8" ?>
<engrade>
<success>true</success>
<values>
<usr>teacher</usr>
<name>Mr. Teacher</name>
<email>teacher@email.com</email>
<mailmail>1</mailmail>
<pwdconf>Password123</pwdconf>
</values>
<time>1286227626</time>
</engrade>

Teacher

Get Teacher's Classes
List all of a teacher's classes.

URL: https://api.engrade.com/api/

Input Fields:
apitask = teacher-classes
apikey = contact us for your API key
ses = The session token ID

Response fields
classes = will provide a list of classes in <item> tags

In each <item> tag:
clid = the Engrade class ID of that class (you'll need this to get the class gradebook, etc.)
created = Unix timestamp of the date the class was created
folder = 3 is active, 2 is archived, 1 is trashed
syr = the school year of the class, either 2YYY or 2YYY-2YYY
gp = the 1-9 grading period of the class
name = the name of the class
code = the class code (i.e. BIO101)

***** Request *****
POST /api/ HTTP/1.1
Host: api.engrade.com
Content-length: x


apikey=1234&apitask=teacher-classes&ses=abc1234



***** Response *****
HTTP/1.0 200 OK
Date: Sat, 15 Jan 2000 14:37:12 GMT
Content-Type: text/xml
Content-Length: x

<?xml version="1.0" encoding="utf-8" ?>
<engrade>
<classes>
<item>
<superid>1000002975618</superid>
<subid>5000001800319</subid>
<supertype>teacher</supertype>
<subtype>class</subtype>
<auth>6</auth>
<joined>1286233052</joined>
<role>Teacher</role>
<clid>5000001800319</clid>
<created>1286233052</created>
<folder>2</folder>
<syr>2012</syr>
<gp>1</gp>
<gscale>9</gscale>
<weighted>1</weighted>
<showper>1</showper>
<stusort>2</stusort>
<assnsort>1</assnsort>
<round>1</round>
<stuview>1</stuview>
<stumail>0</stumail>
<teachmail>1</teachmail>
<priteach>1000002975618</priteach>
<name>Art History</name>
<code></code>
</item>
<item>
<superid>1000002975618</superid>
<subid>5000001001388</subid>
<supertype>teacher</supertype>
<subtype>class</subtype>
<auth>6</auth>
<joined>1280670949</joined>
<role>Teacher</role>
<clid>5000001001388</clid>
<created>1232949661</created>
<folder>3</folder>
<syr>2012</syr>
<gp>1</gp>
<gscale>9</gscale>
<weighted>0</weighted>
<showper>1</showper>
<stusort>2</stusort>
<assnsort>3</assnsort>
<round>4</round>
<stuview>1</stuview>
<stumail>0</stumail>
<teachmail>1</teachmail>
<priteach>1000002975618</priteach>
<name>US History</name>
<code>HIST1</code>
</item>
</classes>
<success>true</success>
<time>1289244591</time>

</engrade>


Teacher Create Class
URL: https://api.engrade.com/api/

Required input fields
apitask = class-add
apikey = contact us for your API key
ses = The session token ID
name = Name of the class
syr = School year (2YYY or 2YYY-2YYY)
gp = Grading period (1-9)
gradelevel = 0 for Pre-K/K, 1-12 for 1st through 12th grade, 13 for college, 14 for occupational, 99 for other.
subject = 12 for math, 42 for foreign language, 1 for Language Arts, 5 for science, 99 for other.

Optional input fields
schoolid = the UID of the class's school (teacher must already have joined school)
stuview = 0/1 for allow/block students from viewing grades online
teachmail = 0/1 for allow/block students from messaging teacher
stumail = 0/1 for allow/block students from messaging each other
stusort = How to sort students: 1 as entered, 2 last name, 3 ID number, 4 class percentage

Output fields:
clid - This will be Engrade's unique class ID for this class

Class

Class functions can be called when either logged in as the class's teacher or as an admin at the class's school.

Edit Class Info
URL: https://api.engrade.com/api/

Input Fields:
apitask = class-edit
apikey = your API key
ses = The session token ID
clid = Engrade class ID
name = Class name
syr = School year (2XXX or 2XXX-2XXX)
gp = Grading period (1-9)
priteach = Engrade UID of the primary teacher
stuview = 0/1 for allow/block students from viewing grades online
teachmail = 0/1 for allow/block students from messaging teacher
stumail = 0/1 for allow/block students from messaging each other

Edit Student List
URL: https://api.engrade.com/api/

Input Fields:
apitask = class-students-edit
apikey = your API key
ses = The session token ID
clid = Engrade Class ID
students = A formatted list of class students (see below)

***** Student List Format ******
FirstName LastName IDNumber
Jon Doe 1234
Jane Smith 5678


***** Request *****
POST /api/ HTTP/1.1
Host: api.engrade.com
Content-length: x

apikey=1234&apitask=class-students-edit&clid=20000000001&students=Jon%20Doe%201234%0AJane%20Smith%205678&stusort=1&ses=12345


***** Response *****
HTTP/1.0 200 OK
Date: Sat, 15 Jan 2000 14:37:12 GMT
Content-Type: text/xml
Content-Length: x

<?xml version="1.0" encoding="utf-8" ?>
<engrade>
<success>true</success>
<values>
</values>
<time>1286222925</time>
</engrade>


Add Assignment
URL: https://api.engrade.com/api/

Required Input Fields:
apitask = assignment-add
apikey = Your API key
ses = The session token ID
clid = The Engrade class ID to which you wish to add the assignment
title = The name of the assignment
points = Numeric point value of the assignment (or EC for extra credit)
cat = The assignment category # of the assignment (enter 99 for not graded)

Optional Input Fields:
due_year = Year the assignment is due in format YYYY
due_month = Month the assignment is due in format MM
due_day = Day the assignment is due in format DD
cal = Set to 1 to have the assignment appear on the class calendar
bb = Set to 1 to allow students to comment
body = The description/instructions for the assignment

Enter Assignment Score
URL: https://api.engrade.com/api/

Required Input Fields:
apitask = assignment-score
apikey = Your API key
ses = The session token ID
clid = The Engrade class ID to which you wish to add the assignment
assnid = The assignment's ID number
stuid = The student's student ID
score = The student's score on the assignment

Get Assignment
URL: https://api.engrade.com/api/

Input Fields:
apitask = assignment
apikey = Your API key
ses = The session token ID
clid = Engrade Class ID
assnid = The assignment ID

Response fields (incomplete)
clid - Engrade Class ID
assnid - the unique ID for this assignment
title - the title of the assignment
scores - a list of student assignment scores correlated by stuid.

Delete Assignment
URL: https://api.engrade.com/api/

Input Fields:
apitask = assignment-edit
apikey = Your API key
ses = The session token ID
clid = The Engrade class ID to which you wish to add the assignment
assnid = The assignment's assnid number
delete = Set to 1

Get Gradebook
URL: https://api.engrade.com/api/

Input Fields:
apitask = gradebook
apikey = Your API key
ses = The session token ID
clid = Engrade Class ID

Response fields (incomplete)
clid - Engrade Class ID
cgs - a list of the class's custom grading scale grades
cat - a list of the class's assignment categories
dls - "drop lowest score" for that assignment category
assignments - a list of gradebook assignments
assnid - the unique ID for a given assignment
students - a list of students in the class with grade information
stuid - a unique ID for a given student
scores - a list of student assignment scores correlated by stuid and assnid.

***** Request *****
POST /api/ HTTP/1.1
Host: api.engrade.com
Content-length: x

apikey=1234&apitask=gradebook&clid=5000000001&ses=abc1234


***** Response *****
HTTP/1.0 200 OK
Date: Sat, 15 Jan 2000 14:37:12 GMT
Content-Type: text/xml
Content-Length: x

<?xml version="1.0" encoding="utf-8" ?>
<engrade>

<clid>5000001001388</clid>
<created>1232949661</created>
<folder>3</folder>
<syr>2012</syr>
<gp>1</gp>
<gscale>9</gscale>
<weighted>0</weighted>
<showper>1</showper>
<stusort>2</stusort>
<assnsort>3</assnsort>
<round>4</round>
<stuview>1</stuview>
<stumail>0</stumail>
<teachmail>1</teachmail>
<priteach>1000002975618</priteach>
<name>US History</name>
<code>HIST1</code>


<cgs>
<item>
<num>1</num>
<low>90</low>
<grade>A</grade>
</item>
<item>
<num>2</num>
<low>80</low>
<grade>B</grade>
</item>
<item>
<num>3</num>
<low>70</low>
<grade>C</grade>
</item>
<item>
<num>4</num>
<low>0</low>
<grade>F</grade>
</item>
</cgs>


<cat>
<item>
<num>1</num>
<name>Quizzes</name>
<weight></weight>
<dls>0</dls>
</item>
<item>
<num>2</num>
<name>Tests</name>
<weight></weight>
<dls>0</dls>
</item>
<item>
<num>3</num>
<name>Homework</name>
<weight></weight>
<dls>0</dls>
</item>
</cat>


<assignments>
<item>
<clid>5000001001388</clid>
<assnid>10</assnid>
<created>1288162330</created>
<creator>1000002975618</creator>
<type>1</type>
<cat>3</cat>
<cal>1</cal>
<due>20101026</due>
<points>10</points>
<title>Register on Engrade</title>
<name>Mr. Teacher</name>
<usr>teacher</usr>
<pic>1</pic>
</item>
<item>
<clid>5000001001388</clid>
<assnid>9</assnid>
<created>1287168099</created>
<creator>1000002975618</creator>
<type>1</type>
<cat>1</cat>
<cal>0</cal>
<due>20101015</due>
<points>7</points>
<title>SAT Word List Prep #1</title>
<name>Mr. Teacher</name>
<usr>teacher</usr>
<pic>1</pic>
</item>
<item>
<clid>5000001001388</clid>
<assnid>8</assnid>
<created>1287127871</created>
<creator>1000002975618</creator>
<type>1</type>
<cat>1</cat>
<cal>0</cal>
<due>20101015</due>
<points>4</points>
<title>Cell Quiz</title>
<name>Mr. Teacher</name>
<usr>teacher</usr>
<pic>1</pic>
</item>
<item>
<clid>5000001001388</clid>
<assnid>5</assnid>
<created>1281468397</created>
<creator>1000002975618</creator>
<type>1</type>
<cat>1</cat>
<cal>1</cal>
<due>20100810</due>
<points>50</points>
<title>Founding Fathers Quiz</title>
<name>Mr. Teacher</name>
<usr>teacher</usr>
<pic>1</pic>
</item>
<item>
<clid>5000001001388</clid>
<assnid>4</assnid>
<created>1281050394</created>
<creator>1000002975618</creator>
<type>1</type>
<cat>2</cat>
<cal>1</cal>
<due>20100805</due>
<points>200</points>
<title>Civil War Midterm</title>
<name>Mr. Teacher</name>
<usr>teacher</usr>
<pic>1</pic>
</item>
<item>
<clid>5000001001388</clid>
<assnid>2</assnid>
<created>1280708218</created>
<creator>1000002975618</creator>
<type>1</type>
<cat>3</cat>
<cal>1</cal>
<due>20100816</due>
<points>10</points>
<title>WWII</title>
<name>Mr. Teacher</name>
<usr>teacher</usr>
<pic>1</pic>
</item>
<item>
<clid>5000001001388</clid>
<assnid>1</assnid>
<created>1232949661</created>
<creator>1000002975618</creator>
<type>1</type>
<cat>3</cat>
<cal>1</cal>
<due>20100802</due>
<points>ec</points>
<title>Return Signed Syllabus</title>
<name>Mr. Teacher</name>
<usr>teacher</usr>
<pic>1</pic>
</item>
</assignments>


<students>
<item>
<stuid>17406</stuid>
<num>1</num>
<first>John</first>
<last>Adams</last>
<grade>A</grade>
<percent>96.1</percent>
</item>
<item>
<stuid>460798</stuid>
<num>2</num>
<first>Thomas</first>
<last>Jefferson</last>
<grade>A</grade>
<percent>97.5</percent>
</item>
<item>
<stuid>99010</stuid>
<num>3</num>
<first>Abraham</first>
<last>Lincoln</last>
<grade>B</grade>
<percent>85.4</percent>
</item>
<item>
<stuid>55678</stuid>
<num>4</num>
<first>Franklin</first>
<last>Roosevelt</last>
<grade>A</grade>
<percent>96.3</percent>
</item>
<item>
<stuid>95956</stuid>
<num>5</num>
<first>George</first>
<last>Washington</last>
<grade>A</grade>
<percent>102.5</percent>
</item>
</students>


<scores>
<item>
<assnid>1</assnid>
<stuid>17406</stuid>
<score>5</score>
</item>
<item>
<assnid>1</assnid>
<stuid>460798</stuid>
<score>m</score>
</item>
<item>
<assnid>1</assnid>
<stuid>55678</stuid>
<score>5</score>
</item>
<item>
<assnid>1</assnid>
<stuid>95956</stuid>
<score>10</score>
</item>
<item>
<assnid>1</assnid>
<stuid>99010</stuid>
<score>E</score>
</item>
<item>
<assnid>2</assnid>
<stuid>17406</stuid>
<score>1</score>
</item>
<item>
<assnid>2</assnid>
<stuid>460798</stuid>
<score>10</score>
</item>
<item>
<assnid>2</assnid>
<stuid>55678</stuid>
<score>10</score>
</item>
<item>
<assnid>2</assnid>
<stuid>95956</stuid>
<score>10</score>
</item>
<item>
<assnid>2</assnid>
<stuid>99010</stuid>
<score>10</score>
</item>
<item>
<assnid>4</assnid>
<stuid>17406</stuid>
<score>180</score>
</item>
<item>
<assnid>4</assnid>
<stuid>460798</stuid>
<score>190</score>
</item>
<item>
<assnid>4</assnid>
<stuid>55678</stuid>
<score>E</score>
</item>
<item>
<assnid>4</assnid>
<stuid>95956</stuid>
<score>190</score>
</item>
<item>
<assnid>4</assnid>
<stuid>99010</stuid>
<score>155</score>
</item>
<item>
<assnid>5</assnid>
<stuid>17406</stuid>
<score>50</score>
</item>
<item>
<assnid>5</assnid>
<stuid>460798</stuid>
<score>50</score>
</item>
<item>
<assnid>5</assnid>
<stuid>55678</stuid>
<score>40</score>
</item>
<item>
<assnid>5</assnid>
<stuid>95956</stuid>
<score>49</score>
</item>
<item>
<assnid>5</assnid>
<stuid>99010</stuid>
<score>50</score>
</item>
<item>
<assnid>8</assnid>
<stuid>17406</stuid>
<score>3</score>
</item>
<item>
<assnid>8</assnid>
<stuid>460798</stuid>
<score>2</score>
</item>
<item>
<assnid>8</assnid>
<stuid>55678</stuid>
<score>3</score>
</item>
<item>
<assnid>8</assnid>
<stuid>95956</stuid>
<score>4</score>
</item>
<item>
<assnid>8</assnid>
<stuid>99010</stuid>
<score>5</score>
</item>
<item>
<assnid>9</assnid>
<stuid>17406</stuid>
<score>11</score>
</item>
<item>
<assnid>9</assnid>
<stuid>460798</stuid>
<score>12</score>
</item>
<item>
<assnid>9</assnid>
<stuid>55678</stuid>
<score>10</score>
</item>
<item>
<assnid>9</assnid>
<stuid>95956</stuid>
<score>15</score>
</item>
<item>
<assnid>9</assnid>
<stuid>99010</stuid>
<score>12</score>
</item>
<item>
<assnid>10</assnid>
<stuid>17406</stuid>
<score>20</score>
</item>
<item>
<assnid>10</assnid>
<stuid>460798</stuid>
<score>10</score>
</item>
<item>
<assnid>10</assnid>
<stuid>55678</stuid>
<score>10</score>
</item>
<item>
<assnid>10</assnid>
<stuid>95956</stuid>
<score>10</score>
</item>
<item>
<assnid>10</assnid>
<stuid>99010</stuid>
<score>8</score>
</item>
</scores>

<success>true</success>

<time>1289054470</time>

</engrade>


Get Attendance
Get Attendance by Week
URL: https://api.engrade.com/api/

Input Fields:
apitask = attendance
apikey = Your API key
ses = The session token ID
clid = Engrade Class ID
ymd = the date of the Monday of the given week in the format YYYYMMDD

***** Request *****
POST /api/ HTTP/1.1
Host: api.engrade.com
Content-length: x

apikey=1234&apitask=attendance&clid=5000000001&ymd=20101101&ses=abc1234


***** Response *****
HTTP/1.0 200 OK
Date: Sat, 15 Jan 2000 14:37:12 GMT
Content-Type: text/xml
Content-Length: x

<?xml version="1.0" encoding="utf-8" ?>
<engrade>
<attendance>
<item>
<clid>5000001001388</clid>
<date>20101105</date>
<stuid>17406</stuid>
<mark>p</mark>
</item>
<item>
<clid>5000001001388</clid>
<date>20101105</date>
<stuid>460798</stuid>
<mark>p</mark>
</item>
<item>
<clid>5000001001388</clid>
<date>20101105</date>
<stuid>55678</stuid>
<mark>t</mark>
</item>
<item>
<clid>5000001001388</clid>
<date>20101105</date>
<stuid>95956</stuid>
<mark>p</mark>
</item>
<item>
<clid>5000001001388</clid>
<date>20101105</date>
<stuid>99010</stuid>
<mark>a</mark>
</item>
</attendance>
<success>true</success>
<time>1289055431</time>

</engrade>


Get Attendance Totals
URL: https://api.engrade.com/api

Input Fields:
apitask = attendance-totals
apikey = Your API key
ses = The session token ID
clid = Engrade Class ID

Enter Attendance
URL: https://api.engrade.com/api/

Required Input Fields:
apitask = attendance-mark
apikey = Your API key
ses = The session token ID
clid = The Engrade class ID to which you wish to add the mark
date = The date in form YYYYMMDD
stuid = The student's student ID
mark = The attendance mark to give the student.

Change Class Folder
This will move a class into either the "Active," "Archive," or "Trash" folders.

URL: https://api.engrade.com/api/

Input Fields:
apitask = class-folder
apikey = Your API key
ses = The session token ID
clid = Engrade class ID
folder = 3 for active, 2 for archive, 1 for trash

Email Invite Students
URL: https://api.engrade.com/api/

Input Fields:
apitask = class-students-email
apikey = your API key
ses = The session token ID
clid = Engrade Class ID

For each student that you wish to invite, add a field in the format:

email_STUDENTID = email1,email2

Replace STUDENTID with that student's ID number and enter the email address(es) as a comma-separated list. For example:

email_1234 = johnny@yahoo.com,johnnysmom@gmail.com

Add Class Teacher
URL: https://api.engrade.com/api/

Input Fields:
apitask = class-user-add
apikey = Your API key
ses = The session token ID
clid = Engrade class ID
usr = The Engrade UID or username of a teacher
priteach = Set to 1 to make this user the class's primary teacher.
auth = The user's authorization level (see list below)

auth options:
3 = View only
4 = Limited Edit
5 = Full Edit
6 = Full Moderator

Drop Class Teacher
URL: https://api.engrade.com/api/

Input Fields:
apitask = class-user-edit
apikey = Your API key
ses = The session token ID
clid = Engrade class ID
usr = The Engrade UID or username of a teacher
delete = Set to 1

Get Marking Periods
URL: https://api.engrade.com/api/

Input Fields:
apitask = class-marking-periods
apikey = Your API key
ses = The session token ID
clid = Engrade Class ID

Response fields (incomplete)
P1, P2, P3, P4, P5 - a list of student final scores correlated by stuid.

***** Request *****
POST /api/ HTTP/1.1
Host: api.engrade.com
Content-length: x

apikey=1234&apitask=class-marking-periods&clid=5000000001&ses=abc1234

***** Response *****
HTTP/1.0 200 OK
Date: Sat, 15 Jan 2000 14:37:12 GMT
Content-Type: text/xml
Content-Length: x


<?xml version="1.0" encoding="utf-8" ?>
<engrade>
<P1>
<item>
<stuid>95956</stuid>
<grade>2</grade>
</item>
</P1>
<P2>
<item>
<stuid>17406</stuid>
<grade>3</grade>
</item>
<item>
<stuid>701310</stuid>
<grade>5</grade>
</item>
</P2>
<P3>
<item>
<stuid>17406</stuid>
<grade>1</grade>
</item>
<item>
<stuid>701310</stuid>
<grade>2</grade>
</item>
<item>
<stuid>95956</stuid>
<grade>4</grade>
</item>
</P3>
<P5>
<item>
<stuid>17406</stuid>
<grade>4</grade>
</item>
<item>
<stuid>701310</stuid>
<grade>2</grade>
</item>
<item>
<stuid>95956</stuid>
<grade>3</grade>
</item>
</P5>
<success>true</success>
<time>1312330741</time>
</engrade>


Edit Marking Periods
URL: https://api.engrade.com/api/

Input Fields:
apitask = class-marking-periods-set
apikey = your API key
ses = The session token ID
clid = Engrade class ID
sskey2 = Period Number (0-9) (see Get Marking Periods)
value = Period Name (blank to delete the period and all associated data)

Admin

Admin Signup
URL: https://api.engrade.com/api/

Input Fields:
apitask = admin-signup
apikey = Your API key
usr = Account username, must be a-z and 0-9 only
name = Name of the admin as students will see it
email = Email address of admin
phone = 10-digit phone number of the admin
pwd = Account password
pwd2 = Account password (again)
tos = Set to 1

Note you must choose a username not already taken by another Engrade user. If a username is already taken, the API will return an error.

Get Admin's Schools
List the schools to which an admin belongs.

URL: https://api.engrade.com/api/

Input Fields:
apitask = admin-schools
apikey = Your API key
ses = The session token ID

Response fields
schools = will provide a list of classes in <item> tags

In each <item> tag:
subid = the Engrade user ID (UID) of the school (you'll need this to get the school's classes, etc.)
joined = Unix timestamp of the date the admin joined the school
role = the role of the admin at the school
name = the name of the school
usr = the Engrade username of the school

***** Request *****
POST /api/ HTTP/1.1
Host: api.engrade.com
Content-length: x

apikey=1234&apitask=admin-schools&ses=abc1234



***** Response *****
HTTP/1.0 200 OK
Date: Sat, 15 Jan 2000 14:37:12 GMT
Content-Type: text/xml
Content-Length: x

<?xml version="1.0" encoding="utf-8" ?>
<engrade>
<success>true</success>
<schools>
<item>
<superid>1000003121245</superid>
<subid>1000002850886</subid>
<supertype>admin</supertype>
<subtype>school</subtype>
<auth>6</auth>
<joined>1280957508</joined>
<role>Admin</role>
<name>Demo School</name>
<usr>school</usr>
<pic>1</pic>
</item>
</schools>
<time>1289246466</time>

</engrade>


Admin Create School
URL: https://api.engrade.com/api/

Input Fields:
apitask = admin-school-new
apikey = Your API key
ses = The session token ID
name = Name of the school: Johnson High School
role = The admin's role at the school: Principal

Return Fields:
schoolid = The Engrade UID/SUPERID/SUBID/SCHOOLID of the school
usr = The Engrade username of the school

School

Note: In order to access any school functions, you must first create a session ID from an approved school admin, then include that session ID and the school's UID in your request.

Get School Classes
List the classes that belong to a given school.

URL: https://api.engrade.com/api/

Input Fields:
apitask = school-classes
apikey = Your API key
ses = The session token ID of a school admin
schoolid = The UID of the school
folder = 3 for active, 2 for archived, 1 for trashed

School Create Class
URL: https://api.engrade.com/api/

Required input fields
apitask = school-class-add
apikey = Your API key
ses = The session token ID
schoolid = the UID of the school to which to add the class
priteach = the UID of the primary teacher of the class or 0 for no primary teacher
name = Name of the class
syr = School year (2YYY or 2YYY-2YYY)
gp = Grading period (1-9)
gradelevel = (see list below)
subject = (see list below)
students = list of students, one per line in format FirstName LastName IDNumber

gradelevel options:
0 = Pre-School and Kindergarten
1 - 12 for 1st through 12th grade
13 = College
14 = Occupational
99 = Other

subject options:
26 = Art
19 = Business &amp; Economics
39 = Computer Science
40 = Geography
36 = Government &amp; Politics
44 = History
12 = Math
25 = Music
42 = Foreign Language
1 = Language Arts
5 = Science
41 = PE and Health
18 = Religion
99 = Other


Output fields:
clid - This will be Engrade's unique class ID for this class

Get School Teachers
List the teacher accounts that belong to a given school.

URL: https://api.engrade.com/api/

Input Fields:
apitask = school-teachers
apikey = Your API key
schoolid = The UID of the school
ses = The session token ID of a school admin

Response fields
school = contains info about the school
teachers = contains a list of school teachers in <item> tags

In each <item> tag:
subid = the Engrade user ID (UID) of the teacher
joined = Unix timestamp of the date the teacher joined the school
role = the role of the teacher at the school
name = the name of the teacher
usr = the Engrade username of the teacher
pic = 1 if the teacher has uploaded a picture, 0 if he has not

Email Invite Teachers
URL: https://api.engrade.com/api/

Input Fields:
apitask = school-teacher-email
apikey = Your API key
ses = The session token ID
schoolid = The Engrade UID of the school creating the teacher
emails = A list of teacher emails separated by whitespaces

This feature will send an email to each teacher listed with instructions for either connecting their existing Engrade account to the school or to create a new Engrade teacher account that will be connected to the school's account.

School Create Teachers
URL: https://api.engrade.com/api/

Input Fields:
apitask = school-teacher-bulk
apikey = Your API key
ses = The session token ID
schoolid = The Engrade UID of the school creating the teacher

name1 = The name of the first teacher as students will see it
email1 = The email address of the first teacher
name2 = The name of the second teacher as students will see it
email2 = The email address of the second teacher
...

Return Fields
uid1 = The Engrade User ID for the first teacher
usr1 = The username for the first teacher
pwd1 = The password for the first teacher
uid2 = The Engrade User ID for the first teacher
usr2 = The username for the first teacher
pwd2 = The password for the first teacher
...

Engrade will automatically create accounts for each teacher entered (1-99). The teacher will be emailed their username and password, and the admin will be emailed a list of all teachers' usernames and passwords. If teachers wish, they change their usernames and passwords by logging in and clicking "Account" at the top of the page.

School Drop Teacher
This will disconnect a teacher from the school's Engrade account.

URL: https://api.engrade.com/api/

Input Fields:
apitask = school-teacher-edit
apikey = Your API key
ses = The session token ID
delete = Must equal 1
schoolid = The school's Engrade UID
teachid = The teacher's Engrade UID

Email Invite Admins
URL: https://api.engrade.com/api/

Input Fields:
apitask = school-admin-email
apikey = Your API key
ses = The session token ID
schoolid = The Engrade UID of the school creating the admin
emails = A list of admin emails separated by whitespaces

This feature will send an email to each admin listed with instructions for either connecting their existing Engrade account to the school or to create a new Engrade admin account that will be connected to the school's account.

Edit School
URL: https://api.engrade.com/api/

Input Fields:
apitask = admin-school-edit
apikey = Your API key
ses = The session token ID
schoolid = The Engrade UID of the school
usr = Username of the school: johnsonhs
name = Name of the school: Johnson High School
email = Primary contact email address of the school: admin@jhs.k12.edu
p0 = Attendance mode: 0 for by class, 1 for schoolwide (requires Plus)
p1 = Block teachers from editing rosters - 0 no, 1 yes (requires Plus)
p2 = Enable class marking periods - 0 no, 1 yes (requires Plus)

School Create Admin
URL: https://api.engrade.com/api/

Input Fields:
apitask = school-admin-new
apikey = Your API key
usr = Account username, must be a-z and 0-9 only
name = Name of teacher as students will see it
email = Email address of teacher
pwd = Account password
schoolid = The Engrade UID of the school creating the teacher

Note you must choose a username not already taken by another Engrade user. If a username is already taken, the API will return an error explaining as much.

School Drop Admin
This will disconnect an admin from the school's Engrade account.

URL: https://api.engrade.com/api/

Input Fields:
apitask = school-admin-edit
apikey = Your API key
ses = The session token ID
delete = Must equal 1
schoolid = The school's Engrade UID
adminid = The teacher's Engrade UID

Bulk Register Students
URL: https://api.engrade.com/api/

Input Fields:
apitask = school-students-register
apikey = Your API key
ses = The session token ID
schoolid = The Engrade UID of the school
syr = The school year in which students have classes
gp = The grading period in which students have classes
email_STUID1 = The email address of the student with the student id STUID1
email_STUID2 = The email address of the student with the student id STUID2
...

Return Fields
uid_STUID1 = The Engrade User ID for the student with the student id STUID1
usr_STUID1 = The username for the student with the student id STUID1
pwd_STUID1 = The password for the student with the student id STUID1
...

This API call will create accounts for ALL students who DO have a class in the given grading period, but who do NOT yet have an account. Sending this call will create accounts for ALL such students whether you specify their email address or not. The email field is optional and, if specified, will allow Engrade to email the student the username and password that Engrade automatically generated for him/her.

Creating a School from Scratch

To create a school, admins, teachers, and classes on Engrade for a school with no existing accounts, do the following:

1. Create a personal admin account for the school's Technology Coordinator using the admin-signup call.

2. Log in as that admin using the login call. This will return the ses value that you will need for the subsequent calls.

3. Create a new school profile using the admin-school-new call. This will return the uid value that you should store on your server and will need for the subsequent calls.

4. Create accounts for the school's other admins and teachers using the school-admin-new and school-teacher-new calls respectively. You will need to provide the school's uid from the previous step in the schoolid field. Each new account will return a uid value that you will should store on your server and will need for the next step.

5. Create classes using the school-class-add call. You will need to provide the school's uid from the Step 3 in the schoolid field. Each class will also need a valid teacher's uid from the previous step supplied for the priteach field.