Tahoe Enrollment API

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

Table 2 - Optional Parameters

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

Table 4 - Enrollment “results” key values

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.

Table 6 - Response codes

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

[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

Table 9 - Results element values

Table 10 - Course details record

Table 11 - Course modes record

Table 12 - Response codes

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.