API 1.0

Overview

The API allows programmatic access to the features of this site, and is particularly useful for writing programs that integrate this site with third-party systems. It uses HTTP and JSON for ease of use and includes several open-source clients.

Version 1 of the API allows you to access data about the users, classes, assignments, and grades associated with your site. Additional functions will be added rapidly based on user feedback; if there's a feature you'd like to see added, please post it to the suggestions forum.

Getting started

By default, API access to the site is disabled. To use the API, first, ask an administrator to enable API access by clicking Admin/Api and enabling the API. This will also display an API key that is required to invoke the API on their behalf. Then download one of our open-source clients or use your favorite programming language to send API calls manually.

Client libraries

We currently provide the following open-source client libraries; click for more information.

If your favorite programming language doesn't currently have an open-source client, don't worry - it's easy to invoke the API manually from any programming language. In addition, it's straightforward to port the current open-source clients to other languages, and we'd love to host any new client library that you create so that others in our community can benefit from your work!

Rate limiting

If you exceed 120 API calls per minute, you will receive a rate limit exception, and API access will be disabled for a minute. This is to protect our servers against API attacks.

Protocols

The on-the-wire protocol uses HTTPS and JSON for simplicity. To invoke an API, perform an HTTP GET to https://[yoursbusiness].matrix.com/api/ followed by the name of the function and arguments supplied using standard URL encoding. If the argument name XXX" is an array, each element of the array should be passed with the name "XXX[]". Times are sent and received in "YYYY-MM-DDThh:mmTZD" format as specified in ISO 6801. Dates are sent and received in "YYYY-MM-DD" format. The API key of an administrator account must also be passed with each API call as the argument with name "api_key". The version of the API that you wish to invoke can also be passed with each API call as the argument "api_version". If omitted, it defaults to the latest version of the API.

If the API call executes normally, the HTTP status of the reply is 200 (OK) and the HTTP reply body is a JSON structure with content type = "application/json; charset=utf-8".

Here are some examples that show the HTTP request and response (each request is a single line, so ignore wrapping):

get_version: Request: https://yourbusiness.matrixlms.com/api/get_version?api_key=23-34-d315a3421
Response: {"version":1}
get_assignments_for_class(1456): Request: https://yourbusiness.matrixlms.com/api/get_assignments_for_class?api_key=23-34-d315a3421&class_id=1456
Response: [{"type":"Freeform","name":"PLOP","points":100.0,...},{"type":"Quiz","name":"XXX","points":0.0,...}]
get_users_with_ids([1,2]): Request: https://yourbusiness.matrixlms.com/api/get_users_with_ids?api_key=23-34-d315a3421&user_ids[]=1&user_ids[]=2
Response: [{"ssn":"123-456-7890","last_name":"Smith",...},{"ssn":null,"last_name":"Jones",...}]

If the API call is unsuccessful, the HTTP status of the reply is 401 (UNAUTHORIZED) in the case of an authentication failure and 400 (BAD REQUEST) otherwise. The HTTP reply body is a JSON structure with content type = "application/json; charset=utf-8". that contains a single field called 'message' that describes the error.

Here's an example that shows the HTTP request and response:

get_version (with incorrect API key): HTTP Request: https://yourbusiness.matrixlms.com/api/get_version?api_key=23-34-d31dae3671
HTTP Response: {"message":"Invalid API key"}

Some APIs can return a lot of data. These APIs are paginated and return data in pages of 100 results. To specify which page of results you want, provide a "page" argument of the form page=XXX, where XXX is a page number that starts at 1. If no page argument is provided, it defaults to 1. If the page number goes beyond the last page of results, an empty set of results is returned.

Version

The following function provides access to the version number of the API:

get_version: Get the version number of the API, which will be a simple integer (1, 2, 3, etc.).

Authentication

The following function allows you to check authentication:

is_authenticated(userid, password): Return true if the password is correct for the specified userid, otherwise return false.

Users

The following functions provide access to user account information:

get_my_account: Info about the caller's account.
get_all_users(page=1): Array of info about all the users in the caller's school. This function is paginated.
get_users_with_ids(user_ids): Array of info about the specified users.
get_users_that_match(constraints, page=1): Array of info about the users that satisfy all the specified constraints, which are specified in the form attribute1=value1&attribute2=value2. The supported attributes are organization id, first name, last name, email, phone, userid, studentID, teacherID, year of graduation, birthdate, nick name, country, state, zip, teacher, student, assistant, monitor, manager, administrator, parent, archived, job_title_id + accounts custom fields.This function is paginated.

User info has the following fields:

id: Unique user ID, referred to as user_id when passed as a parameter to an API call.
first_name: First name
last_name: Last name
userid: Login userid
password: Login password
email: Email address
sms_email: SMS gateway address
student: True if a student, otherwise false
teacher: True if an instructor, otherwise false
assistant: True if a teaching assistant, otherwise false
administrator: True if an administrator, otherwise false
monitor: True if a monitor, otherwise false
manager: True if a manager, otherwise false
parent: True if a parent, otherwise false (only present if families are enabled)
parent_ids: If user has parents, an array of ids of the parent (only present if families are enabled)
children_ids: If user has children, an array of ids of the children (only present if families are enabled)
year_of_graduation: Year of graduation
student_id: Student ID
teacher_id: Teacher ID
organization_id: If organizations are enabled, the ID of the user's organization
organization_id: Organization ID
birthdate: Birthdate
nick_name: Nick name
skype: Skype name
phone: Phone number
gender: If known, Male or Female, otherwise null
street_1: Street address line 1
street_2: Street address line 2
city: City
state: State/Province
zip: Zip code
country: Country
picture: URL of user profile picture
joined_at: Time account was created.
first_login_at: Time of first login.
last_login_at: Time of last login.
logins: Number of logins.
archived: True is the user is archived, otherwise false.
archived_at: If the user was archived, the time that the archive occurred
job_title_id: The id of their job title, if they have one

The user info also includes entries for any custom fields that are defined.

The following function allows you to add a user:

add_user(attributes): Add a user with the specified attributes, which are in the form attribute1=value1&attribute2=value2, etc. If an account with a matching userid, student ID, teacher ID, or name & birth date is found, it's assumed that its information is to be updated instead of creating a new account. Returns the ID and userid of the newly added account.
update_user(attributes): Update a user with the specified attributes, which are in the form attribute1=value1&attribute2=value2, etc. Users are matched based on userid, student ID, teacher ID, or name & birth date. If a match is not found, an exception is returned. Returns the ID and userid of the updated account.

When adding/updating a user, the following attributes have a special meaning:

account_types: A comma-separated list of account types that the user can have: student, teacher, assistant, manager, monitor, administrator, and/or partial_administrator.
change_password: Set to true if you need the user to change their password when they first log in. False by default.
update_password: Set to true if you want the password of an existing account to be updated. False by default.
send_login_instructions: Set to true if you want the user to be sent login instructions. False by default.
from_name: If send_login_instructions is true, send the instructions from this name.

The following functions allow you to archive and reactivate students:

archive_users(user_ids): Archive the users with the specified user IDs.
reactivate_users(user_ids): Reactivate the users with the specified user IDs.
delete_users(user_ids): Delete the users with the specified user IDs.

Courses

The following functions provide access to course information:

