Enlight API v1

Envisage provides a simple API for you to manage your account

Mikel Lindsaar avatar
Written by Mikel Lindsaar
Updated over a week ago

Enlight has a simple API that is available for your use, any feedback is welcome.

This document represents version 1 of the API. You can find all versions listed in our help article:

You can use the API to programatically update many aspects of your enlight training system. There are rate limits and API usage limits on the enlight API that you can read more about in our help article:

  • Enlight API Usage Limits

This document walks through the major aspects of the API and how to use it and is broken up into the following sections:

Setup & Testing Authentication

In order to use the API, you need to get your API key can be found on your user profile page. You will need to include this in an `Authorization` HTTP header as a `Bearer` token. This key is a 32 character string that will look something like:

3824ac01-83ed-1aef-b124-48380def5e7f

Additionally, you will need your enlight subdomain or enlight domain name in order to access your API end point. For example, if might be example.enlight.io which we will use throughout this guide.

For example, you can do the following to access the API through a curl command.

curl -IH "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/authenticate

Which should give you a 200 OK with an empty body looking something like:

HTTP/1.1 200 OK
Date: Thu, 27 Aug 2020 02:30:22 GMT
Connection: close
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Cache-Control: no-cache, no-store
Content-Type: application/json; charset=utf-8
X-Request-Id: ef230e63-dfd0-4cab-bffb-363c472cb19b
X-Runtime: 0.035810

If you don't get a 200 OK, make sure you have replaced `YOUR_API_KEY` with your 32 character API key. If this still doesn't work, please contact support to debug what is happening.

Using the Courses API

List all Courses

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/courses

This will give you an array of courses with the following format:

[
{
"id":"50edd30a-d0da-4862-ba89-02b29835c80a",
"name":"How to use the Enlight API",
"summary":"This course teaches you the enlight API",
"course_image":{
"id":"course/d8297351-f278-4e84-af89-84c4df524acd/course_image/0984231234.jpg",
"storage":"store",
"metadata":{
"md5":"2880c465167aec271ff5f28b0a1dc9dc",
"size":30146,
"filename":"how-to-use.jpg",
"mime_type":"image/jpeg"
}
},
"multiple_sign_ups":false,
"purchasable":true,
"advertised":true,
"price_cents":1000,
"price_currency":"USD",
"instructor_id":"50edd30a-d0da-4862-ba89-02b29835c80a",
"prerequisite_course_id":"798fceb7-6d65-4659-9e69-a949a370bc68",
"archived_at":null,
"created_at":"2015-06-17T12:51:08.182Z",
"updated_at":"2020-05-02T05:41:07.051Z"
}
]

In the above response, it includes the course ID, the ID of the assigned instructor, any prerequisite course ID as well as other key data such as the price, which is represented in cents, so the above of 1000 means $10.00.

Show a Specific Course

A specific course can be shown by passing the ID in the courses API such as:

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/courses/50edd30a-d0da-4862-ba89-02b29835c80a

This will give you a JSON object of the requested course:

{
"id":"50edd30a-d0da-4862-ba89-02b29835c80a",
"name":"How to use the Enlight API",
"summary":"This course teaches you the enlight API",
"course_image":{
"id":"course/d8297351-f278-4e84-af89-84c4df524acd/course_image/0984231234.jpg",
"storage":"store",
"metadata":{
"md5":"2880c465167aec271ff5f28b0a1dc9dc",
"size":30146,
"filename":"how-to-use.jpg",
"mime_type":"image/jpeg"
}
},
"multiple_sign_ups":false,
"purchasable":true,
"advertised":true,
"price_cents":1000,
"price_currency":"USD",
"instructor_id":"50edd30a-d0da-4862-ba89-02b29835c80a",
"prerequisite_course_id":"798fceb7-6d65-4659-9e69-a949a370bc68",
"archived_at":null,
"created_at":"2015-06-17T12:51:08.182Z",
"updated_at":"2020-05-02T05:41:07.051Z",
"checksheets": [
{
"id":"6986ac14-19a4-4b5c-953c-a37f83754240",
"course_id":"67b24850-e32f-47a4-b2bd-cf87936a2c7b",
"version":1,
"current_checksheet":false,
"published":true,
"created_at":"2020-10-18T05:34:45.866Z",
"updated_at":"2020-10-18T05:34:45.866Z"
},
{
"id":"e412869e-affe-403f-a006-47e6f1bfc668",
"course_id":"67b24850-e32f-47a4-b2bd-cf87936a2c7b",
"version":2,
"current_checksheet":true,
"published":true,
"created_at":"2020-10-18T05:34:45.866Z",
"updated_at":"2020-10-18T05:34:45.866Z"
}
]
}

