NAV navbar

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.

drawing 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.

drawing 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.

drawing 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:

  1. Choose your endpoint. (i.e., Create a Class or Get Attendance). For a full list of endpoints, see the table in the next section.
  2. Find the correct method for your endpoint (GET, POST, PUT, or DELETE) as listed in the sections below.
  3. 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.
  4. Add the Authorization header using the Bearer authorization scheme.
  5. 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.
  6. Make the constructed http request using your preferred programming language and library.
  7. 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
email 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)
email 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)
email 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)
email 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.

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)
email 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)
email 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)
email 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)
email 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.