get_all_classes(archived=nil, page=1)

Array of info about all the courses in the caller's school. By default, this includes all archived courses, but you can pass an optional archived=value parameter where value can be true or false. This function is paginated.

get_classes_with_ids(class_ids)

Array of info about all the specified courses.

get_classes_for_organization(organization_id, archived=nil, page=1)

Array of info about all the courses that have at least one student enrolled from the specified organization. By default, this includes all archived courses, but you can pass an optional archived=value parameter where value can be true or false. This function is paginated.

get_classes_that_match(constraints, page=1)

Array of info about the courses that satisfy all the specified constraints, which are specified in the form attribute1=value1&attribute2=value2. The supported attributes are name, course_code, section_code, and archived. This function is paginated.

get_classes_taught_by(user_id)

Array of info about the courses taught by the specified user. Each course info includes an additional 'coteacher' field that is true if the user is a co-teacher.

get_classes_enrolled_by(user_id)

Array of info about the courses enrolled in by the specified user.

get_all_class_completions

This endpoint will return all students who completed a class, containing all the fields for the associated class and student (user). The two data sets will be separated in the output under the “class” and “student” keys. Additionally, if the completed class awards certificates, these will be returned in an array under the “certificates” key. Certificate objects contain all the fields related to a certificate, including a URL to download the certificate PDF.

The API output provides a download URL for each PDF under the "certificate_file_url" key. This download URL will call a separate API endpoint called "download_certificate" and pass the current API key automatically. This API endpoint accepts the following optional parameters to filter the output:

completed_after - Return completions after this date

completed_before - Return completions before this date

class_id - Only completions for this specific class

user_id - Only completions for this specific user

The date filters accept various date formats, however the recommended format is YYYY-MM-DD.

Note: It’s recommended to apply at least one filter parameter, otherwise the output size can be very large.

Example call:

https://www.ABCschoolEd.com/api/get_all_class_completions?api_key=customerAPIKey&completed_after=2022-08-01&class_id=123456

get_teachers_for_class(class_id): Array of user info about the teachers in the specified course. Each user info includes an additional 'coteacher' field that is true if the user is a co-teacher.
get_students_for_class(class_id): Array of student info about the students in the specified course.
get_status_of_classes(user_id): Three arrays of class IDs for the specified user, in the form 'enrolled' => [class ids], 'deactivated' => [class ids], 'completed' => [class ids]

Course info has the following fields:

id: Unique class ID, referred to as class_id when passed as a parameter to an API call.
name: Name
style: The style ('Instructor', 'Self paced' or 'Blended')
course_code: Course code
section_code: Section code
picture: URL of the class's picture
semester: Semester
start: Start date of the class (if not self paced)
finish: Finish date of the class (if not self paced)
class_times: An array of the entries for the course schedule shown in Admin/Configure/Schedule (if not self paced) [{"day"=>"Tue", "from"=>"15:15", "to"=>"17:30", "location"=>"Los Angeles"}, {"day"=>"Wed", "from"=>"16:0", "to"=>"18:0", "location"=>"Room 101"}]
weighting_using_categories: True if group assignments by category when calculating weights.
weighting_style: Weighting style ('MaxScore', 'Points', 'Percent', 'Equally')
display_in_catalog: True if the course is displayed in the catalog, otherwise false.
archived: True if the course is archived.
catalog_category: The catalog categories of the course.
grademap: Array of grade mappings of the form {'grade' => grade, 'minimum_percent' => percent} in descending order of minimum percent
grading_periods: Array of grading periods of the form {'name' => name, 'percent' => percent, 'start' => start} in ascending order of start date
custom fields: An entry of the form name=value for each custom field in the course.

Student info has all the fields of user info plus the following fields:

notes: Array of notes of the form {'teacher_id' => <id of teacher who submitted the note>, 'submitted_at' => <time note was submitted>, 'show_student' => <true if the student should see the note, otherwise false>, 'show_parents' => <true if the parents should see the note, otherwise false>, 'subject' => <subject of the message>, 'message' => <note contents>}.
enroll_type: How the learner was enrolled, valid values are: Direct','Roster','Invite','Transfer','Copy','File','Catalog','API','Waitlist','SIS'
enrolled_at: When the learner was enrolled
enrolled_by_id: The ID of the user who enrolled the learner
started_at: When the learner first visited the course
last_visited_at: The last time the learner visited the course
time_spent: The amount of time in seconds that the learner has spent in the course
completed_at: When the learner completed the course, or nil if not applicable
unenrolled: True if the learner was unenrolled from the course, false otherwise
unenrolled_at: When the learner was unenrolled, or nil if not applicable
unenrolled_by_id: The ID of the user who unenrolled the learner, or nil if not applicable
deactivated: True if the learner is deactivated, otherwise false
deactivated_at: When the learner was deactivated, or nil if not applicable
reactivated_at: When the learner was reactivated, or nil if not applicable
percent: If the learner has completed the course, their percent at the time of completion
grade: If the learner has completed the course, their grade at the time of completion

The following function allows you to add students to a course:

add_students_to_class(class_id, user_ids, options): Enroll the specified users into the specified course, with an optional set of options. If successful, the number of users that were enrolled is returned. This API either succeeds completely or fails completely - if an errors occur, no users are enrolled.

When adding students, the following options are available:

send_notification: If true, send each student the canned message that tells them they have been enrolled into the course. False by default.
ignore_already_enrolled: If true, don't generate an error if the student is not enrolled in the course. False by default.

The following function allows you to remove students from a course:

remove_students_from_class(class_id, user_ids, options): Unenroll the specified users from the specified course, with an optional set of options. If successful, the number of users that were unenrolled is returned.

The following function allows you to deactivate students from a class:

deactivate_students_in_class(class_id, user_ids, options): Deactivate the specified users from the specified class, with an optional set of options.

The following function allows you to reactivate students from a class:

reactivate_students_in_class(class_id, user_ids, options): Reactivate the specified users from the specified class, with an optional set of options.

The following function allows you to complete students from a class:

complete_students_in_class(class_id, user_ids, options): Complete the specified users from the specified class, with an optional set of options.

The following function allows you to uncomplete students from a class:

uncomplete_students_in_class(class_id, user_ids, options): Uncomplete the specified users from the specified class, with an optional set of options.

When removing students, the following options are available:

send_notification: If true, send each student the canned message that tells them they have been unenrolled from the course. False by default.

The following functions allows you to deactivate/reactivate students in a course:

deactivate_students_in_class(class_id, user_ids): Deactivate the specified students in the specified course.
reactivate_students_in_class(class_id, user_ids): Reactivate the specified students in the specified course.

The following function allows you to add instructors to a course:

add_teachers_to_class(class_id, user_ids, options): Add the specified users as instructors of the specified course, with an optional set of options. If successful, the number of users that were added is returned. This API either succeeds completely or fails completely - if an errors occur, no users are added as instructors.

When adding instructors, the following options are available:

send_notification: If true, send each instructor the canned message that tells them they have been added to the course. False by default.

The following function allows you to remove instructors from a course:

remove_teachers_from_class(class_id, user_ids): Remove the specified users as instructors from the specified course. If successful, the number of users that were removed is returned.

The following function allows you to add a course:

add_class(attributes): Add a class, which are in the form attribute1=value1&attribute2=value2, etc. Returns the ID of the newly added course.
add_class_from_template(class_template_id, attributes): Add a course which is a copy of the specified course template, then set the specified attributes (which are optional) on the copy. Returns the ID of the newly added course. If you want to make the template a parent course to allow synchronization, include the attribute sync=true.
add_child_class(parent_class_id, attributes): Add a child course to the specified parent course, then set the specified attributes (which are optional) on the copy. Returns the ID of the newly added child course.

When adding a course, the following attributes can be specified:

name: The name of the course.
description: A description of the course.
style: The style of the course, which can be 'Instructor', 'Self paced', or 'Blended'. 'Self-paced' by default.
start_at: If instructor-led or blended, the start date of the course.
finish_at: If instructor-led or blended, the end date of the course.
private: Set to true if you want the course to be private and have an access code. True by default.
top_tab: The landing page of the course, which can be 'News', 'Lessons', 'Custom', 'CurrentLesson', or 'Agenda'. 'Lessons' by default.
picture: The URL where the picture for the course should be loaded. If omitted, the default course picture is used.
tabs: A comma-separate list of the tabs this class should have. The available tabs are 'custom', 'news', 'lessons', 'custom', 'calendar', 'blogs', 'resources', 'forums', 'wikis', 'chat', 'attendance', 'groups', 'portfolios', 'reviews', 'syllabus_tab', 'students_tab', 'parents_tab', and 'teachers_tab'.

The following function allows you to edit a course:

edit_class(class_id, attributes): Edit the specified course, with the attributes to update in the form attribute1=value1&attribute2=value2, etc. Returns the ID of the edited course. The attributes are the same as the attributes for add_class().

The following functions allows you to archive/reactivate/delete/restore classes:

archive_classes(class_ids): Archive the specified classes.
reactivate_classes(class_ids): Unarchive the specified classes.
delete_classes(class_ids): Delete the specified classes (and place them into the trash can).
restore_classes(class_ids): Restore the specified classes from the trash can.

Course Templates

The following function allows you to add a class template:

add_class_template(attributes)

The following function allows you to edit a class template:

edit_class_template(class_id, attributes)

The following functions provide access to course template information:

get_all_class_templates(archived=nil, page=1): Array of info about all the courses in the caller's school. By default, this includes all archived courses, but you can pass an optional archived=value parameter where value can be true or false. This function is paginated.
get_class_templates_with_ids(class_ids): Array of info about all the specified courses.
get_class_templates_for_organization(organization_id, archived=nil, page=1): Array of info about all the courses that have at least one student enrolled from the specified organization. By default, this includes all archived courses, but you can pass an optional archived=value parameter where value can be true or false. This function is paginated.
get_class_templates_that_match(constraints, page=1): Array of info about the courses that satisfy all the specified constraints, which are specified in the form attribute1=value1&attribute2=value2. The supported attributes are name, course_code, section_code, and archived. This function is paginated.

Course info has the following fields:

id: Unique class ID, referred to as class_id when passed as a parameter to an API call.
name: Name
style: The style ('Instructor', 'Self paced' or 'Blended')
course_code: Course code
section_code: Section code
picture: URL of the class's picture
semester: Semester
start: Start date of the class (if not self paced)
finish: Finish date of the class (if not self paced)
weighting_using_categories: True if group assignments by category when calculating weights.
weighting_style: Weighting style ('MaxScore', 'Points', 'Percent', 'Equally')
display_in_catalog: True if the course is displayed in the catalog, otherwise false.
archived: True if the course is archived.
catalog_category: The catalog categories of the course.
grademap: Array of grade mappings of the form {'grade' => grade, 'minimum_percent' => percent} in descending order of minimum percent
grading_periods: Array of grading periods of the form {'name' => name, 'percent' => percent, 'start' => start} in ascending order of start date

The following function allows you to add a course template:

add_class_template(attributes): Add a course template, which are in the form attribute1=value1&attribute2=value2, etc. Returns the ID of the newly added course. The attributes are the same as the attributes for add_class().

The following function allows you to edit a course template:

edit_class_template(class_id, attributes): Edit the specified course template, with the attributes to update in the form attribute1=value1&attribute2=value2, etc. Returns the ID of the edited course template. The attributes are the same as the attributes for add_class().

The following functions allows you to delete/restore class templates:

delete_class_templates(class_ids): Delete the specified class templates (and place them into the trash can).
restore_class_templates(class_ids): Restore the specified class templates from the trash can.

Modules

The following functions provide access to course information:

get_lessons_for_class(class_id): Array of info about all the modules in the specified course, in the order that they appear. Please note that the API also includes information about a module's sections in addition to the module information.

Module info has the following fields:

id: Unique lesson ID
name: Name
start_at: When the lesson is scheduled to start, or null if not scheduled
competencies: If mastery is enabled for the class, an array of the ids of the competencies associated with the module.
sections: An array of information about the sections in the module.

Section info has the following fields:

id: Unique section ID
name: Name
type: The type of the section (Page, Assignment, SCORM, Class, or Certificate)
assignment_id: If it's an assignment section, the id of its associated assignment.
class_id: If it's a course section, the id of its associated course.
certificate_id: If it's a certificate section, the id of its associated certificate.

Assignments

The following functions provide access to assignment information:

get_assignments_for_class(class_id): Array of info about all the assignments in the specified course, in the order that they appear.

Assignment info has the following fields:

id: Unique assignment ID
name: Name
type: Type ('Attendance', 'Debate', 'Discussion', 'Freeform', 'Offline', 'Quiz', 'Survey', 'Team')
points: Points
category: The weighting category, or null if none
grading: The grading type (Normal, Extra credit, Ignore or Not graded)
weight: The weight (only present if the course is weight-by-category or weight-by-points-within-category)
begin: Begin time (not present if the course is self-paced)
end: End time (not present if the course is self-paced)
given: True if given, otherwise false (not present if the course is self-paced)
gateway: True if a gateway, otherwise false
gateway_threshold: The gateway threshold (only present if the assignment is a gateway)
lesson: The id of the assignment's lesson, or null if not in a lesson
competencies: If mastery is enabled for the class, an array of the ids of the competencies associated with the assignment

Grades

The following functions provide access to grade information:

get_grades_for_class(class_id): Array of grade info for each user in the specified class.
get_grades_for_user(user_id): Array of the form {'class_id' => class_id, 'grades' => <grade info>} for the specified user in all their classes (excluding those that are archived).

Grade info for a student is of the form {'user_id' => user_id, 'percent' => percent, 'grade' => grade, 'grading_periods' => [grading_period_info]}, where grading_period_info is of the form {'name' => name, 'percent' => percent, 'grade' => grade, 'assignments' => [assignment_info]} and assignment_info is of the form {'id' => assignment id, 'percent' => percent, 'grade' => grade, 'score' => score, 'points' => points, 'comment' => comment, 'submitted_at' => submission_time, 'grader_id' => id_of_grader}. The grading_period_info is in ascending order of date. If the assignment was a quiz or SCORM assignment and the grade was set manually by the grader, then assignment_info also includes 'gradebook' => true.

The following function allows grades to be set:

set_grades_for_assignment(assignment_id, grades): Set the grades for the specified users within the specified assignment. The grades are an array of the form {''user_id'' => user_id, ''grade'' => grade}. A grade can be a letter grade (B+), a floating point number (3.1), a percentage (15%), a blank ('') or a special grade (X/M/I/AB).

Organizations

The following functions provide access to organizations:

get_all_organizations(page=1): Array of info about all the organizations in the caller's business. This function is paginated.
get_organizations_with_ids(organization_ids): Array of info about all the specified organizations.

Organization info has the following fields:

id: Unique organization ID, referred to as organization_id when passed as a parameter to an API call.
name: Name
description: Description
internal: Is it an internal organization? (true/false)

The following function allows you to add an organization:

add_organization(attributes): Add an organization, which are in the form attribute1=value1&attribute2=value2, etc. Returns the ID of the newly added organization.

When adding an organization, the following attributes can be specified:

name: The name of the organization.
description: A description of the organization.
internal: Set to true if you want the organization to be internal. False by default.
picture: The URL where the picture for the organization should be loaded. If omitted, the default organization picture is used.

The following function allows you to edit an organization:

edit_organization(organization_id, attributes): Edit the specified organization, with the attributes to update in the form attribute1=value1&attribute2=value2, etc. Returns the ID of the edited organization. The attributes are the same as the attributes for add_organization().

The following function allows you to delete organizations:

delete_organizations(organization_ids): Delete the organizations with the specified organization IDs.

Groups

The following functions provide access to group information:

get_all_groups(page=1): Array of info about all the groups in the caller's business. This function is paginated.
get_groups_with_ids(group_ids): Array of info about all the specified groups.
get_groups_that_match(constraints, page=1): Array of info about the groups that satisfy all the specified constraints, which are specified in the form attribute1=value1&attribute2=value2. The only currently supported attributes are name and access_code. This function is paginated.
get_members_for_group(group_id): Return array of group user info for the members.
get_admins_for_group(group_id): Return array of group user info for the admins.
get_groups_with_member(user_id): Return array of info about all the groups that the specified user id a member of.
get_groups_with_admin(user_id): Return array of info about all the groups that the specified user id an admin of.

Group info has the following fields:

id: Unique group ID
name: Name
description: The group description
access_code: The access code, if activated
picture: The URL of the group picture
visibility: 'Private', 'Class', 'Team', 'Translator', 'School', 'District', or 'Community'
type: 'Interest', 'Study', 'Club', 'Hobby', 'Faculty', 'Students', or 'Topic'.
picture: URL of the group's picture.

Group user info has the following fields:

id: Unique user ID
joined_at: The time that the user joined the group.
last_visited_at: The last time that the user visited the group.

The following functions allows you to add and remove group admins and members:

add_members_to_group(group_id, user_ids): Add the users with the specified IDs as members of the group.
remove_members_from_group(group_id, user_ids): Remove the users with the specified IDs as members of the group.
add_admins_to_group(group_id, user_ids): Add the users with the specified IDs as admins of the group.
remove_admins_from_group(group_id, user_ids): Remove the users with the specified IDs as admins of the group.

The following function allows you to add a business-scope group:

add_group(attributes): Add a group, which are in the form attribute1=value1&attribute2=value2, etc. Returns the ID of the newly added group.

When adding a group, the following attributes can be specified:

name: The name of the group.
description: A description of the group.
admin_id: The user ID of the administrator of the group. The caller of the API by default.
private: Set to true if you want the group to be private and have an access code. True by default.
type: 'Interest', 'Study', 'Club', 'Hobby', 'Faculty', 'Students', or 'Topic'.
top_tab: The landing page of the group, which can be 'News', or 'Custom'. 'News' by default.
picture: The URL where the picture for the group should be loaded. If omitted, the default group picture is used.
tabs: A comma-separate list of the tabs this group should have. The available tabs are 'news', 'custom', 'calendar', 'blog', 'resources', 'forums', 'wikis', 'chat', 'members_tab', and 'admins_tab'.

The following function allows you to edit a group:

edit_group(group_id, attributes): Edit the specified group, with the attributes to update in the form attribute1=value1&attribute2=value2, etc. Returns the ID of the edited group. The attributes are the same as the attributes for add_group().

The following function allows you to delete business-scoped groups:

delete_groups(group_ids): Delete the groups with the specified group IDs.

Paths

The following functions provide access to path information:

get_all_paths(page=1): Array of info about all the paths in the caller's school. This API is paginated.
get_paths_with_ids(path_ids): Array of info about all the specified paths.
get_students_for_path(path_id): Array of user info about the students in the specified path.

Path info has the following fields:

id: Unique path ID, referred to as path_id when passed as a parameter to an API call.
name: Name
description: Description
picture: URL of the path's picture
sequencing: InOrder, OneAtATime, or Any
goals: Array of info about the path goals. Each info is of the form {type: CompleteClassGoal, class_id: ID of class}

The following function allows you to add students to a path:

add_students_to_path(path_id, user_ids, options): Enroll the specified users into the specified path, with an optional set of options. If successful, the number of users that were enrolled is returned. This API either succeeds completely or fails completely - if an errors occur, no users are enrolled.

When adding students, the following options are available:

send_notification: If true, send each student the canned message that tells them they have been enrolled into the path. False by default.

The following function allows you to remove students from a path:

remove_students_from_path(path_id, user_ids, options): Unenroll the specified users from the specified path, with an optional set of options. If successful, the number of users that were unenrolled is returned.

When removing students, the following options are available:

send_notification: If true, send each student the canned message that tells them they have been unenrolled from the path. False by default.

Resources

The following functions provide access to resources:

get_resources(constraints, page=1): Array of info about the resources (resources) that satisfy all the specified constraints and the total number of matches (count). The constraints are specified in the form attribute1=value1&attribute2=value2. The supported attributes are name, type, libraries (a single string separated by commas), and subject (if K-20 subjects are enabled). By default, the library scope is interpreted from the perspective of the user who calls the API. You can specify an optional user_id attribute to interpreted the libraries from the specified user's perspective. Up to 100 matches are returned. You can specify an optional offset attribute if you wish to paginate through all matches. This function is paginated.

Resource info has the following fields:

id: Resource ID
type: The type of resource (Assignment, Badge, Certificate, Class template, Competencies, Equalla, File, Google doc, Lesson, Page, Question bank, Rubric, SCORM package, Tool, Tool provider, Web resource)
name: Name of resource
library: The library where the resource is located (Personal, Organization, School, Network, All)
creator_id: The user ID of the resource creator.
created_at: When the resource was created
url: The URL of the page that shows this resource on the LMS
subject: The subject of the resource (if K-20 subjects are enabled)

Certificates

The following functions provide access to certificates:

get_all_certificates: Array of info about all the certificates in the caller's business and personal libraries.
get_certificates_with_ids(certificate_ids): Array of info about all the specified certificates.

Certificate info has the following fields:

id: Unique certificate ID
name: Name
description: Description
printable: Is it printable? (true/false)
duration: How< long is the certificate valid for?

Competencies

The following functions provide access to competencies:

get_all_curricula: Array of info about all competencies.
get_curricula_with_ids(curriculum_ids): Array of info about the competencies with the specified ids.

Competencies info has the following fields:

id: Unique competencies ID
name: Name.
description: Description.
city: The city the competencies are associated with.
state: The state the competencies are associated with.
country: The country the competencies are associated with.
organization: The organization the competencies are associated with.

The following functions provide access to competencies:

get_proficiencies_for_curriculum(curriculum_id): Array of info about the competencies in the specified competencies with sub-competencies included as children of their parent competency.

Competency info has the following fields:

id: Unique competency ID
name: Name.
code: Code.
description: Desription.
childen: If the competency has sub-competencies, this is an array of info about the sub-competencies.

The following functions provide the ids of competencies associated with a particular item, as well as a list of the ids of competencies that are ignored:

get_curricula_for_class(class_id): Array of info about the curricula associated with the specified class.
get_curricula_for_group(group_id): Array of info about the curricula associated with the specified group.
get_curricula_for_job_title(job_title_id): Array of info about the curricula associated with the specified job title.

Each item in the info array has the following fields:

id: Unique ID of the competency group
ignored_proficiency_ids: Array of IDs of the competencies being ignored.

Mastery

The following function provides access to mastery information for a class:

get_mastery_for_class(class_id): Mastery data in the form {'proficiencies' => [proficiency info], 'students' => [student info]}
get_mastery_for_class_students(class_id, student_ids): Mastery data in the form {'proficiencies' => [proficiency info], 'students' => [student info]} for the specific students.

Competency info has the following fields:

id: Unique competency ID.
percent: The average student percent for this competency
classification: The name mapped to this percent

Student info has the following fields:

id: Unique user ID.
percent: The average percent over all competencies
classification: The name mapped to this percent
proficiencies: An array of detailed competency info for the student

Detailed competency info has the following fields:

id: Unique competency ID.
percent: The percent for this competency
classification: The name mapped to this percent
mastered: True if the competency is mastered, otherwise false.
assignments: Array of assignment competency info.

Assignment competency info has the following fields:

id: Unique assignment ID.
percent: Percent for the competency for this assignment
classification: name mapped to this percent.

The following function provides access to aggregated mastery information for a user:

get_active_curricula_for_user(user_id): Return an array of competencies info for all the competency groups that the user is actively working on (those that appear in their mastery widget)
get_mastery_for_user(user_id, curriculum_id): Mastery data for the specfied curriculum in the form {'proficiencies' => [competency info], 'mastery' => [mastery info]}

Competencies info has the following fields:

id: Unique competencies ID
name: Name.
description: Description.
city: The city the competencies are associated with.
state: The state the competencies are associated with.
country: The country the competencies are associated with.
organization: The organization the competencies are associated with.

Competency info has the following fields:

id: Unique competency ID.
classification: The name mapped to this percent

Mastery info has the following fields:

percent: The average percent over all competencies
classification: The name mapped to this percent
proficiencies: An array of detailed competency info for the user

Detailed competency info has the following fields:

id: Unique competency ID.
percent: The percent for this competency
classification: The name mapped to this percent
mastered: True if the competency is mastered, otherwise false.
assignments: Array of assignment competency info.

Assignment competency info has the following fields:

id: Unique assignment ID.
percent: Percent for the competency for this assignment
classification: name mapped to this percent.

Sessions

The following functions provide access to login sessions:

get_session_details(user_ids): Array of detailed info about the sessions for the specified users. We currently only provide details of sessions that occurred in the last 30 days.

Session info has the following fields:

id: User ID
count: Number of sessions for this user.
sessions: Array of session info, ordered by ascending login_at time.

Session info has the following fields:

login_at: Time of login
logout_at: Time of logout (can be null if no corresponding logout occurred)
ip_address: IP address of login

Course reports

The following function provides access to course reports:

get_class_report(class_id, constraints): Array of info about the students in the specified course. If you supply optional constraints in the form attribute1=value1&attribute2=value2, only students that satisfy all the constraints are considered.

The following constraints are currently supported:

student_ids: Select the students whose id is in the specified array of ids. If this constraint is omitted, all currently active students are selected.
started_from: Only select students that are not currently deactivated or were not deactivated before the specified time.
to: Only select students who were enrolled before the specified time.
from: Only select students who were enrolled on or after the specified time,

Course report info has the following fields:

student_id: The unique ID of the student.
enrolled_at: When they were enrolled.
started_at: When they first visited the course.
last_visited_at: When they last visited the course.
completed_at: When they completed the course.
score: Their final score in the form {percent: <percentage>, grade: <grade letter>}

Reports

Overview

This set of API calls allows you to prepare, run and download the results of any reports from your portal. The main flow is the following:

Prepare and run a report
Check the report’s status
Download or check the report’s result

All report results run via API can be viewed at any time on the Reports/History tab. Also, the owner of the API key(Execute as) will receive a notification when the report job finishes.

Functions

run_report

Prepare and run the specified report. The LMS will detect and validate all the run options. If the validation process fails, the endpoint will return an error message about the issue. When the validation process succeeds, the endpoint will return the run_report_id. This ID can be used the check the report’s status or to download the results.

Data fields:

report (required):
- for course reports: course_id - an array of ids
  - "class_id": "-1" = all courses
  - "class_id": "-1" = all archived courses
  - "class_id": "-1" = all I teach
- for team reports: team_id - an array of ids
- for organization reports: organization_id - an array of ids
  - "organization_id": "-1" = all organization
- id (required): an existing report’s ID. It can be a custom or a built-in report.
- outpup (required): “CSV”, “HTML”, or “Chart”
- other report specific attributes (required):
run_options (required):
- start_at (required for scheduled reports): the start date of the report
- repeats_scheduled_report (required for scheduled reports with repeat): true
- repeats (required for scheduled reports with repeat): “Minutely”, “Daily”, “Weekly”, “Monthly”, “Yearly”
- repeat_every (required for scheduled reports with repeat): number between 1 and 30
- run (required): “immediately” for immediate jobs and “schedule” for scheduled jobs
- other run options for Scheduled reports (required for scheduled reports)
period (required for reports that use periods, example: Course status, Course attendance, Learner time tracking):
- begin_at: the period’s beginning date (mm/dd/yyyy format)
- end_at: the period’s ending date (mm/dd/yyyy format)
- period_number: number of periods (between 1 and 31)
- period_time: “day”, “week”, “month”, or “year”
- current_period: “day”, “week”, “month”, or “year”
- period_type (required): “Date Range”, “Last Period”, or “Current Period”
- extra required attributes for “Date Range” period:
- extra required attributes for “Last Period” period:
- extra required attributes for “Current Period” period:

Examples:

Scheduled report with repeat

{
  "report": {
       "id": 43,
       "class_id": [11,22,33],
       "output": "CSV"
   },
   "run_options": {
       "run": "schedule",
       "start_at": "2021.02.01 17:03:01",
       "repeats_scheduled_report": true,
       "repeats": "Monthly",
       "repeat_every": 10
   }
}

Scheduled report without repeat

{
    "report": {
       "id": 43,
       "team_id": [11,22,33],
       "output": "HTML"
   },
   "run_options": {
       "run": "schedule",
       "start_at": "2021.02.01 17:03:01"
   }
}

Immediate report

{
    "report": {
       "id": 47,
       "class_id": [1098, 1095, 1092],
       "output": "CSV"
   },
   "run_options": {
       "run": "immediately"
   }
}