Update a specific Course

You can update a specific course by passing in one of the supported attributes:

curl -H "Authorization: Bearer YOUR_API_KEY" \
-X PATCH \
-d '{"price_cents":"5000"}' \
https://example.enlight.io/api/v1/courses/f613fc3d-0101-44d4-86e0-0d2ef55dac9b

Which will return the same parameters as the show specific course on success. On error (such as attempting to set a negative price) it will return an error hash.

{"errors":{"price":["must be greater than or equal to 0"]}}

Create a Course

You can create a course by passing all of the required attributes:

curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X POST \
-d '{"name":"Special Course","completion_information_html":"<p>Well done on completing your course!</p>","summary":"This course teaches you the basics","marketing_copy_html":"<p>Buy this course today!</p>","purchasable":"false","price_cents":"0"}' \
https://example.enlight.io/api/v1/courses

The minimum required fields are:

  • name - the name of the course

  • summary - the summary of the course

  • marketing_copy_html - what is displayed on the purchase website

  • completion_information_html - what the student is told at the end of the course

Which will return the same parameters as the show specific course on success. On error (such as creating a course with the same name) it will return an error hash.

{"errors":{"name":["has already been taken"]}}

Cancel a Course

To cancel a course, pass in its ID with the DELETE method.

curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X DELETE \
https://example.enlight.io/api/v1/courses/b6062c1f-e879-44e9-12ce-3bd2ecd384b9

On success this will return 200 OK and an empty JSON body. This process first cancels any enrollment currently attached to the course and then marks it as deleted.

Using the Checksheets API

List all Checksheets

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/checksheets

Which will return a full list of your first 100 checksheets.

[
{
"id":"6986ac14-19a4-4b5c-953c-a37f83754240",
"course_id":"67b24850-e32f-47a4-b2bd-cf87936a2c7b",
"version":1,
"current_checksheet":false,
"published":true,
"created_at":"2020-10-18T05:34:45.866Z",
"updated_at":"2020-10-18T05:34:45.866Z"
},
{
"id":"a412869e-dffe-203f-b126-52e6f1bfc668",
"course_id":"67b24850-e32f-47a4-b2bd-cf87936a2c7b",
"version":2,
"current_checksheet":true,
"published":true,
"created_at":"2020-10-18T05:34:45.866Z",
"updated_at":"2020-10-18T05:34:45.866Z"
}
]

This also shows you all the versions of checksheets including if they are the current checksheet for the course in question.

Show a Specific Checksheet

A specific checksheet can be shown by passing the ID in the checksheets API such as:

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/checksheets/e412869e-affe-403f-a006-47e6f1bfc668

This will give you a JSON object of the requested checksheet including all sections and steps in sequence that they appear:

{
"course_id": "b6062c1f-e879-44e9-12ce-3bd2ecd384b9",
"created_at": "2020-10-18T05:21:42.289Z",
"current_checksheet": true,
"id": "e412869e-affe-403f-a006-47e6f1bfc668",
"published": true,
"sections": [
{
"created_at": "2020-10-18T05:21:42.279Z",
"final": false,
"id": "a1bae269-bd33-4f08-af0d-2b5956345910",
"label": null,
"name": "Section 1",
"sequence": 1,
"section_steps": [
{
"id": "48f73ba8-c013-4480-a5a9-d917f159331e",
"content_html": "What is the art of selling? ",
"conditional": false,
"label": null,
"needs_attachment": false,
"number_of_items": null,
"points": 5,
"title": "Quiz",
"type": "Steps::MultipleChoice",
"created_at": "2018-10-11T07:06:55.472Z",
"updated_at": "2018-10-11T07:06:55.472Z",
"library_item_id": null,
"organisation_id": "0ca51df6-704e-4dc4-afc7-9a4aa90e2c24",
"target_course_id": null,
"archived_at": null,
"answer_html": null,
"reject_duplicate_attempts": false,
"suggested_response": "Thank you for your answer",
"cloned_from_step_id": "072e9a9d-1c02-423e-95c6-afeca1047099",
"data": {
"choices": [
{
"name": "Answer A.",
"correct": "1"
},
{
"name": "Answer B."
},
{
"name": "Answer C."
}
],
"persist_order": false,
"selection_type": "single"
}
}
}
],
"updated_at": "2020-10-18T05:21:42.308Z"
}
],
"updated_at": "2020-10-18T05:21:42.289Z",
"version": 1
}

