Notes API

Description

This API call responds with notes data based on the input parameters.

Endpoint Specification

Path: api/notes

Method: GET

Parameters:

Parameter Name	Definition
batchSize	For pagination. The number of notes to retrieve at a time. Default value is 500. Maximum value is 1000. If you set this parameter, you'll also need to set the batchIndex parameter.
batchIndex	For pagination. The number of the page in the set you'd like to retrieve. Defaults to 1. If you set this parameter, you'll also need to set the batchSize parameter.
noteType	Will return notes of a given type. The possible options are "note", "reminder" and "statusChange". The "note" option will return all notes. The "reminder" option will return only notes with a due date. The "statusChange" option will return only notes with one or more note reasons. It is possible for a note to have both a due date and note reasons, so the "reminder" and "statusChange" sets of notes will not be mutually exclusive. If you want to include all types of notes, you could either specify "note", or not include this parameter in the query at all.
anyDateFrom	Will return notes whose create date or update date is on or after the date specified, date inclusive (in MM/DD/YYYY format). This will capture all notes for which there has been any activity on or after the date specified.
anyDateTo	Will return notes whose create date or update date is on or before the date specified, date inclusive (in MM/DD/YYYY format). This will capture all notes for which there has been any activity on or before the date specified.
createDateFrom	Will return notes created on or after the date specified, date inclusive (in MM/DD/YYYY format)
createDateTo	Will return notes created on or before the date specified, date inclusive (in MM/DD/YYYY format)
updateDateFrom	Will return notes updated on or after the date specified, date inclusive (in MM/DD/YYYY format)
updateDateTo	Will return notes updated on or before the date specified, date inclusive (in MM/DD/YYYY format)
date	Deprecated. The createDateFrom parameter will provide the same functionality. Will return notes created on or after the date specified, date inclusive (in MM/DD/YYYY format)
displayDateFrom	Deprecated. The createDateFrom parameter will provide the same functionality.
displayDateTo	Deprecated. The createDateTo parameter will provide the same functionality.

Template API Call using cURL

curl -u <YourAPIUSername>:<YourAPIKey> "https://<yourschoolsubdomain>.gradesfirst.com/api/notes?batchSize=300&batchIndex=1"

Example API Call using cURL

curl -u apiuser:ebd6b6470d35d12675fcbd308125b7 "https://coastalcollege.gradesfirst.com/api/notes?batchSize=300&batchIndex=1"

Template API Call using HTTP Basic Authentication

https://<username>:<api-key>@<yourschoolsubdomain>.gradesfirst.com/api/notes?batchSize=300&batchIndex=1

Example API Call using HTTP Basic Authentication

https://apiuser:ebd6b6470d35d12675fcbd308125b7@coastalcollege.gradesfirst.com/api/notes?batchSize=300&batchIndex=1

Template API Call using HTTP Basic Authentication via a web browser

https://<username>:<api-key>@<yourschoolsubdomain>.gradesfirst.com/api/notes.json?batchSize=300&batchIndex=1

Example API Call using HTTP Basic Authentication via a web browser

https://apiuser:ebd6b6470d35d12675fcbd308125b7@coastalcollege.gradesfirst.com/api/notes.json?batchSize=300&batchIndex=1

Example Requests

Some example queries are as follows:

To fetch the first 500 notes:

https://coastalcollege.gradesfirst.com/api/notes?batchSize=500&batchIndex=1

To fetch the next 500 notes if 500 notes were returned in the first batch:

https://coastalcollege.gradesfirst.com/api/notes?batchSize=500&batchIndex=2

To fetch notes created between 10/01/2014 and 11/01/2014 (both dates inclusive)

https://coastalcollege.gradesfirst.com/api/notes?batchSize=500&batchIndex=1&createDateFrom=10/01/2014&createDateTo=11/01/2014

To fetch notes created or updated since 11/01/2014 (inclusive)