Report with “Date Range” period

{
    "report": {
"id": 12750,
"organization_id": -1,
"period":{
   "period_type": "Date Range",
   "begin_at": "01/01/2022",
   "end_at": "02/17/2022"
},
"output": "CSV"
},
"run_options": {
"run": "immediately"
   }
}

Report with “Current Period” period

{
    "report": {
"id": 12750,
"organization_id": -1,
"period":{
   "period_type": "Current Period",
   "current_period": "month"
},
"output": "CSV"
},
"run_options": {
"run": "immediately"
   }
}

Report with “Last Period” period

{
    "report": {
"id": 12750,
"organization_id": -1,
"period":{
   "period_type": "Last Period",
   "period_number": 15,
   "period_time": "week"
},
"output": "CSV"
},
"run_options": {
"run": "immediately"
   }
}

Response:

get_report_status: Use this endpoint to check the report’s status.

Data fields:

run_report_id (required): the same ‘run_report_id’ from the response of the ‘run_report_id’ endpoint

Response:

the status of the report

download_report

Use this endpoint to download the result of the report. This can be used only for CSV reports.

Data fields:

run_report_id (required): the same ‘run_report_id’ from the response of the ‘run_report_id’ endpoint

Response:

a CSV file with the results

Attendance

The following functions provides access to attendance data:

get_attendance(class_id, date_and_time): The attendance data for the specified class at the specific date/time. You can use "date_and_time" param to specify the date and time too, or you can use only the "date" param to specify only the date.
get_all_attendance(class_id): All the attendance data for the specified class.

Attendance data has the following fields:

started_at: The time for the set of attendance records.
records: An array of attendance records for the specific time.

An attendance record has the following fields:

student_id: The unique user ID of the student.
status: If there is attendance data for the student, this will be one of 'OnTime', 'Late', 'Early', 'Absent', 'Excuse', or 'NoExcuse'.
details: If the status is 'Late' or 'Early', this can be the number of minutes that the student was late/early.
excused: True if the student was excused.
note: An optional note.

News feeds

The following functions provide access to news feeds:

post_class_announcement(class_id, message, options): Post the announcement to the class with the specified ID.
post_class_message(class_id, message, options): Post the message to the class with the specified ID.
post_group_announcement(group_id, message, options): Post the announcement to the group with the specified ID.
post_group_message(group_id, message, options): Post the message to the group with the specified ID.
post_site_announcement(message, options): Post the announcement to the site.
post_site_message(message, options): Post the message to the site.

When posting a message, the following options are available:

sticky: If true, make the announcement sticky. False by default. (not available for post_site_message)
submitter_id: If set, post as the user with the specified ID, otherwise post as the invoker of the API.

When posting an announcement, the following options are available:

sticky: If true, make the announcement sticky. False by default.
notify: If true, send a notification as well. False by default.
submitter_id: If set, post as the user with the specified ID, otherwise post as the invoker of the API.

The following additional options are available when posting to the site:

students: If true, send the announcement to all students. False by default.
teachers: If true, send the announcement to all teachers. False by default.
parents: If true, send the announcement to all parents. False by default.
managers: If true, send the announcement to all managers. False by default.

Gamification

The following functions provide access to game information:

get_games_for_site: Array of game info about all site-wide games.
get_games_for_class(class_id): Array of game info about all the games in the specified course.

Game info has the following fields:

id: Unique game ID
name: Name
description: Description
levels: Array of level info of the form ['name' => name, 'points' => points]
enable_leaderboard: True if the leaderboard is enabled, otherwise false.
leaderboard_size: The size of the leaderboard if enabled.
show_to_students: True if the leaderboard should be shown to students, otherwise false.
include_completed_students: True if students that have completed the class should be included in the leaderboard, otherwise false.

The following functions provide player status:

get_status_for_all_players(game_id): Array of player info about all players in the specified game.
get_status_for_players(game_id, user_ids): Array of player info about the specified players in the specified game.

Player info has the following fields:

user_id: ID of the player
points: The player's points.
level: The name of the player's level.
badges: Array of badge info of the form ['id' => badge ID, 'name' => badge name, 'awarded_at' => time]

Ecommerce

The following functions provide access to e-commerce information:

get_all_orders: Array of info for all orders. This function is paginated.
get_orders_with_ids(order_ids): Array of info for orders with the specified ids. This function is paginated.
get_orders_for_organization(organization_id): Array of info for all orders purchased by members of the specified organization. This function is paginated.
get_orders_for_user(user_id): Array of info for all orders purchased by the specified user. This function is paginated.
get_orders_that_match(status, date): Array of info for all orders with specified status (i.e. incomplete) that were created after a specified date.

Order info has the following fields:

id: Unique order ID
user_id: User ID of purchaser
user_name: Name of purchaser
organization_id: Organization ID of purchaser
checkout_at: Time of purchase.
currency: Currency of purchase.
bulk_discount: Amount of bulk discount, if any.
coupon_codes: Coupon codes associated with the order, if any.
items: Array of item info for each item in the order.
total: Total value of the order.
total_without_bulk_discount: Total value of the order without the bulk discount.
verified_at: When the order was verified.
affiliate: If the order was placed through an affiliate link, this object will be present and will contain the id, name, email, organization_id, organization_name fields

Item info has the following fields:

id: Unique ID of item in order
quantity: Quantity of item
unit_cost: Unit code of item
used: Quantity of item used so far
item_id: ID of item (such as ID of course, digital media, etc.)
item_type: Type of item (such as Class, DigitalMedia, Bundle, Subscription, etc.)
item_name: Name of item.
discount_type: Type of discount, if any.
discount: Amount of discount, if any.
coupon_id: ID of coupon applied, if any.
items: If the item is a Bundle, an array of info about the items in the bundle.
total_cost: The total cost of the item purchased.
total_cost_without_discount: The total cost of the item purchased without the discount.
organization_id: ID of the organization associated with the purchased item.
organization_name: Name of the organization associated with the purchased item.
custom fields: Only in the case of courses, any custom fields set for the purchased course will be appended to the list.

Job titles

The following functions provide access to job titles:

get_all_job_titles: Array of info for all the job titles.
get_job_titles_with_ids(job_title_ids): Array of info for all the specified job titles.
get_job_titles_that_match(constraints, page=1): Array of info for all the job titles that match the constraints, which are specified in the form attribute1=value1&attribute2=value2. The supported attributes are job title id and name.This function is paginated.

Job title info has the following fields:

id: Unique job title ID
name: Name
description: Description

The following function allows you to add a job title:

add_job_title(attributes): Add a job title, which are in the form attribute1=value1&attribute2=value2, etc. Returns the ID of the newly added job title.

When adding a job title, the following attributes can be specified:

name: The name of the job title.
description: A description of the job title.
picture: The URL where the picture for the job title should be loaded. If omitted, the default job title picture is used.

The following function allows you to edit a job title:

edit_job_title(job_title_id, attributes): Edit the specified job title, with the attributes to update in the form attribute1=value1&attribute2=value2, etc. Returns the ID of the edited job title. The attributes are the same as the attributes for add_job_title().

The following function allows you to delete job titles:

delete_job_titles(job_title_ids): Delete the job titles with the specified job title IDs. Note that you cannot delete a job title if any users are associated with that job title.