Note in the above response, the correct anwer is included in the step data. If this is not wanted in the JSON response, query the checksheet using the student API token instead of a user API token, when requesed this way, all internal data about the step and enrollment content (such as correct answer, suggested response, etc) are removed from the response and multiple choice questions are randomized as shown here:

{
"course_id": "b6062c1f-e879-44e9-12ce-3bd2ecd384b9",
"created_at": "2020-10-18T05:21:42.289Z",
"current_checksheet": true,
"id": "e412869e-affe-403f-a006-47e6f1bfc668",
"published": true,
"sections": [
{
"created_at": "2020-10-18T05:21:42.279Z",
"final": false,
"id": "a1bae269-bd33-4f08-af0d-2b5956345910",
"label": null,
"name": "Section 1",
"sequence": 1,
"section_steps": [
{
"id": "a636a972-0d1c-4603-b2c1-64027fbe09e1",
"list_source_step": null,
"possible_reference_section_step_ids": [
"5a9865e3-6fd7-4720-b88f-488cc9dd413d",
"cf6ef8a3-bcfa-4938-9afa-e87df5011761",
"fe233f06-ee24-4455-880c-71b88478f1da"
],
"step": {
"id": "48f73ba8-c013-4480-a5a9-d917f159331e",
"content_html": "What is the correct answer? ",
"conditional": false,
"label": null,
"needs_attachment": false,
"number_of_items": null,
"points": 5,
"title": "Quiz",
"type": "Steps::MultipleChoice",
"created_at": "2018-10-11T07:06:55.472Z",
"updated_at": "2018-10-11T07:06:55.472Z",
"library_item_id": null,
"organisation_id": "0ca51df6-704e-4dc4-afc7-9a4aa90e2c24",
"target_course_id": null,
"data": {
"choices": [
{
"name": "Answer B"
},
{
"name": "Answer C"
},
{
"name": "Answer A"
}
],
"persist_order": false,
"selection_type": "single"
}

}
}
],
"updated_at": "2020-10-18T05:21:42.308Z"
}
],
"updated_at": "2020-10-18T05:21:42.289Z",
"version": 1
}

Using the Library Items API

Show a Specific Library Item

A specific library item can be shown by passing the ID in the courses API such as:

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/library_items/8e016712-0472-443e-b187-a99332deac3c

This will give you a JSON object of the requested library item:

{
"id": "8e016712-0472-443e-b187-a99332deac3c",
"author": null,
"title": "Example",
"intro_html": null,
"content_html": null,
"kind": null,
"duration": null,
"asset_host": "https://d3psjymf7uu91w.cloudfront.net",
"asset_file_url": "https://d14hmtmeb4nek6.cloudfront.net/uploads/libraryitems/pdf/8e016712-0472-443e-b187-a99332deac3c/asset_file/9a344eff6b81d7f37e765861927753e6.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAAIVDJ3DFYIBSG5TQ%2F20210413%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200413T135146Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=d8be28a418362826a998db99e234538094280fa94265f159952b8c1969a0e5aa4",
"asset_file_data": {
"id": "libraryitems/pdf/8e016712-0472-443e-b187-a99332deac3c/asset_file/9a344eff6b81d7f37e765861927753e6.pdf",
"storage": "store",
"metadata": {
"md5": "8c4e551a93d74cdadcde813da9f1533c",
"size": 58958,
"filename": "example.pdf",
"mime_type": "application/pdf"
}
},
"video_captions": null,
"type": "Pdf",
"visibility": "members",
"provide_download_link": true,
"show_in_library": true,
"published": false,
"feature_in_top_resources": false,
"public_access_key": "56e64be0668b2489495c0e2ec0508d0616fe33a85ad842334fa92072392f11e9",
"created_at": "2018-10-16T05:08:48.775Z",
"updated_at": "2021-01-29T18:41:30.270Z"
}

Note, if the request is made by a student, many fields will not be available from the above.

Using the Students API

List all Students

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/students

