API Endpoints available for enrolling learners in courses on Tahoe from a third-party system.
Use these to use an external system to enroll users in courses by sending the relevant information over to Tahoe to start the learner’s enrollment process there.
Note:
In this doc, you will see references to Token <insert token here>. If you are a Tahoe site admin, please contact
support@appsembler.com to request a unique auth token for your site.
Registration vs Enrollment
Registration is the process of signing up for an account on an Open edX site. It requires at least an email, name, username, password, and acceptance of TOU/Privacy Policy. It does not enroll the user in any courses.
Enrollment is the process of enrolling a registered user in one or more courses.
Bulk enrollment (and unenrollment)
Endpoint: /tahoe/api/v1/enrollments/ Request Method: POST
Description
The Tahoe API v1 bulk enrollment API performs enrollment of one or more learners in one or more courses. The same API can be used to unenroll learners from one or more course depending on the value of the “action” parameter.
The bulk enrollment is derived from and modeled after the bulk enrollment available to our Enterprise customers on Ginkgo or higher. For reference, see our
edx-platform Ginkgo api docs.
Payload
The bulk enrollment payload is an HTTP request body.
Table 1 – Required Parameters
Name
|
Type
|
Description
|
action
|
string
|
To enroll, value must be either “enroll” or “unenroll”.
|
courses
|
List of “string”
|
Each list item is the course identifier. This identifies the course for which to enroll (or unenroll; depending on “action”) all learners in the “identifiers” list. To populate this, you can either use course identifiers you already know, or get them from the Course API.
|
identifiers
|
List of “string”
|
Each list item is a learner identifier. This can be an email address or username. If the learner has not yet registered, it must be an email address. To populate this, you can either use learner identifiers you already know, or get them from the User API.
|
Table 2 – Optional Parameters
Name
|
Type
|
Description
|
auto_enroll
|
boolean
|
Enroll learners in the specified courses as soon as they register. This applies to learners in your list who are not yet registered for the site. Default is false.
Note: This parameter is only applicable when “action” is “enroll”. It is, however, ignored when action is “unenroll”. |
email_learners
|
boolean
|
Learners will be sent email notifications upon enrollment. Default is false.
|
Response
The following tables identify the keys and values of the response. The response body is JSON data by default. See the example response following these tables.
Table 3 – Top Level Response Keys
Name
|
Description
|
action
|
The action as sent in the request body
|
courses
|
List of “string” These are the course identifiers as sent in the request body
|
results
|
List of results for each learner enrollment. See the following table for the structure of each element
|
email_learners
|
See the optional parameter “email_learners” in Table 2. This is that value
|
auto_enroll
|
See the optional parameter “auto_enroll” in Table 2. This is that value
Note: This response key shows up only when action is “enroll”. |
Table 4 – Enrollment “results” key values
These are the values for each element in the “results” value for the previous table
Name
|
Description
|
identifier
|
User unique identifier. This is either the user’s email or the user’s username. Should be the same as the value entered in the “identifiers” list in the required POST parameters table
|
before
|
Contains a set of flags indicating the “before enrollment” state
|
after
|
Contains a set of flags indicating the “after enrollment” state
|
Table 5 – Enrollment “before” and “after” values
NOTE: These are response values built into the existing Open edX platform and not a new feature of the Tahoe enrollment API.
Name
|
Description
|
enrollment
|
Boolean. Has the user been enrolled. ‘False’ for new users (not yet registered). ‘True’ for already existing users.
|
auto_enroll
|
Boolean. If ‘True’, then the user will be automatically enrolled in the course after registering. If ‘False’ then the user will not be automatically enrolled after registering OR the user has already been enrolled (meaning an existing user has enrolled). Notes:
Note: |
user
|
Boolean. Does the user exist after the bulk enrollment. ‘False’ for new users, as the user needs to personally register. ‘True’ if enrolling an existing users
|
allowed
|
Boolean. User is allowed to enroll in the course. ‘True’ for new users (who need to register to enroll). ‘False’ for existing users who are enrolled by this bulk enrollment.
|
Table 6 – Response codes
Name
|
Description
|
201
|
Created. Bulk enrollment was successful for an “enroll” action.
|
200
|
Ok. Bulk enrollment was successful for an “unenroll” action. |
400
|
Bad Request. Invalid parameter(s) or value(s) in request body
|
401
|
Unauthorized. User token passes but user doesn’t have permissions
|
403
|
Forbidden. An invalid token will cause this
|
Examples
Example enroll payload
{ "action": "enroll", "courses": [ "org.26/course_26/Run_26", "org.27/course_27/Run_27" ], "identifiers": [ "robot+test+54@example.com", "alpha@example.com", ], "email_learners": true, "auto_enroll": true }
Example enroll response
{ "action": "enroll", "courses": [ "org.26/course_26/Run_26", "org.27/course_27/Run_27"], "email_learners": true, "results": [ { "identifier": "robot+test+54@example.com", "after": { "enrollment": true, "auto_enroll": false, "user": true, "allowed": false }, "before": { "enrollment": false, "auto_enroll": false, "user": true, "allowed": false } }, { "identifier": "alpha@example.com", "after": { "enrollment": false, "auto_enroll": true, "user": false, "allowed": true }, "before": { "enrollment": false, "auto_enroll": false, "user": false, "allowed": false } } ], "auto_enroll": true }
Example enroll cURL command
curl -X POST https://<your-site-name>.tahoe.appsembler.com/tahoe/api/v1/enrollments/ -H 'Authorization: Token <insert token here>' -H 'Cache-Control: no-cache' -H 'Content-Type: application/json' -d '{ "action": "enroll", "email_learners": true, "identifiers": [ "ann@example.com", "robert@example.com" ], "auto_enroll": true, "courses": [ "course-v1:testing-apis+AP200+2019", "course-v1:testing-apis+AS100+2018" ] }'
Example unenroll cURL command
Similar to the example above, but using the “unenroll” action. Notice that we dropped the “auto_enroll” parameter because it’s irrelevant in the case of “unenroll” action.
curl -X POST https://<your-site-name>.tahoe.appsembler.com/tahoe/api/v1/enrollments/ -H 'Authorization: Token <insert token here>' -H 'Cache-Control: no-cache' -H 'Content-Type: application/json' -d '{ "action": "unenroll", "email_learners": true, "identifiers": [ "ann@example.com", "robert@example.com" ], "courses": [ "course-v1:testing-apis+AP200+2019", "course-v1:testing-apis+AS100+2018" ] }'
Comments/Notes
Running a POST twice on the same data with new (unregistered) user emails should not create additional records. It is intended to be idempotent (at least with regard to CourseEnrollmentAllowed records).
GET List
Endpoint: /tahoe/api/v1/enrollments/ Request Method: GET
Table 7 – Query parameters
Name
|
Type
|
Description
|
course_id
|
string
|
URL friendly course id.example: “course-v1:delta-rook+APH5P+2019”
|
username
|
string
|
Username for the user on whom to filter[1]
|
user_id
|
integer
|
User id for the user on whom to filter[1]
|
[1] For the initial release, only one user is retrieved. If the username and user_id don’t match, then nothing is retrieved. This is a bug that needs to be fixed so we can retrieve multiple users
Response
The top level response contains pagination data, which can be used to page through the list responses.
Table 8 – Top Level Response Keys
Name
|
Description
|
count
|
Number of total records retrieved
|
next
|
Link to the next page of results. Null if no next page
|
previous
|
Link to the previous page of results. Null if no previous page
|
results
|
List of enrollment data. See the next table
|
Table 9 – Results element values
Name
|
Description
|
created
|
Timestamp when the course was created
|
mode
|
The mode of the course. For example, “honor”
|
is_active
|
Boolean. Is the course active or not
|
course_details
|
List of course details records
|
user
|
String. This is the user’s username
|
Table 10 – Course details record
Name
|
Description
|
course_id
|
String id for the course
|
course_name
|
Descriptive name of the course
|
enrollment_start
|
Date the course is open for enrollment. Null if there is no enrollment window (enrollment open anytime)
|
enrollment_end
|
Date the course closes for enrollment. Null if there is no enrollment window (enrollment open anytime)
|
course_start
|
Date the course starts
|
course_end
|
Date the course ends. Can be null
|
invite_only
|
Boolean. True if enrollment is restricted to invites
|
course_modes
|
List of course modes. See the following table
|
Table 11 – Course modes record
Name
|
Description
|
slug
|
Slug for the course mode (lowercase, no spaces. This is the url friendly string for the course mode. Example “honor”
|
name
|
Name for the course mode. Example “Honor”
|
min_price
|
Minimum price for the course. 0 (zero) if there is no cost to the course
|
sugested_price
|
Can be an empty string.
|
currency
|
Country’s ISO currency code. For example, “usd” for United States dollars
|
expiration_datetime
|
Can be null
|
description
|
Can be null
|
sku
|
Can be null
|
bulk_sku
|
Can be null
|
Table 12 – Response codes
Name
|
Description
|
200
|
OK (success)
|
400
|
Bad Request. Invalid parameter(s) or value(s) in request body
|
401
|
Unauthorized. User token passes but user doesn’t have permissions
|
403
|
Forbidden. An invalid token will cause this
|
Example cURL command
curl -X GET https://<your-site-name>.tahoe.appsembler.com/tahoe/api/v1/enrollments/ -H 'Accept: */*' -H 'Authorization: Token <insert token here> -H 'Cache-Control: no-cache'
Example response
{ "count": 59, "next": "https://your-site-name.tahoe.appsembler.com/tahoe/api/v1/enrollments/?limit=20&offset=20", "previous": null, "results": [ { "created": "2019-01-03T16:01:26.609570Z", "mode": "honor", "is_active": true, "course_details": { "course_id": "course-v1:testing-apis+AP200+2019", "course_name": "APIs: How I learned to stop worrying and love APIs", "enrollment_start": null, "enrollment_end": null, "course_start": "2030-01-01T00:00:00Z", "course_end": null, "invite_only": false, "course_modes": [ { "slug": "honor", "name": "Honor", "min_price": 0, "suggested_prices": "", "currency": "usd", "expiration_datetime": null, "description": null, "sku": null, "bulk_sku": null } ] }, "user": "ann_example_com" }, … ]
GET Detail
Endpoint: /tahoe/api/v1/enrollments/<enrollment id>/ Request Method: GET
DO NOT USE. This is currently broken. It returns a course overview and not a course enrollment.