SIS Sync

Overview

This set of API calls allow you to prepare and commit a sync job to update instructors & learners, courses, and who is instructing/enrolled in a course. The main flow is as follows:

Begin a new sync.
Sync instructors if any of their account information has changed.
Sync learners if any of their account information has changed.
Sync courses if any of their information has changed, including who is teaching/enrolled in them.
Commit the sync.
Check the sync status zero or more times to see how it's going.

All sync jobs are tracked in the Admin portal under Admin/SIS. You can view the current sync job and its status, as well as view a history of previous sync jobs. For each sync job, you can get a summary of added, edited and deleted items, and drill down to look at the specific details of each one of these actions and associated data. Sync jobs that are in “Prepared” state can be manually committed by an administrator.

General terms

There are three types of identifiers in the uploaded data: id, sis_id and lms_id:

Id refers to your own unique item id (within the type of item like user or course) that cannot change and is required for add/edit actions.
Sis_id is also, your own unique item id, but can change over time (like a user login id for example), or it could be always the same as id.
Lms_id is the id generated by our LMS, which is unique and doesn’t change. The lms_id is optional, however, if it’s included in the item's JSON, it will take the highest precedence in resolving/matching the object to one in our LMS.

Matching

During the committing of a sync, we use the following rules to find a matching item:

Try to match using the lms_id field if present, else
Try to match using the id field, else
Try to match using the sis_id field, else
Try to match based on the type of item as follows:
1. Instructor: teacher_number, email
2. Learner: student_number, email
3. Course: course_number (Course code)

Instructors and learners have to be present before courses are synced, since a course has references to both instructors and learners, and we need to be able to resolve these references. References to instructors and learners in the course are via their lms_id field.

Functions

The following function begins a new sync:

begin_sync: Start a new Sync job and return a simple JSON object with the sync_id and basic status information.

{
  "sync_id": 4567,
  "status": "Preparing",
  "created_at": “2019-08-08T16:05:44.099Z”,
  “committed_at”: “”,
  "error": ""
}

The following function commits a sync:

commit_sync(sync_id, force=false): Put the specified sync job into a Prepared state and queue the sync to be committed. At this point, the sync data is evaluated and if the LMS detects a large number of items being changed (edited or deleted), it will fail the commit and return an error message, and will leave the sync job in the system in a Prepared status, so an administrator can confirm the changes are appropriate and manually commit the sync job. If you choose to force the commit to proceed regardless of this threshold test, you can include the optional force=true parameter in this call. After the sync job is put in Prepared status, the committing will be queued for execution, which might take a few seconds or a lot longer depending on the amount of the data sync’ed. You can check the status of the sync to check when it’s completed.

The following function cancels a sync:

cancel_sync(sync_id): Terminate the specified sync job and delete it before it has been committed. Once a sync has been committed, it cannot be canceled.

The following function gets a sync status:

sync_status(sync_id) - with valid sync ID: Return the current status of the specified sync job.
sync_status(sync_id) - with invalid sync ID: Returns the "Invalid sync_ID" error message.
sync_status(sync_id) - with no sync ID in the reqeust: Returns the "No active sync was found" error message, or if there is an active sync, returns the sync_.id

A sync status has the following fields:

sync_id: Unique ID of the sync.
status: The status, which can be Committed, Prepared, XXX.
created_at: When the sync was created
committed_at: When the sync was committed
error: A description of an error, if any.

Here is an example:

{
  "sync_id": 4567,
  "status": "Committed",
  "created_at": “2019-08-08T16:05:44.099Z”,
  “committed_at”: “2019-08-08T16:25:44.099Z”,
  "error": ""
}

The following function updates one or more instructors.:

sync_teachers(sync_id, [operations]): Update one or more instructors. For each entry, you can specify to add, edit or delete the specified instructor.

An operation has the following fields:

action: The type of the operation, which can be "add", "edit", or "delete".
data: The top level structure containing the data for the operation.
data.lms_id: LMS id of the instructor.
data.created: Date the instructor account was created.
data.credentials: Structure that contains the instructor credentials.
data.credentials.district_username: The instructor's district user name.
data.email: Email address
data.ext: Structure that contains extensions.
data.ext.custom_fields: Array of custom fields.
data.ext.custom_fields.name: Name of a custom field.
data.ext.custom_fields.value: Value for a custom field.
data.id: Unique and immutable id of the instructor in the SIS.
data.last_modified: Date the instructor account was last modified.
data.name: Structure that contains the user name.
data.name.first: First name.
data.name.last: Last name.
data.name.middle: Middle name.
data.sis_id: SIS id.
data.teacher_number: Instructor number.
data.title: Title of the instructor (such as Mr., Mrs, etc.)

Here is an example:

{
  "data": [
    {
      "action": "add",
      "data": {
        "id": "SIS10",
        "title": "Grade 3 Common Branch Teacher",
        "created": "2017-03-28T16:16:28.915Z",
        "last_modified": "2017-08-08T16:05:44.099Z",
        "name": {
          "first": "Leatha",
          "last": "Abernathy",
          "middle": "D"
        },
        "credentials": {
          "district_username": "abernathy.leatha"
        },
        "teacher_number": "670963",
        "email": "leatha.abernathy@example.org",
        "sis_id": "SIS10",
        "ext": {
          "custom_fields": [
            {
              "name": "My Field",
              "value": "Some value"
               }
          ]
        }
      }
    },
    {
      "action": "edit",
      "data": {
        "lms_id": "280913"
        "email": "spinka.leo@example.net",
        "title": "Grade 3 Common Branch Teacher",
        "ext": {
          "custom_fields": [
            {
              "name": "My Field",
              "value": "Some value"
               }
          ]
        },
        "credentials": {
          "district_username": "spinka_leo"
        },
        "sis_id": "SIS11",
        "teacher_number": "539224",
        "name": {
          "first": "Vlad",
          "last": "Cotorobai"
        },
        "created": "2017-03-28T16:16:28.918Z",
        "last_modified": "2017-08-08T16:05:44.105Z",
        "id": "SIS11"
      }
    },
    {
      "action": "delete",
      "data": {
        "lms_id": "162919"
      }
    }
  ]
}

The following function updates one or more learners:

sync_students(sync_id, [operations]): Update one or more learners. For each entry, you can specify to add, edit or delete the specified learner.

An operation has the following fields:

action: The type of the operation, which can be "add", "edit", or "delete".
data: The top level structure containing the data for the operation.
data.lms_id: LMS id of the learner.
data.created: Date the learner account was created.
data.credentials: Structure containing user credentials.
data.credentials.district_username: The learner's district user name.
data.dob: Date of birth.
data.email: Email address
data.ext: Structure containing extensions.
data.ext.custom_fields: Array of custom fields.
data.ext.custom_fields.name: Name of custom field.
data.ext.custom_fields.value: Value of custom field.
data.gender: Gender
data.grade: Grade level.
data.graduation_year: Year of graduation.
data.hispanic_ethnicity: Hispanic?
data.id: Id of the learner.
data.last_modified: Date learner account was last modified.
data.location: Structure containing learner location.
data.location.address: Street address.
data.location.city: City
data.location.lat: Latitude.
data.location.lon: Longitude.
data.location.state: State.
data.location.zip: Zip code.
data.name: Structure containing learner name.
data.name.first: First name.
data.name.last: Last name.
data.name.middle: Middle name.
data.race: Race.
data.sis_id: SIS id.
data.student_number: Learner number.