Which will return a full list of your first 100 students.

[
{
"id":"82121578-afda-46ca-a2db-5b5f92bbce16",
"given_name":"Bob",
"family_name":"Example",
"email":"bob@example.com",
"external_id":"12345",
"locale":"en-US",
"time_zone":"Sydney",
"gravatar_url":"http://www.gravatar.com/avatar/6bed2cc82ac1538da3fc3312d424bb04"
}
]

For each additional page, pass the parameter page=<number> as follows:

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/students?page=2

Show a Specific Student

To show a specific student, first get its ID and then query as follows:

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/students/82121578-afda-46ca-a2db-5b5f92bbce16

This will give you the specific information on the requested student.

{
"id":"82121578-afda-46ca-a2db-5b5f92bbce16",
"given_name":"Bob",
"family_name":"Example",
"email":"bob@example.com",
"api_key":"57056867-5ea3-4adf-b411-63b4fbf4eda1"
"external_id":"12345",
"locale":"en-US",
"time_zone":"Sydney",
"gravatar_url":"http://www.gravatar.com/avatar/6bed2cc82ac1538da3fc3312d424bb04"
}

Update a specific Student

You can update a specific student by passing in one of the supported attributes:

curl -H "Authorization: Bearer YOUR_API_KEY" \
-X PATCH \
-d '{ "email": "sam@example.com" }'\
https://example.enlight.io/api/v1/students/82121578-afda-46ca-a2db-5b5f92bbce16

Once done this will return the same output as the Show specific Enrollment api call.

If there is an error, it will be displayed:

{"errors":{"email":["can't be blank"]}}

Create a Student

You can create a student by passing all of the required attributes:

curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X POST \
-d '{"given_name":"John",
"family_name":"Smith",
"email": "john@example.com"}' \
https://example.enlight.io/api/v1/students

The minimum required fields are:

  • given_name - the given name of the student

  • family_name - the family name of the student

  • email - the email address of the student (must be unique)

You can also pass in the following additional attributes:

  • external_id - the given name of the student

  • student_account_id - the family name of the student

  • time_zone - the email address of the student (must be unique)

  • locale - One of the supported locales (en-US, en-GB, es-ES, es-MX)

  • force_accept_invitation - Marks the student as verified (does not require verification email to be clicked)

  • assigned_password - assigns the provided password as the student's password

  • language - the language of the student

  • external_id - the external ID of this student

  • cancel_legacy_system - sends an email to the managers when the student enters their own credit card allowing you to cancel any other billing system you have in place

  • lock - locks the student and prevents them from signing in

Which will return the same parameters as the show specific student on success. On error (such as creating a student with the same email as someone else) it will return an error hash.

{
"errors":{"email":["has already been taken"]}
}

Delete a Student

There is no method to delete a student through the API

Using the Enrollments API

List all Enrollments

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/enrollments

Which will return a full list of your first 100 enrollments.

[
{
"id":"95d81367-9e78-4937-a30b-77c853e89baa",
"student_id":"82121578-afda-46ca-a2db-5b5f92bbce16",
"course_id":"9c89bc86-b7ba-4223-bbab-9feb4f408370",
"checksheet_id":"e412869e-affe-403f-a006-47e6f1bfc668",
"instructor_id":"5e0435d2-d88c-45ea-a106-d91cdcc323e8",
"enroller_id":"a2efae3a-ed33-431c-ad72-aaf1bfe8f25b",
"active":true,
"created_at":"2020-05-01T13:58:26.354Z",
"updated_at":"2020-08-08T09:59:27.172Z",
"started_at":"2020-08-08T09:57:28.816Z",
"completed_at":null,
"expires_at":"2021-05-01T13:58:26.354Z",
"custom_name":null
}
]

The above shows all the unique IDs related to the enrollment, each one you can query with the related APIs. Enroller is a special ID that relates to the user who enrolled the student which you can also inspect with the Instructor API.

For each additional page, pass the parameter page=<number> as follows:

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/enrollments?page=2

Show a Specific Enrollment

To show a specific enrollment, first get its ID and then query as follows:

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/enrollments

This will give you the specific information on the requested enrollment but will also give extra embedded information on the student related to that enrollment:

