Introduction
Welcome to Class's developer platform. Here you can learn how to use our API to integrate Class into your organization's virtual learning experience.
With Class's API, you can perform bulk operations, automate set-up and maintenance of your Class installation, and easily sync Class data into your organization’s systems of record.
This platform is organized to help you access, create, and update:
The following sections contain detailed information on how to get started.
Preparing to Use the API
To use the Class API, you or your organization's Class administrator will need to create an API key, retrieve the secret used to authorize requests, and find your organization's base URL -- a unique domain that will serve as the first part of all API calls.
Creating API Key(s)
Class uses API keys to allow access to the API. A new Class API key can be registered through the Class admin portal, in the API Keys section. When creating keys, the administrator can specify scopes (which API methods can be accessed) as well as an optional expiration date for that key.
Create a key with scopes in the Admin UI.
Recording the Secret
Once you create the key and click Save
, you will see a one-time only dialog box with the new API key's secret. Be sure to save this information, as you will not be able to access it later. You will also need to provide the secret to anyone else using this key to access the API.
Creating a key generates a secret you will need for calling the APIs.
Determining Your Base URL
Class assigns your organization a unique base URL that you will need to access any endpoints in the Class API. To find your base URL once you have created a key, go to the API Keys page and click on the name of the key you just created. This will open the Edit API Key page. You will find the base URL listed below the key's description and expiration date.
Find your organization's base URL on the Edit API Key page.
Once you have created the key and recorded the secret and the base URL, you have all the information you will need to get started.
Making an API Call
Example of a Get Class Info request:
GET [api_base_url]/api/v1/classes?class_id=01cceb4b-afce-4703-a842-6b41fad111b5
Authorization: Bearer [api_key_secret]
Example Response:
Status: 200
[
{
"class_id": "01cceb4b-afce-4703-a842-6b41fad111b5",
"ext_class_id": "demo-1",
"class_name": "Demo Class",
"class_description": "A demonstration of Class",
"meeting_id": "92117646134",
"host": "Anne Malley",
"invite_link": "https://mydemo.class.com/class.html?class_uuid=01cceb4b-afce-4703-a842-6b41fad111b5",
"password": "a1demo"
}
]
To make an API call, you will need to decide which endpoint to use, and combine the method and path from that endpoint with your base URL and secret.
Specifically, follow these steps to construct your request and make your API call:
- Choose your endpoint. (i.e., Create a Class or Get Attendance). For a full list of endpoints, see the table in the next section.
- Find the correct method for your endpoint (GET, POST, PUT, or DELETE) as listed in the sections below.
- Generate the url for the http request by combining your organization's base URL with the path of the endpoint and any desired query parameters supported by your chosen endpoints.
- Add the Authorization header using the Bearer authorization scheme.
- If your endpoint requires a request body with additional information specific to your request (i.e. the name of the class you wish to create), add that as well. This should be formatted as a JSON object.
- Make the constructed http request using your preferred programming language and library.
- Once you have made the http request, check if your call was successful, based on the returned status code. A response status in the 200s indicates success; a response status of 400 or above indicates an error. See the Error Codes table below for an explanation of each error code.
Understanding Data Formats
Many Class API calls and responses use data in specific formats. The following are some notes to keep in mind.
Multiple Identifiers
Some Class API endpoints (i.e., Classes, Reporting, Templates and Users) may accept multiple identifiers. In these cases, you are required to select one and only one identifier. For example, when calling "Remove a User", you are required to identify a user by 'id', 'email' or 'ext_user_id' -- but you may not use more than one of these. There is no preferred identifier; use whichever best suits your organization's use case.
Unix Time
Some API calls may also require you to specify a date and time. Note that Class uses an integer representing Unix Time, the number of seconds that have elapsed since the Unix epoch (00:00:00 UTC on January 1, 1970). Many utilities are available to help convert dates to and from Unix Time.
Time Zone
Some API calls require you to specify a time zone. Class uses the Time Zone ID values from the Time Zone Database to represent time zones, such as 'America/Los_Angeles' for Pacific Time. A full list of supported timezones can be found in the Class application in the dropdown menu for "Time Zone" when creating a class.
Pagination
Example of a paginated request:
GET [api_base_url]/api/v1/users?page=1&limit=20
Authorization: Bearer [api_key_secret]
Example Response:
Status: 200
{
"data": [
{
"id": 1,
"ext_user_id": null,
"email": "john@mail.com",
"user_name": "John Smith",
"roles": [
"instructor"
],
"is_zoom_configured": true
},
{
"id": 2,
"ext_user_id": "555",
"email": "jane@mail.com",
"user_name": "Jane Smith",
"roles": [
"instructor"
],
"is_zoom_configured": false
}
],
"pagination": {
"total_records": 100,
"current_page": 1,
"total_pages": 5,
"next_page": 2,
"prev_page": null
}
}
Pagination is used to divide a large set of data into manageable chunks or pages. These parameters allow you to control which page of data you want to retrieve and how many records are displayed per page. Pagination is only available on select endpoints.
Attribute | Type | Description |
---|---|---|
page |
number | The page number to retrieve. Must be a positive integer. |
limit |
number | The number of records to be displayed on each page. Must be a positive integer. Maximum: 1,000. |
Choosing Endpoints & Scopes
The table below provides an overview of all available endpoints along with the scope(s) you are required to select when creating your API key.
Summary of Available Endpoints
Endpoint | Required Scope | Method & Path |
---|---|---|
Classes | ||
Create a Class | class:write | POST /api/v1/classes |
Get All Classes Info | class:read | GET /api/v1/classes |
Get Single Class Info | class:read | GET /api/v1/classes |
Update a Class | class:write | PATCH /api/v1/classes |
Remove a Class | class:write | DELETE /api/v1/classes |
Enrollments | ||
Create an Enrollment | enrollment:write | POST /api/v1/class/enrollments |
Get Enrollments | enrollment:read | GET /api/v1/class/enrollments |
Update an Enrollment | enrollment:write | PUT /api/v1/class/enrollments |
Remove an Enrollment | enrollment:write | DELETE /api/v1/class/enrollments |
Launch | ||
Get a Launch Link | enrollment:read | GET /api/v1/class/enrollments/launch |
Reporting | ||
Get Attendance | attendance:read | GET /api/v1/reporting/attendance |
Get Metrics | metrics:read | GET /api/v1/reporting/metrics |
Schedules | ||
Add a Class Date | schedule:write | POST /api/v1/schedules |
Get Class Dates | schedule:read | GET /api/v1/schedules |
Remove a Class Date | schedule:write | DELETE /api/v1/schedules |
Templates | ||
Create a Template | template:write | POST /api/v1/templates |
Get All Templates | template:read | GET /api/v1/templates |
Get a Template | template:read | GET /api/v1/templates |
Update a Template | template:write | PATCH /api/v1/templates |
Remove a Template | template:write | DELETE /api/v1/templates |
Users | ||
Create or Update a User | user:write | PUT /api/v1/users |
Get All Users | user:read | GET /api/v1/users |
Get a User | user:read | GET /api/v1/users |
Remove a User | user:write | DELETE /api/v1/users |
The following sections provide information specific to each endpoint as well as examples of how to make each type of API call. See the Parameters table in each section for a summary of information used in the request body, as well whether each field is required or optional.
Classes
There are three Classes endpoints:
You can use these endpoints when creating a new class or when you wish to gather information on a single class or all classes within your organization.
Create a Class
Example Request:
POST [api-base-url]/api/v1/classes
Example Body:
{
"email": "anne.malley@demo.com",
"first_name": "Anne",
"last_name": "Malley",
"timezone": "America/Los_Angeles",
"ext_class_id": "demo-1",
"class_name": "Demo Class",
"class_description": "A demonstration of Class",
"meeting_passcode": "a1demo",
"session_times": [
{
"start_time": 1631810954,
"end_time": 1631814554
}
],
"settings": {
"waiting_room": false,
"join_before_host": true,
"jbh_time": 0
},
"additional_instructors": [
{
"email": "james.lloyd@demo.com"
},
{
"email": "chaya.meyer@demo.com"
}
]
}
Example Response:
Status: 201
{
"meeting_id": "92117646134",
"invite_link": "https://mydemo.class.com/class.html?class_uuid=01cceb4b-afce-4703-a842-6b41fad111b5"
}
Status: 201 (Deferred)
{
"class_deferred_id": 7,
"class_id": "a1cceb4b-afce-4703-a842-6b41fad111b5",
"ext_id": "demo-1"
}
Method & Path: POST /api/v1/classes
Required Scope: class:write
Use the Create a Class endpoint to create a new class. You will need to add information about the instructor, the class, and optionally, a class schedule.
Request Body
Attribute | Type | Required? | Description |
---|---|---|---|
String | Yes | Instructor's e-mail | |
first_name | String | Yes | Instructor's first name |
last_name | String | Yes | Instructor's last name |
display_name | String | No | Instructor's name as displayed in the class |
ext_class_id | String | No | Your organization's assigned identifier for the class |
class_name | String | Yes | Name of the class |
class_description | String | No | Description of the class |
template_id | Integer | No | Identifier for template to populate class contents |
meeting_passcode | String | No | Passcode needed to join the class meeting |
timezone | String | Yes | Time zone class is held in |
session_times | Object | No | A json array of objects, each corresponding to the times of a class session |
session_times.start_time | Integer | Yes | Time at which the class session starts, in Unix Time |
session_times.end_time | Integer | Yes | Time at which the class session ends, in Unix Time |
settings.waiting_room | Boolean | No | Flag indicating whether waiting room is enabled |
settings.join_before_host | Boolean | No | Flag indicating whether participants can join before the meeting host |
settings.jbh_time | Integer | No | Number of minutes before start time participants can join [0, 5, 10] |
additional_instructors | Array | body | List of additional instructors |
additional_instructors[{email}] | String | body | E-mail of an additional instructor |
Get All Classes Info
Example Request:
GET [api-base-url]/api/v1/classes
GET [api-base-url]/api/v1/classes?deferred=true
Example Response:
Status: 200
[
{
"class_id": "01cceb4b-afce-4703-a842-6b41fad111b5",
"ext_class_id": "demo-1",
"class_name": "Demo Class",
"class_description": "A demonstration of Class",
"meeting_id": "92117646134",
"host": "Anne Malley",
"invite_link": "https://mydemo.class.com/class.html?class_uuid=01cceb4b-afce-4703-a842-6b41fad111b5",
"password": "a1demo"
},
{
"class_id": "a1cceb4b-afce-4703-a842-6b41fad111b5",
"ext_class_id": "demo-2",
"class_name": "Another Demo Class",
"class_description": "Another demonstration of Class",
"meeting_id": "92117646135",
"host": "James Lloyd",
"invite_link": "https://mydemo.class.com/class.html?class_uuid=a1cceb4b-afce-4703-a842-6b41fad111b5",
"password": "demob2"
}
]
Status: 200 (deferred)
[
{
"class_deferred_id": 100,
"class_id": "01cceb4b-afce-4703-a842-6b41fad111b5",
"ext_class_id": "demo-1",
"email": "anne.malley@demo.com",
"class_name": "Demo Class",
"class_description": "A demonstration of Class",
"created_at": "2023-03-03T14:48:06.312Z",
"updated_at": "2023-03-03T14:48:06.312Z"
},
{
"class_deferred_id": 101,
"class_id": "fd856d46-fd2f-4e2f-bfb6-132f741c0bf4",
"ext_class_id": "demo-2",
"email": "james.lloyd@demo.com",
"class_name": "Another Demo Class",
"class_description": "Another demonstration of Class",
"created_at": "2023-03-03T14:49:06.312Z",
"updated_at": "2023-03-03T14:49:06.312Z"
}
]
Method & Path: GET /api/v1/classes
Required Scope: class:read
Use the Get All Classes Info endpoint to return specific information (i.e. meeting id, host, invite link, etc.) on all of your organization's classes. This endpoint doesn't require data in the request body or request parameters.
Query Parameters
Param | Type | Required? | Description |
---|---|---|---|
deferred | boolean | No | Signals if you are querying deferred or scheduled class records. Defaults to false |
Get Single Class Info
Example Requests:
GET [api-base-url]/api/v1/classes?class_id=01cceb4b-afce-4703-a842-6b41fad111b5
GET [api-base-url]/api/v1/classes?ext_class_id=demo-1
GET [api-base-url]/api/v1/classes?deferred=true&class_id=01cceb4b-afce-4703-a842-6b41fad111b5
GET [api-base-url]/api/v1/classes?deferred=true&ext_class_id=demo-1
Example Response:
Status: 200
[
{
"class_id": "01cceb4b-afce-4703-a842-6b41fad111b5",
"ext_class_id": "demo-1",
"class_name": "Demo Class",
"class_description": "A demonstration of Class",
"meeting_id": "92117646134",
"host": "Anne Malley",
"invite_link": "https://mydemo.class.com/class.html?class_uuid=01cceb4b-afce-4703-a842-6b41fad111b5",
"password": "a1demo"
}
]
Status: 200 (deferred)
[
{
"class_deferred_id": 100,
"class_id": "01cceb4b-afce-4703-a842-6b41fad111b5",
"ext_class_id": "demo-1",
"email": "anne.malley@demo.com",
"class_name": "Demo Class",
"class_description": "A demonstration of Class",
"created_at": "2023-03-03T14:48:06.312Z",
"updated_at": "2023-03-03T14:48:06.312Z"
}
]
Method & Path: GET /api/v1/classes
Required Scope: class:read
Use the Get Single Class Info endpoint to return specific information (i.e. meeting id, host, invite link, etc.) for a particular class. This endpoint doesn't require data in the request body, but requires a query parameter to identify the class, as summarized in the table below.
Query Parameters
Param | Type | Required? | Description |
---|---|---|---|
class_id | String | Yes* | Class's automatically-generated UUID for the class |
ext_class_id | String | Yes* | Your organization's assigned identifier for the class (specified during class creation) |
deferred | boolean | No | Signals if you're querying "deferred" or "scheduled" class record. Defaults to false |
Update a Class
Example Request:
PATCH [api-base-url]/api/v1/classes
Example Body:
{
"ext_class_id": "demo-1",
"class_name": "Demo class extended",
"class_description": "Updated description text"
}
Example Response:
Status: 200
{
"class_id": "01cceb4b-afce-4703-a842-6b41fad111b5",
"ext_class_id": "demo-1",
"class_name": "Demo class extended",
"class_description": "Updated description text",
"meeting_id": "92117646134",
"host": "Anne Malley",
"invite_link": "https://mydemo.class.com/class.html?class_uuid=01cceb4b-afce-4703-a842-6b41fad111b5",
"password": "a1demo"
}
Status: 200 (deferred)
[
{
"class_deferred_id": 100,
"class_id": "01cceb4b-afce-4703-a842-6b41fad111b5",
"ext_class_id": "demo-1",
"email": "anne.malley@demo.com",
"class_name": "Demo class extended",
"class_description": "Updated description text",
"created_at": "2023-03-03T14:48:06.312Z",
"updated_at": "2023-03-03T14:48:06.312Z"
}
]
Method & Path: PATCH /api/v1/classes
Required Scope: class:write
Use the Update a Class endpoint to update an existing class. Only a small subset of attributes is allowed for update.
Request Body
Attribute | Type | Required? | Description |
---|---|---|---|
class_id | String | Yes* | Class's automatically-generated UUID for the class |
ext_class_id | String | Yes* | Your organization's assigned identifier for the class |
class_deferred_id | String | Yes* | Class's automatically-generated ID for the deferred class |
class_name | String | No | Name of the class |
class_description | String | No | Description of the class |
Remove a Class
Example Request:
DELETE [api-base-url]/api/v1/classes?class_id=01cceb4b-afce-4703-a842-6b41fad111b5
DELETE [api-base-url]/api/v1/classes?ext_class_id=demo-1
DELETE [api-base-url]/api/v1/classes?class_deferred_id=100
Example Response:
Status: 200
{
"message": "Success"
}
Method & Path: DELETE /api/v1/classes
Required Scope: class:write
Use the Remove a Class endpoint to delete an existing class.
Query Parameters
Param | Type | Required? | Description |
---|---|---|---|
class_id | String | Yes* | Class's automatically-generated UUID for the class |
ext_class_id | String | Yes* | Your organization's assigned identifier for the class (specified during class creation) |
class_deferred_id | String | Yes* | Class's automatically-generated ID for the deferred class |
Enrollments
There are four Enrollments endpoints:
You can use these endpoints when adding or modifying a class's enrollments, as well as retrieving all the enrollments for a particular class.
Create an Enrollment
Example Request:
POST [api-base-url]/api/v1/class/enrollments
Example Body:
{
"email": "francisco.beck@demo.com",
"ext_class_id": "074c697e-e20b-4da8-9361-1b707137d6e3",
"ext_person_id": "f.beck",
"first_name": "Francisco",
"last_name": "Beck",
"role": "student",
"display_name": "Francisco Beck"
}
Example Response:
Status: 200
{
"student_id": "abcc140a-3462-4950-9ab7-c826fbf2376f",
"meeting_id": "95556910000",
"first_name": "Francisco",
"last_name": "Beck",
"user_name": "Francisco Beck",
"role": "student",
"email": "francisco.beck@demo.com",
"ext_person_id": "f.beck"
}
Status: 200 (Deferred)
{
"id": 8,
"class_deferred_id": "7",
"email_user": "francisco.beck@demo.com",
"enroll_params": {
"pod": {
"name": "pod-3",
"region": "us-east-1",
"account": "mydemo",
"environment": "dev",
"databaseName": "customer_mydemo"
},
"class": {
"ext_id": "074c697e-e20b-4da8-9361-1b707137d6e3"
}
},
"user": {
"role": "student",
"email": "francisco.beck@demo.com",
"last_name": "Beck",
"user_name": "Francicso Beck",
"first_name": "Francisco",
"ext_person_id": "f.beck"
},
"created_at": "2022-04-06T03:20:18.145Z",
"updated_at": "2022-04-06T03:20:18.142Z",
"role": "student"
}
Method & Path: POST /api/v1/class/enrollments
Required Scope: enrollment:write
Use the Create an Enrollment endpoint to associate users with a specific class.
Request Body
Attribute | Type | Required? | Description |
---|---|---|---|
class_id | String | NoÂą | Class's automatically-generated UUID for the class |
ext_class_id | String | NoÂą | Your organization's assigned identifier for the class (specified during class creation) |
ext_person_id | String | No² | Your organization's assigned identifier for the user (specified during user creation) |
String | No² | User's e-mail | |
first_name | String | Yes | User's first name |
last_name | String | Yes | User's last name |
role | String | No | User's role [student, assistant, teacher]; defaults to student if not provided |
display_name | String | No | User's name as displayed in the class |
Get Enrollments
Example Request:
GET [api-base-url]/api/v1/class/enrollments?class_id=01cceb4b-afce-4703-a842-6b41fad111b5
GET [api-base-url]/api/v1/class/enrollments?ext_class_id=074c697e-e20b-4da8-9361-1b707137d6e3
Example Response:
Status: 200
[
{
"student_id": "20cc140a-3462-4950-9ab7-c826fbf2376e",
"meeting_id": "8456209194",
"user_name": "Anne Malley",
"first_name": "Anne",
"last_name": "Malley",
"email": "anne.malley@demo.com",
"ext_person_id": "a.malley",
"role": "teacher"
},
{
"student_id": "abcc140a-3462-4950-9ab7-c826fbf2376f",
"meeting_id": "8456209194",
"user_name": "Francisco Beck",
"first_name": "Francisco",
"last_name": "Beck",
"email": "francisco.beck@demo.com",
"ext_person_id": "f.beck",
"role": "student"
}
]
Method & Path: GET /api/v1/class/enrollments
Required Scope: enrollment:read
Use the Get Enrollments endpoint to return all enrollments for a specific class. This endpoint doesn't require data in the request body but requires a query parameter to identify the class, as summarized in the table below.
Query Parameters
Param | Type | Required? | Description |
---|---|---|---|
class_id | String | NoÂą | Class's automatically-generated UUID for the class |
ext_class_id | String | NoÂą | Your organization's assigned identifier for the class (specified during class creation) |
Update an Enrollment
Example Request:
PUT [api-base-url]/api/v1/class/enrollments
Example Body:
{
"email": "kayla.becker@demo.com",
"ext_class_id": "074c697e-e20b-4da8-9361-1b707137d6e3",
"ext_person_id": "k.becker",
"first_name": "Kayla",
"last_name": "Becker",
"role": "student",
"display_name": "Kayla Becker"
}
Example Response:
Status: 200
{
"student_id": "abcc140a-3462-4950-9ab7-c826fbf2376f",
"ext_person_id": "k.becker",
"meeting_id": "95556910000",
"first_name": "Kayla",
"last_name": "Becker",
"user_name": "Kayla Becker",
"role": "student",
"email": "kayla.becker@demo.com"
}
Method & Path: PUT /api/v1/class/enrollments
Required Scope: enrollment:write
Use the Update an Enrollment endpoint to modify information such as name, email, or role for an enrolled user in a specified class.
Request Body
Attribute | Type | Required? | Description |
---|---|---|---|
class_id | String | NoÂą | Class's automatically-generated UUID for the class |
ext_class_id | String | NoÂą | Your organization's assigned identifier for the class (specified during class creation) |
student_id | String | No² | Class's automatically-generated UUID for the user |
ext_person_id | String | No² | Your organization's assigned identifier for the user (specified during user creation) |
String | No² | User's e-mail | |
first_name | String | Yes | User's first name |
last_name | String | Yes | User's last name |
role | String | No | User's role [student, assistant, teacher]; defaults to student if not provided |
display_name | String | No | User's name as displayed in the class |
Remove an Enrollment
Example Request:
DELETE [api-base-url]/api/v1/class/enrollments
Example Body:
{
"email": "jordan.day@demo.com",
"ext_class_id": "074c697e-e20b-4da8-9361-1b707137d6e3"
}
Example Response:
Status: 200
{
"message": "Success"
}
Method & Path: DELETE /api/v1/class/enrollments
Required Scope: enrollment:write
Use the Remove an Enrollment endpoint to delete an enrollment from a specified class.
Request Body
Attribute | Type | Required? | Description |
---|---|---|---|
class_id | String | NoÂą | Class's automatically-generated UUID for the class |
ext_class_id | String | NoÂą | Your organization's assigned identifier for the class (specified during class creation) |
student_id | String | No² | Class's automatically-generated UUID for the user |
ext_person_id | String | No² | Your organization's assigned identifier for the user (specified during user creation) |
String | No² | User's e-mail |
Launch
There is a single Launch endpoint:
You can use this endpoint to get a user-specific launch URL into a meeting for an enrolled user.
Get a Launch Link
Example Request:
GET [api-base-url]/api/v1/class/enrollments/launch?ext_class_id=demo-1&ext_person_id=f.beck
GET [api-base-url]/api/v1/class/enrollments/launch?class_id=074c697e-e20b-4da8-9361-1b707137d6e3&email=francisco.beck@demo.com
Example Response:
Status: 200
{
"launch_url": "https://school.class.com/class.html?class_uuid=01cceb4b-afce-4703-a842-6b41fad111b5&student_id=1234&username=Francisco+Beck&code=c282d896-5603-4ce3-8632-dd5d18cd2dad"
}
Method & Path: GET /api/v1/class/enrollments/launch
Required Scope: enrollment:read
Use the Get Enrollments Launch endpoint to return a URL of a launch link for specific user and class. This endpoint doesn't require data in the request body but requires query parameters to identify the class and user, as summarized in the table below.
Query Parameters
Param | Type | Required? | Description |
---|---|---|---|
class_id | String | Yes* | Class's automatically-generated UUID for the class |
ext_class_id | String | Yes* | Your organization's assigned identifier for the class (specified during class creation) |
String | Yes** | User's e-mail | |
ext_person_id | String | Yes** | Your organization's assigned identifier for the user (specified during user creation) |
Reporting
There are two Reporting endpoints:
You can use these endpoints to return attendance and activity metrics for all users in a particular class.
Get Attendance
Example Request:
GET [api-base-url]/api/v1/reporting/attendance?class_id=01cceb4b-afce-4703-a842-6b41fad111b5
GET [api-base-url]/api/v1/reporting/attendance?ext_class_id=111
Example Response:
Status: 200
{
"class_id": "01cceb4b-afce-4703-a842-6b41fad111b5",
"sessions": [
{
"session_id": "685a0e1e-698d-4961-9461-2aabae0be4b2",
"start_time": "2021-02-22T19:02:00.000Z",
"end_time": "2021-02-22T20:02:00.000Z",
"students": [
{
"student_id": "abcc140a-3462-4950-9ab7-c826fbf2376f",
"email": "francisco.beck@demo.com",
"ext_person_id": null,
"present": false,
"tardy": false,
"join_time": null,
"leave_time": null
},
{
"student_id": "dbcc140a-3462-4950-9ab7-c826fbf237ab",
"email": "kayla.becker@demo.com",
"ext_person_id": "k.beck",
"present": false,
"tardy": false,
"join_time": null,
"leave_time": null
},
{
"student_id": "efcc140a-3462-4950-9ab7-c826fbf23cba",
"email": null,
"ext_person_id": "j.day",
"present": false,
"tardy": false,
"join_time": null,
"leave_time": null
}
]
}
]
}
Method & Path: GET /api/v1/reporting/attendance
Required Scope: attendance:read
Use the Get Attendance endpoint to return attendance data for all users in a specific class. This endpoint doesn't require data in the request body but requires a query parameter to identify the class, as summarized in the table below.
Query Parameters
Param | Type | Required? | Description |
---|---|---|---|
class_id | String | Yes* | Class's automatically-generated UUID for the class |
ext_class_id | String | Yes* | Your organization's assigned identifier for the class (specified during class creation) |
Get Metrics
Example Request:
GET [api-base-url]/api/v1/reporting/metrics?class_id=ab1727de-8e17-4d90-b26e-24a4c634cff7&starting_after=1655315424
GET [api-base-url]/api/v1/reporting/metrics?ext_class_id=ab1727de-8e17-4d90-b26e-24a4c634cff7
Example Responses:
Status: 200
[
{
"student_id": "abcc140a-3462-4950-9ab7-c826fbf2376f",
"email": "francisco.beck@demo.com",
"ext_person_id": null,
"event_start": "2022-06-15T17:43:40.196Z",
"event_end": "2022-06-15T17:53:40.197Z",
"event_duration": 36000,
"event_type": "FOCUSED",
"event_value": "true"
},
{
"student_id": "abcc140a-3462-4950-9ab7-c826fbf2376f",
"email": "francisco.beck@demo.com",
"ext_person_id": null,
"event_start": "2022-06-15T17:43:40.196Z",
"event_end": "2022-06-15T17:53:40.197Z",
"event_duration": 36000,
"event_type": "IS_TALKING",
"event_value": "true"
},
{
...
},
{
...
}
]
Method & Path: GET /api/v1/reporting/metrics
Required Scope: metrics:read
Use the Get Metrics endpoint to return all activity data (i.e. hand raises, speaking time, etc.) for all users in a specific class. This endpoint doesn't require data in the request body but requires a query parameter to identify the class, as summarized in the table below.
Query Parameters
Param | Type | Required? | Description |
---|---|---|---|
class_id | String | Yes* | Class's automatically-generated UUID for the class |
ext_class_id | String | Yes* | Your organization's assigned identifier for the class (specified during class creation) |
starting_after | Integer | No | Query events starting after Unix timestamp (seconds) |
ending_before | Integer | No | Query events ending before Unix timestamp (seconds) |
limit | Integer | No | Number of events to retrieve (max 1000) |
The following table provides a summary of all activity event types that will be returned by a Get Metricsrequest, as well as possible return values. Each activity entry will include user identifying information, event info (type and value), as well as start and end time and duration.
Event Type | Possible Return Values | Notes |
---|---|---|
ATTENDANCE | true | |
FEEDBACK | clap | |
coffee | Need break | |
dislike | ||
faster | Go faster | |
like | ||
no_mark | No | |
question | ||
slower | Go slower | |
time | Away | |
yes_mark | Yes | |
FOCUSED | true, false | |
IS_AUDIO_MUTED | true, false | |
IS_TALKING | true, false | |
IS_VIDEO_ON | true, false | |
PRESENTING | true, false | |
RAISED_HAND | 0 | Hand not raised |
1 | Hand raised | |
REACTION | clap | |
crying | ||
laughing | ||
thumbup | ||
SPOTLIGHT | true, false | |
STARS | 0, 1, 2, 3 | Number of stars awarded to user |
Schedules
There are three Schedules endpoints:
When creating your class, you may have already added information on a class's scheduled meeting dates. You can use the Schedules endpoints to add or remove class dates, or to return a list of all scheduled meetings for a particular class.
Schedules may also be applied to deferred classes.
Add a Class Date
Example Request:
POST [api-base-url]/api/v1/schedules
Example Body:
{
"class_id": "01cceb4b-afce-4703-a842-6b41fad00000",
"start_time": 1654787671,
"end_time": 1654874071,
"timezone": "America/Los_Angeles"
}
Example Response:
Status: 200
{
"schedule_id": "8ce1adbf-e60d-4606-8ad2-69f57d0ed571"
}
Method & Path: POST /api/v1/schedules
Required Scope: schedule:write
Use this endpoint each time you want to modify a class's schedule by adding a meeting date.
Request Body
Attribute | Type | Required? | Description |
---|---|---|---|
class_id | String | Yes | Class's automatically-generated UUID for the class. May point to either regular or deferred class |
start_time | Integer | Yes | Time at which the class session starts, in Unix Time |
end_time | Integer | Yes | Time at which the class session ends, in Unix Time |
timezone | String | Yes | Time zone class is held in |
Get Class Dates
Example Request:
GET [api-base-url]/api/v1/schedules?class_id=01cceb4b-afce-4703-a842-6b41fad00000
Example Response:
Status: 200
[
{
"schedule_id": "080911e5-1770-4db2-95bf-f11659dd480d",
"class_id": "01cceb4b-afce-4703-a842-6b41fad00000",
"start_time": 1628859600,
"end_time": 1628920800
},
{
"schedule_id": "a208762a-c1ae-4c71-8f42-7e0a33a86c2e",
"class_id": "01cceb4b-afce-4703-a842-6b41fad00000",
"start_time": 1628946000,
"end_time": 1629007200
}
]
Method & Path: GET /api/v1/schedules
Required Scope: schedule:read
Use this endpoint to return a list of all scheduled meeting dates for a particular class. This endpoint doesn't require data in the request body but requires a query parameter to identify the class, as summarized in the table below.
Query Parameters
Param | Type | Required? | Description |
---|---|---|---|
class_id | String | Yes | Class's automatically-generated UUID for the class |
Remove a Class Date
Example Request:
DELETE [api-base-url]/api/v1/schedules?schedule_id=a208762a-c1ae-4c71-8f42-7e0a33a86c2e
Example Response:
Status: 200
{
"message": "Success"
}
Method & Path: DELETE /api/v1/schedules
Required Scope: schedule:write
Use this endpoint each time you want to modify a class's schedule by removing a meeting date. This endpoint doesn't require data in the request body but requires a query parameter to identify the meeting dates, as summarized in the table below.
Note that this endpoint requires a schedule_id for a specific meeting date for a particular class. You can find this id in the response body of both the Create a Class Date and Get Class Dates endpoints.
Query Parameters
Param | Type | Required? | Description |
---|---|---|---|
schedule_id | String | Yes | Unique, Class-generated schedule identifier for a particular session of a particular class |
Templates
There are five Templates endpoints:
Class templates allow you to automate your workflow by storing and reusing class components such as assignments, quizzes, and polls. You can then include this content for future offerings of the same class.
Create a Template
Example Request:
POST [api-base-url]/api/v1/templates
Example Body:
{
"name": "Template Name",
"description": "A Template Description",
"status": "draft"
}
Example Response:
Status: 201
{
"template_id": "8ce1adbf-e60d-4606-8ad2-69f57d0ed571",
"name": "Template Name",
"description": "A Template Description",
"status": "draft"
}
Method & Path: POST /api/v1/templates
Required Scope: template:write
Use this endpoint to create a new class template.
Request Body
Attribute | Type | Required? | Description |
---|---|---|---|
name | String | Yes | Template's name |
description | String | No | Template's description |
status | String | No | Template's status [published, draft]. Note that this attribute defaults to published if not specified |
Get All Templates
Example Request:
GET [api-base-url]/api/v1/templates
Example Response:
Status: 200
[
{
"template_id": "8ce1adbf-e60d-4606-8ad2-69f57d0ed571",
"name": "Template Name",
"description": "A Template Description",
"status": "draft"
},
{
"template_id": "7ce1adbf-e60d-4606-8ad2-69f57d0ed572",
"name": "Template Name 2",
"description": "A Template Description 2",
"status": "published"
}
]
Method & Path: GET /api/v1/templates
Required Scope: template:read
Use the Get All Templates endpoint to return a list of all available templates. This endpoint doesn't require data in the request body or request parameters.
Get a Template
Example Request:
GET [api-base-url]/api/v1/templates?template_id=01cceb4b-afce-4703-a842-6b41fad00000
Example Response:
Status: 200
[
{
"template_id": "8ce1adbf-e60d-4606-8ad2-69f57d0ed571",
"name": "Template Name",
"description": "A Template Description",
"status": "draft"
}
]
Method & Path: GET /api/v1/templates
Required Scope: template:read
Use the Get a Template endpoint to return the name, description, and status for a specific template. This endpoint doesn't require data in the request body, but requires a query parameter to identify the template, as summarized in the table below.
Note that this endpoint requires a template_id. You can find this id in the response body of both the Create a Template and Get a Template endpoints.
Query Parameters
Param | Type | Required? | Description |
---|---|---|---|
template_id | String | Yes | Unique, Class-generated identifier for template |
Update a Template
Example Request:
PATCH [api-base-url]/api/v1/templates
Example Body:
{
"template_id": "8ce1adbf-e60d-4606-8ad2-69f57d0ed571",
"name": "New template Name",
"description": "A New Template Description",
"status": "draft"
}
Example Response:
Status: 200
{
"template_id": "8ce1adbf-e60d-4606-8ad2-69f57d0ed571",
"name": "New template Name",
"description": "A New Template Description",
"status": "draft"
}
Method & Path: PATCH /api/v1/templates
Required Scope: template:write
Use the Update a Template endpoint to modify name, description, and/or status for an existing template.
Request Body
Attribute | Type | Required? | Description |
---|---|---|---|
template_id | String | Yes | Unique, Class-generated identifier for template |
name | String | No | Template's name |
description | String | No | Template's description |
status | String | No | Template's status [published, draft] |
Remove a Template
Example Request:
DELETE [api-base-url]/api/v1/templates?template_id=8ce1adbf-e60d-4606-8ad2-69f57d0ed571
Example Response:
Status: 200
{
"template_id": "8ce1adbf-e60d-4606-8ad2-69f57d0ed571",
"name": "Template Name",
"description": "A Template Description",
"status": "draft"
}
Method & Path: DELETE /api/v1/templates
Required Scope: template:write
Use the Remove a Template endpoint to delete a particular template. This endpoint doesn't require data in the request body, but requires a query parameter to identify the template, as summarized in the table below.
Note that this endpoint requires a template_id. You can find this id in the response body of both the Create a Template and Get a Template endpoints.
Query Parameters
Param | Type | Required? | Description |
---|---|---|---|
template_id | String | Yes | Unique, Class-generated identifier for template |
Users
There are four Users endpoints:
Users is how Class identifies and manages non-learners (i.e. administrators, instructors and instructional designers).
Class generates a unique, internal id parameter for each user. You also have the option to set an external user id, ext_user_id, in order to link users to your organization's system of record.
Create or Update a User
Example Request:
PUT [api-base-url]/api/v1/users
Example Body:
{
"identified_by": "email",
"ext_user_id": "888",
"email": "mail@mail.com",
"user_name": "Bob Smith",
"roles": [
"admin",
"instructor"
]
}
Example Body:
{
"identified_by": "id",
"id": 2,
"ext_user_id": null,
"email": "mail@mail.com",
"user_name": "Bob Smith",
"roles": [
"admin",
"instructor"
]
}
Example Responses:
Status: 200 (Updated)
{
"id": 2,
"ext_user_id": "888",
"email": "mail@mail.com",
"user_name": "Bob Smith",
"roles": [
"instructor",
"admin"
],
"is_zoom_configured": false
}
Status: 201 (Created)
{
"id": 2,
"ext_user_id": "888",
"email": "mail@mail.com",
"user_name": "Bob Smith",
"roles": [
"instructor",
"admin"
],
"is_zoom_configured": false
}
Method & Path: PUT /api/v1/users
Required Scope: user:write
Use the Create or Update a User endpoint to either add a user or modfiy their information. If the user is found by the identified_by attribute, the user is updated. Otherwise, a new user is created.
Request Body
Attribute | Type | Required? | Description |
---|---|---|---|
identified_by | Integer | Yes | Attribute selected to identifiy user [id, ext_user_id, email] |
id | Integer | No | Unique, Class-generated integer identifier for user |
ext_user_id | String | No | Your organization's assigned identifier for the user (specified during user creation) |
String | No | User's e-mail | |
user_name | String | Yes | User's full name, normally using form 'first_name last_name' |
roles | Array | No | User's role(s), an array including some or all of the following [admin, instructor, instructional-designer] |
Get All Users
Example Request:
GET [api-base-url]/api/v1/users
Example Response:
Status: 200
[
{
"id": 1,
"ext_user_id": null,
"email": "john@mail.com",
"user_name": "John Smith",
"roles": [
"instructor"
],
"is_zoom_configured": true
},
{
"id": 2,
"ext_user_id": "555",
"email": "jane@mail.com",
"user_name": "Jane Smith",
"roles": [
"instructor"
],
"is_zoom_configured": false
}
]
Method & Path: GET /api/v1/users
Required Scope: user:read
Use the Get All Users endpoint to return a list of all users. This endpoint supports pagination parameters.
Get a User
Example Request:
GET [api-base-url]/api/v1/users?id=2
GET [api-base-url]/api/v1/users?ext_user_id=555
GET [api-base-url]/api/v1/users?email=john@mail.com
Example Response:
Status: 200
[
{
"id": 2,
"ext_user_id": "555",
"email": "jane@mail.com",
"user_name": "jane Smith",
"roles": [
"instructor"
],
"is_zoom_configured": false
}
]
Method & Path: GET /api/v1/users
Required Scope: user:read
Use the Get a User endpoint to return information on a specific user. This endpoint doesn't require data in the request body, but requires a query parameter to identify the user, as summarized in the table below.
Query Parameters
Param | Type | Required? | Description |
---|---|---|---|
id | Integer | No | Unique, Class-generated integer identifier for user |
ext_user_id | String | No | Your organization's assigned identifier for the user (specified during user creation) |
String | No | User's e-mail |
Remove a User
Example Request:
DELETE [api-base-url]/api/v1/users?id=2
DELETE [api-base-url]/api/v1/users?ext_user_id=888
DELETE [api-base-url]/api/v1/users?email=mail@mail.com
Example Response:
Status: 200
{
"id": 2,
"ext_user_id": "888",
"email": "mail@mail.com",
"user_name": "Bob Smith",
"roles": [
"instructor",
"admin"
],
"is_zoom_configured": false
}
Method & Path: DELETE /api/v1/users
Required Scope: user:write
To delete a user from the system, use the Remove a User endpoint.
Query Parameters
Param | Type | Required? | Description |
---|---|---|---|
id | Integer | No | Unique, Class-generated integer identifier for user |
ext_user_id | String | No | Your organization's assigned identifier for the user (specified during user creation) |
String | No | User's email |
Error Status Codes
Example error response while calling Create a Class:
Status: 400
{
"error": "Class exists for external class ID provided: 074c697e-e20b-4da8-9361-1b707137d6e3."
}
Example error response while creating a user or enrollment:
Status: 400
{
"error": "Request failed validation",
"data": {
"email": [
"The email format is invalid."
]
}
}
Example error response while calling Create a Class:
Status: 403
{
"error": "Api key scope class:write required"
}
Example error response while calling Get Single Class Info:
Status: 404
{
"error": "class 01cceb4b-afce-4703-a842-6b41fad111b5 not found"
}
The following table summarizes the HTTP error status codes that can be returned by the Class API endpoints if a problem occurs when making a call. The responses in the right-hand column provide examples of error status codes that may be returned along with additional information on the type of error that occurred.
Error Status | Meaning |
---|---|
400 | Bad Request -- The request could not be understood by the server due to malformed syntax. |
401 | Unauthorized -- The API key is malformed or the Authorization Header is not included. |
403 | Forbidden -- The API key does not include the required scopes to access the resource. |
404 | Not Found -- The resource could not be found. |
500 | Internal Server Error -- Something unexpected happened while processing the call. Try again later. |
503 | Service Unavailable -- Class is temporarily offline for maintenance. Try again later. |