Here is an example:

{
  "data": [
    {
      "action": "add",
      "data": {
        "ext": {
          "custom_fields": [
            {
              "name": "My Field",
              "value": "Some value"
               }
          ]
        },
        "location": {
          "state": "",
          "zip": "10459",
          "address": "",
          "city": "",
          "lat": "",
          "lon": ""
        },
        "credentials": {
          "district_username": "stevez33"
        },
        "id": "SISS10",
        "sis_id": "SISS10",
        "email": "z.steve@example.net",
        "last_modified": "2017-08-08T16:05:50.871Z",
        "name": {
          "first": "Steve",
          "last": "Ziemann",
          "middle": "G"
        },
        "student_number": "100095233",
        "gender": "M",
        "created": "2017-03-28T16:16:35.025Z",
        "grade": "Kindergarten",
        "dob": "2/11/2007",
        "graduation_year": "",
        "race": "Black or African American",
        "hispanic_ethnicity": "Y"
      }
    },
    {
      "action": "edit",
      "data": {
        "credentials": {
          "district_username": "douglasw58"
        },
        "created": "2017-03-28T16:16:35.029Z",
        "dob": "6/18/1998",
        "lms_id": "249389",
        "sis_id": "SISS11",
        "race": "Caucasian",
        "graduation_year": "",
        "last_modified": "2019-10-03T16:06:03.857Z",
        "grade": "9",
        "hispanic_ethnicity": "N",
        "district": "58da8a43cc70ab00017a1a87",
        "email": "w_douglas@example.net",
        "ext": {
          "custom_fields": [
            {
              "name": "My Field",
              "value": "Some value"
               }
          ]
        },
        "gender": "X",
        "name": {
          "first": "Student",
          "last": "10",
          "middle": "S"
        },
        "location": {
          "zip": "75020",
          "address": "101 Main St.",
          "city": "Dallas",
          "lat": "",
          "lon": "",
          "state": "TX"
        },
        "student_number": "101565758",
        "id": "SISS11"
      }
    },
    {
      "action": "delete",
      "data": {
        "lms_id": "1198316"
      }
    }
  ]
}

The following function updates one or more courses.

sync_classes(sync_id, [operations]): Update course information. For each entry, you can specify to add, edit or delete the specified course, as well as who is instructing it and who is enrolled.

An operation has the following fields:

action: The type of the operation, which can be "add", "edit", or "delete".
data: The top level structure containing the data for the operation.
data.lms_id: LMS id of course.
data.created: Date course was created.
data.ext: Structure containing extensions.
data.ext.parent_class_id: SIS id of parent course.
data.ext.parent_class_lms_id: LMS id of parent course.
data.ext.custom_fields: Array of custom fields.
data.ext.custom_fields.name: Name of custom field.
data.ext.custom_fields.value: Value of custom field.
data.grade: Grade level of course.
data.id: SIS id of the course.
data.last_modified: Date course was last modified.
data.name: Name of course.
data.period: Period.
data.section_number: Section number.
data.sis_id: Unique SIS id of course.
data.students: Array of SIS ids of all learners enrolled in this course.
data.subject: Subject.
data.teacher: SIS id of the main instructor.
data.teachers: Array of SIS ids of all instructors teaching this course.
data.term: Structure containing term information.
data.term.start_date: Start date of term.
data.term.end_date: End date of term.

Here is an example:

{
  "data": [
    {
      "action": "add",
      "data": {
        "id": "SISC100",
        "sis_id": "SISC100",
        "name": "Sixth Grade Advisory - Madison - 4",
        "subject": "homeroom/advisory",
        "students": [
          "SISS10",
          "SISS11"
        ],
        "created": "2017-03-28T16:16:42.732Z",
        "term": {
          "name": "Summer 2019",
          "start_date": "2019-06-01",
          "end_date": "2019-08-10"
         },
        "grade": "6",
        "teacher": "SIS10",
        "last_modified": "2018-07-10T16:05:39.496Z",
        "course": "5970d4de35e9e69741000277",
        "section_number": "",
        "ext": {
          "parent_class_id": "79277",
          "custom_fields": [
            {
              "name": "My Field",
              "value": "Some value"
               }
          ]
        },
        "teachers": [
          "SIS10"
        ],
        "period": "4"
      }
    },
    {
      "action": "edit",
      "data": {
        "ext": {
          "custom_fields": [
            {
              "name": "My Field",
              "value": "Some value"
             }
          ]
        },
        "id": "SISC1",
        "sis_id": "SISC1",
        "created": "2017-03-28T16:16:42.742Z",
        "grade": "6",
        "teachers": [
          "58da8c5da7a7e5a6470000a8"
        ],
        "course": "5970d4de35e9e69741000278",
        "period": "4",
        "name": "Sixth Grade Advisory - Monroe - 4",
        "section_number": "",
        "subject": "homeroom/advisory",
        "term": {
          "name": "Summer 2019",
          "start_date": "2019-06-01",
          "end_date": "2019-08-10"
         },
        "students": [
          "58da8c63d7dc0ca068000418",
          "58da8c63d7dc0ca068000419",
          "58da8c63d7dc0ca068000453",
          "58da8c65d7dc0ca0680007b3"
        ],
        "last_modified": "2018-07-10T16:05:39.498Z",
        "teacher": "58da8c5da7a7e5a6470000a8",
        "lms_id": "79277"
      }
    },
    {
      "action": "delete",
      "data": {
        "lms_id": "203413"
      }
    }
  ]
}

Related Articles
API 3.0
Introduction Welcome to the help area for API 3.0, the third generation of our Application Programming Interface. API 3.0 implements RESTFUL best practices whenever possible, and includes an OpenAPI 3.0.2 specification so that it can be easily ...
PHP
Overview Our open source PHP client provides a simple way to invoke the API from PHP. To download the PHP client, right-click /clients/lms_api.php and then save the contents to your local computer. Example: code The following example lists all the ...
Javascript
Overview Our open source Javascript client provides a simple way to invoke the API from Javascript. To download the Javascript client, right-click /javascripts/lms_api.js and the save the contents to your local computer. The Javascript client is ...
Ruby
Our open source Ruby client provides a simple way to invoke the API from Ruby. Overview To download the Ruby client, right-click /clients/lms_api.rb and the save the contents to your local computer. Example: code The following example lists all the ...
Java
Overview Our open source Java client provides a simple way to invoke the API from Java. Installation You can download the Java API from/clients/java-api-client.zip and include it in your project. Dependencies: http://unirest.io/java.html and ...

API 1.0

API 1.0

Overview

Getting started

Client libraries

Rate limiting

Protocols

Pagination

Version

Authentication

Users

Courses

Course Templates

Modules

Assignments

Grades

Organizations

Groups

Paths

Resources

Certificates

Competencies

Mastery

Sessions

Course reports

Reports

Overview

Functions

Attendance

News feeds

Gamification

Ecommerce

Job titles

SIS Sync

Overview

General terms

Matching

Functions

Related Articles

API 3.0

PHP

Javascript

Ruby

Java