{
"id":"95d81367-9e78-4937-a30b-77c853e89baa",
"student_id":"82121578-afda-46ca-a2db-5b5f92bbce16",
"course_id":"9c89bc86-b7ba-4223-bbab-9feb4f408370",
"checksheet_id":"e412869e-affe-403f-a006-47e6f1bfc668",
"instructor_id":"5e0435d2-d88c-45ea-a106-d91cdcc323e8",
"enroller_id":"a2efae3a-ed33-431c-ad72-aaf1bfe8f25b",
"active":true,
"created_at":"2020-05-01T13:58:26.354Z",
"updated_at":"2020-08-08T09:59:27.172Z",
"started_at":"2020-08-08T09:57:28.816Z",
"completed_at":null,
"expires_at":"2021-05-01T13:58:26.354Z",
"custom_name":null,
"student":{
"id":"82121578-afda-46ca-a2db-5b5f92bbce16",
"given_name":"Bob",
"family_name":"Example",
"email":"bob@example.com",
"external_id":"12345",
"locale":"en-US",
"time_zone":"Sydney",
"gravatar_url":"http://www.gravatar.com/avatar/6bed2cc82ac1538da3fc3312d424bb04"
}
}

Update a specific Enrollment

You can update a specific enrollment by passing in one of the supported attributes:

curl -H "Authorization: Bearer YOUR_API_KEY" \
-X PATCH \
-d '{ "expires_at": "2020-12-01T13:58:26.354Z" }' \
https://example.enlight.io/api/v1/enrollments/cb3fa2a3-ecff-4cbd-96cc-308b85e7996d

Note, you can only update the instructor and expiry date on an enrollment via the API. Once done this will return the same output as the Show specific Enrollment api call.

If there is an error, it will be displayed:

{"errors":{"expires_at":["must be in the future"]}}

Create an Enrollment for an Existing Student

You can create an enrollment for an existing student, course and instructor by passing all of the required attributes:

curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X POST \
-d '{"course_id":"f613fc3d-0101-44d4-86e0-0d2ef55dac9b",
"student_id":"82121578-afda-46ca-a2db-5b5f92bbce16",
"send_enrollment_notification": "true",
"group_ids":["e0c351c8-8516-4e42-b719-6c11f181624b"],
"instructor_id": "5e0435d2-d88c-45ea-a106-d91cdcc323e8"}' \
https://example.enlight.io/api/v1/enrollments

The minimum required fields are:

  • course_id - the ID of the course

  • student_id - the ID of the student

  • instructor_id - the instructor ID assigned to the course

The optional fields are:

  • send_enrollment_notification - If present, an email will be sent to the student inviting them to sign into their dashboard

  • group_ids - an array of enrollment groups the student belongs to

Which will return the same parameters as the show specific enrollment on success. On error (such as creating a course with the same name) it will return an error hash.

{
"message":"Unable to save enrollment",
"errors":{
"course_id":["can't be blank"],
}
}

Create an Enrollment and Student Simultaneously

You can create an enrollment and the student at the same time as long as you supply the course and instructor as well:

curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X POST \
-d '{"student_given_name":"Jane",
"student_family_name":"Smith",
"student_email":"jane@example.com",
"student_external_id":"12345",
"student_password":"secret123",
"student_locale":"en-US",
"group_ids":["e0c351c8-8516-4e42-b719-6c11f181624b"],
"send_enrollment_notification": "true",
"course_id":"f613fc3d-0101-44d4-86e0-0d2ef55dac9b",
"instructor_id": "5e0435d2-d88c-45ea-a106-d91cdcc323e8"}' \
https://example.enlight.io/api/v1/enrollments

When creating a student this way, the minimum required fields are:

  • course_id - the ID of the course

  • instructor_id - the instructor ID assigned to the course

  • student_email - the email of the student

  • student_given_name - the given (first) name of the student

  • student_family_name - the family (last) of the student

In addition, the following student attributes can also be defined:

  • student_external_id - the external ID of the student

  • student_locale - the locale of the student

  • student_account_id - the Student Account ID the student belongs to

  • student_cancel_legacy_system - if you wish to receive an email when the student enters their credit card details

Which will return the same parameters as the show specific enrollment on success. On error (such as creating a course with the same name) it will return an error hash.

{
"message":"Unable to save enrollment",
"errors":{
"student_email":["can't be blank"],
}
}

Cancel an Enrollment

To cancel an enrollment, pass in its ID with the DELETE method.

curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X DELETE \
https://example.enlight.io/api/v1/enrollments/cb3fa2a3-ecff-4cbd-96cc-308b85e7996d

On success this will return 200 OK and an empty JSON body. This will cancel the associated enrollment, expelling the student from the course.

Using the Groups API

List all Groups

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/groups

Which will return a full list of your first 100 students.

[
{
"id":"e0c351c8-8516-4e42-b719-6c11f181624b",
"name":"Class of 2020"
}
]

For each additional page, pass the parameter page=<number> as follows:

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/groups?page=2

Show a Specific Group

To show a specific group, first get its ID and then query as follows:

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/groups/e0c351c8-8516-4e42-b719-6c11f181624b

This will give you the specific information on the requested group including its enrollments

{
"id":"e0c351c8-8516-4e42-b719-6c11f181624b",
"name":"Class of 2020",
"enrollments": [
{
"id":"265f5058-6915-4125-aa92-cfa67aa20691",
"student_id":"5f6e867a-c510-408a-8553-41c866ea4689",
"course_id":"4805f4f3-0fb7-43c4-865c-acba8bd3cdf1",
"checksheet_id":"36abf929-22cb-4d2c-8856-9a2d7c85c34b",
"instructor_id":"24e4d370-d73d-424a-8e3e-d77d8f9d9223",
"enroller_id":"24e4d370-d73d-424a-8e3e-d77d8f9d9223",
"active":true,
"created_at":"2020-04-15T06:39:42.309Z",
"updated_at":"2020-08-27T10:12:45.529Z",
"started_at":null,
"completed_at":null,
"expires_at":"2021-04-15T00:00:00.000Z",
"custom_name":null
}]
}

Update a specific Group

You can update a specific group by passing in one of the supported attributes:

curl -H "Authorization: Bearer YOUR_API_KEY" \
-X PATCH \
-d '{ "name": "Class of 2021" }'\
https://example.enlight.io/api/v1/groups/e0c351c8-8516-4e42-b719-6c11f181624b

Once done this will return the same output as the Show specific Group api call.

If there is an error, it will be displayed:

{"errors":{"name":["can't be blank"]}}

Create a Group

You can create a student group by passing all of the required attributes:

curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X POST \
-d '{ "name":"Class of 2020" }' \
https://example.enlight.io/api/v1/groups

The minimum required fields are:

  • name - the name of the group

Which will return the same parameters as the show specific group on success. On error (such as creating a group without a name) it will return an error hash.

{
"errors":{"name":["can't be blank"]}
}

Delete a Group

To delete a group, pass in its ID with the DELETE method.

curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X DELETE \
https://example.enlight.io/api/v1/groups/e0c351c8-8516-4e42-b719-6c11f181624b

On success this will return 200 OK and an empty JSON body. This will delete the group but not touch the associated enrollments.

Using the Users API

List all Users

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/users

Which will return a full list of your first 100 users.

[
{
"id":"d39e311f-018d-4c57-ba88-6c5ac76ccb15",
"given_name":"Sam",
"family_name":"Smith",
"email":"sam@example.com",
"locale":"en-US",
"role":"instructor",
"unsubscribed":false
}
]

For each additional page, pass the parameter page=<number> as follows:

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/users?page=2

Show a Specific User

To show a specific user, first get its ID and then query as follows:

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://example.enlight.io/api/v1/users/d39e311f-018d-4c57-ba88-6c5ac76ccb15

This will give you the specific information on the requested user

{
"id":"d39e311f-018d-4c57-ba88-6c5ac76ccb15",
"given_name":"Sam",
"family_name":"Smith",
"email":"sam@example.com",
"locale":"en-US",
"role":"instructor",
"unsubscribed":false
}

Update a specific User

You can update a specific user by passing in one of the supported attributes:

curl -H "Authorization: Bearer YOUR_API_KEY" \
-X PATCH \
-d '{ "given_name": "Samuel" }'\
https://example.enlight.io/api/v1/users/d39e311f-018d-4c57-ba88-6c5ac76ccb15

Once done this will return the same output as the Show specific Instructor API call.

If there is an error, it will be displayed:

{"errors":{"given_name":["can't be blank"]}}

Create a User

You can create an user by passing all of the required attributes:

curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X POST \
-d '{"role":"instructor", "given_name":"Sam", "family_name":"Smith", "email": "sam@example.com"}' \
https://example.enlight.io/api/v1/users