https://coastalcollege.gradesfirst.com/api/notes?batchSize=500&batchIndex=1&anyDateFrom=11/01/2014

To fetch notes created or updated between 11/01/2014 and 12/10/2014 (both dates inclusive)

https://coastalcollege.gradesfirst.com/api/notes?batchSize=500&batchIndex=1&anyDateFrom=11/01/2014&anyDateTo=12/10/2014

To fetch notes that associated with a note reason

https://coastalcollege.gradesfirst.com/api/notes?batchSize=500&batchIndex=1&noteType=statusChange

To fetch all notes associated with a due date that have been updated on or before 11/01/2014

https://coastalcollege.gradesfirst.com/api/notes?batchSize=500&batchIndex=1&noteType=reminder&updateDateTo=11/01/2014

Output

This call outputs a JSON array.

Attribute Name	Definition
status	"success" if the API call was successful. Possible values: success success, no matches found error
message	A human-readable description of the results of the API call
Note	DataType
noteId	(integer) The internal system id of the note.
removed	(boolean) Legacy. This attribute is here for backward compatibility. Always false.
noteBody	(string) The text of the note.
studentId	(string) The primary id of the student related to this note.
privateNote	(boolean) true if the note is marked as private; false otherwise.
removedDate	(date) Legacy. This attribute is here for backward compatibility. Always null.
advisorId	(string) The primary id of the advisor who created this note.
statusStatus	(string) The note reason associated with the note.
dateCreated	(date) The date the note was created.
displayDate	(date) Legacy. Same as dateCreated.
edited	(string) "N" if this field has been edited after it was created.
dateEdited	(date) The date when the note was edited. Null if not edited.
noteCreatedWithReminder	(string) "Y" If the due date field on this note has a value. "N" otherwise.
noteCreatedWithStatusChange	(string) "Y" if this note has one or more note reasons. "N" otherwise.
noteBodyPlainText	(string) Another form of noteBody without the html tags.

Output Examples

A successful call to the API:

{
"status":"success",
"message":"The request for notes has been processed successfully. 2 records have been returned.",
"data":[
{
"noteId":4277,
"removed":false,
"noteBody":"<p>Shantelle received excellent feedback again</p>",
"studentId":"126897",
"privateNote":true,
"removedDate":null,
"advisorId":"127026",
"studentStatus":"Family loss",
"dateCreated":"09/11/2015",
"displayDate":"09/11/2015",
"edited":"N",
"dateEdited":null,
"noteCreatedWithReminder":"N",
"noteCreatedWithStatusChange":"Y"

"noteBodyPlainText": "Shantelle received excellent feedback again"

},
{
"noteId":4278,
"removed":false,
"noteBody":"Ivan received excellent feedback",
"studentId":"129001",
"privateNote":true,
"removedDate":null,
"advisorId":"127026",
"studentStatus":"Following up ",
"dateCreated":"09/11/2015",
"displayDate":"09/11/2015",
"edited":"N",
"dateEdited":null,
"noteCreatedWithReminder":"N",
"noteCreatedWithStatusChange":"Y"

"noteBodyPlainText": "Ivan received excellent feedback"
}
]
}

A call to the API that has an incorrect parameter or incorrect note type:

{

"status": "error",

"message": "The parameters entered for this request are invalid.",

"data": null

}

A call to the API that has an incorrect date format for one of the parameters:

{

"status": "error",

"message": "The date entered for this request is invalid. It must be in MM/DD/YYYY format and be a date after 01/01/2010 (there are no records before that date).",

"data": null

}

A call to the API that has happened less than 12 hours after the previous successful call to the API:

{

"status": "error",

"message": "Activity for this API is limited. Your institution has already accessed the API a short time ago, and must wait until the required period is completed before accessing it again.",

"data": null

}

A call to the API that has resulted in any other error:

{

"status": "error",

"message": "An error occurred while processing your request.",

"data": null

}