The minimum required fields are:

  • given_name - the given name of the user

  • family_name - the family name of the user

  • email - the email address of the user (must be unique)

  • role - the role of the user (instructor, supervisor, manager, owner)

Which will return the same parameters as the show specific user on success. On error (such as creating a user with the same email as someone else) it will return an error hash.

{
"errors":{"email":["can't be blank"]}
}

Delete a User

To remove a user from your organisation, pass in its ID with the DELETE method.

curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X DELETE \
https://example.enlight.io/api/v1/users/e0c351c8-8516-4e42-b719-6c11f181624b

On success this will return 200 OK and an empty JSON body. This will remove the user from your organisation.

Submitting Answers API

Enlight allows you to create Answers for checksheets directly via the API.

There are 4 broad types of step that each require a different process to submit answers for:

Steps Requiring a Specific Answer

These are automatically marked steps such as Sorting a List or Multiple Choice.

These require the student to submit a specific answer in order to have it marked as "passed" automatically by the system. When submitting an answer to one of these steps you will get back a Success response (200 OK) or a Bad Request response (400 Error) depending on if the answer was marked as correct or not.

These steps include:

  • Multiple Choice Step (single or multiple correct values)

  • Sequence Items Step

To submit an answer for these, you need the Student's API token, the Enrollment ID they are using as well as the Section Step ID that they are submitting an answer for and then submit as follows:

# Single Multiple Choice with "Choice 2" as correct answer
# note the content is a string
curl -H "Authorization: Bearer STUDENT_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X POST \
https://example.enlight.io/api/v1/answer \
-d '{"enrollment_id":"51278615-f974-4bde-b42e-31cd699e11c7",
"section_step_id":"da902bc7-72ce-4b21-90c4-44734de06af1",
"answer":{"content":"Choice 2"}}'

# Multi Multiple Choice with "Choice 2 + 1" as correct answer
# note the content is an array
curl -H "Authorization: Bearer STUDENT_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X POST \
https://example.enlight.io/api/v1/answer \
-d '{"enrollment_id":"51278615-f974-4bde-b42e-31cd699e11c7",
"section_step_id":"da902bc7-72ce-4b21-90c4-44734de06af1",
"answer":{"content":["Choice 1", "Choice 2"]}}'

# Sequence Items with "Item 2 then Item 1" as correct answer
# note the content is an array
curl -H "Authorization: Bearer STUDENT_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X POST \
https://example.enlight.io/api/v1/answer \
-d '{"enrollment_id":"51278615-f974-4bde-b42e-2a6addca9aad",
"section_step_id":"da902bc7-72ce-4b21-90c4-447143206af1",
"answer":{"content":["Item 2", "Item 1"]}}'

Steps Requiring any Answer to be Marked Later

These steps are not automatically marked as passed, but are given a Success response (200 OK) if any valid answer is supplied. For example, a Question Step will require the user to type some text that gets submitted to an instructor for marking, however this happens some time after the request, so as long as there is content submitted, this will be given a Success response to let the student continue.

You can then at a later time, query the API to see the status of this step answer to determine if it was correct or not.

These steps include:

  • Allocate Step

  • Arrange Step

  • Assignment Step

  • Checkpoint Step

  • List Step

  • Question Step

  • Unformatted Question Step

To submit an answer for these, you need the Student's API token, the Enrollment ID they are using as well as the Section Step ID that they are submitting an answer for and then submit as follows:

# Question and Unformatted Question Step with "This is my answer"
# as the student's answer, note the content is a string
curl -H "Authorization: Bearer STUDENT_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X POST \
https://example.enlight.io/api/v1/answer \
-d '{"enrollment_id":"51278615-f974-4bde-b42e-2a6addca9aad",
"section_step_id":"da902bc7-72ce-4b21-90c4-447143206af1",
"answer":{"content":"This is my answer"}}'

# Other step types not supported yet.

Steps Requiring any Answer without Marking

These steps are automatically marked as passed and given a Success response (200 OK) if any valid answer is supplied. These are informational steps, such as "Note" or "Rating" where the student can submit whatever they like. As long as there is valid content, these will be marked as correct and passed.

These steps include:

  • Feedback Step

  • Identify Enrollment Step

  • Note Step

  • Note & Rating Step

  • Rank Step

  • Rating Step

  • Review Step

  • Survey Step

  • Value Enrollment Step

To submit an answer for these, you need the Student's API token, the Enrollment ID they are using as well as the Section Step ID that they are submitting an answer for and then submit as follows:

No API support for submitting answers to these Step types yet

Steps Not Requiring an Answer

These steps require no answer, and just create the "answer" record so that they can be marked as done. Such as reading a document or watching a video.

These steps include:

  • All Library Item / Reference Steps

  • Information Step

To submit an answer for these, you need the Student's API token, the Enrollment ID they are using as well as the Section Step ID that they are submitting an answer for and then submit as follows:

# All reference and information steps
curl -H "Authorization: Bearer STUDENT_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X POST \
https://example.enlight.io/api/v1/answer \
-d '{"enrollment_id":"51278615-f974-4bde-b42e-2a6addca9aad",
"section_step_id":"da902bc7-72ce-4b21-90c4-447143206af1"}'

Viewing an Answer

To show an answer for a section step, such as to see if the answer has been marked as correct or not after it has been submitted, you can call:

curl -H "Authorization: Bearer STUDENT_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X GET \
https://example.enlight.io/api/v1/answer \
-d '{"enrollment_id":"19bbb83c-2e9e-442e-b2a3-2a6addca9aad",
"section_step_id":"4e8defc7-0a8c-4ace-b4aa-447143206af1"}'

This will give you the specific details of the answer for that section step.

{
"id":"2e9f4c9d-cf43-419a-93bc-1238878058a0",
"pass_at":"2021-02-08T07:26:07.812Z",
"points":10,
"state":"passed",
"answered_at":"2021-02-08T07:26:07.815Z",
"created_at":"2021-02-08T07:26:07.815Z",
"updated_at":"2021-02-08T07:26:07.815Z",
"enrollment_id":"19bbb83c-2e9e-442e-b2a3-2a6addca9aad",
"section_step_id":"4e8defc7-0a8c-4ace-b4aa-447143206af1"
}

The possible states an answer can be in are:

  • unsubmitted (has been autosaved and not yet sent to the instructor)

  • submitted (sent to the instructor for marking)

  • rejected (rejected by the instructor as incorrect)

  • passed (either automatically passed, or instructor passed)

Any answer that is not "passed" can be edited by just calling the create answer actions above passing in the enrollment and section step IDs, the new content will update the answer.

Enabling Webhooks

Enlight supports the following webhooks where the system will deliver a JSON payload to a URL of your choice. You add URLs for your webhooks via your profile page.

Course Completion

At the successful end of a course, the enrollment will be marked complete and a the completed enrollment JSON payload will be sent to the webhook. This payload is the same as the show specific enrollment API and looks like this:

{
"id":"95d81367-9e78-4937-a30b-77c853e89baa",
"student_id":"82121578-afda-46ca-a2db-5b5f92bbce16",
"course_id":"9c89bc86-b7ba-4223-bbab-9feb4f408370",
"checksheet_id":"e412869e-affe-403f-a006-47e6f1bfc668",
"instructor_id":"5e0435d2-d88c-45ea-a106-d91cdcc323e8",
"enroller_id":"a2efae3a-ed33-431c-ad72-aaf1bfe8f25b",
"active":true,
"created_at":"2020-05-01T13:58:26.354Z",
"updated_at":"2020-08-08T09:59:27.172Z",
"started_at":"2020-08-08T09:57:28.816Z",
"completed_at":"2020-08-08T09:57:28.816Z",
"expires_at":"2021-05-01T13:58:26.354Z",
"custom_name":null,
"student":{
"id":"82121578-afda-46ca-a2db-5b5f92bbce16",
"given_name":"Bob",
"family_name":"Example",
"email":"bob@example.com",
"locale":"en-US",
"time_zone":"Sydney",
"gravatar_url":"http://www.gravatar.com/avatar/6bed2cc82ac1538da3fc3312d424bb04"
}
}

New Student

When a new student signs up on your system, the student JSON payload will be sent to the webhook. This payload is the same as the show specific studen API and looks like this:

{
"id":"82121578-afda-46ca-a2db-5b5f92bbce16",
"given_name":"Bob",
"family_name":"Example",
"email":"bob@example.com",
"locale":"en-US",
"time_zone":"Sydney",
"gravatar_url":"http://www.gravatar.com/avatar/6bed2cc82ac1538da3fc3312d424bb04"
}

Did this answer your question?