Common API Tasks

Here are some common tasks you can do with the Skilljar API:

Add a user to a private domain

First, list your domains and get the Domain's name:

HTTP GET: /v1/domains

Result:
{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "abcdefg123456",
            "name": "learn.example.com",
            "catalog_title": "All Courses",
            "private": true,
            "access_code_message_html": "Please have an admin add you to the domain, then log in.",
            "marketing_message": null
        }
    ]
}

In this example, we will use learn.example.com as our domain name.

Next, add the user to the domain via an HTTP POST to the DomainUser endpoint:

HTTP POST: /v1/domains/learn.example.com/users
Content-Type: application/json

Body:
{
    "user": {
        "email": "bob@test.com",
        "first_name": "Bob",
        "last_name": "User"
    }
}

Response:
HTTP 201 Created
{
    "user": {
        "id": "jklmnop987654",
        "email": "bob@test.com",
        "first_name": "Bob",
        "last_name": "User"
    },
    "active": true,
    "marketing_optin": null,
    "expires_at": null
}

Bob User now has an active membership in learn.example.com If you're not implementing SSO - then Bob User will need to set a password via the "Forgot Password" link if he hasn't already logged in previously.

Enroll a user in a course

Looking at the previous example, you can see that Bob User's user_id is jklmnop987654. Let's use that to enroll him in a course on learn.example.com.

First, we need to get the published_course_id of the course in which we wish to enroll the user:

HTTP GET: /v1/domains/learn.example.com/published-courses
Accept: application/json

Response:
{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "abcdefg123456",
            "slug": "example-course",
            "live": true,
            "course": {
                "id": "cdefghi3456789",
                "title": "Example Title"
            }
        }
    ]
}

The published_course_id in this example is abcdefg123456.

Now that we know Bob User's user_id and the published_course_id, let's create an enrollment for Bob in the Example Course:

HTTP POST: /v1/domains/learn.example.com/published-courses/abcdefg123456/enrollments

Content-Type: application/json

Body:
{
  "user": {
    "id": "jklmnop987654"
  },
  "expires_at": "2015-03-20T07:07:01+00:00",
  "active": true
}

Response:
HTTP 201 Created
{
  "id": "defghijk123456",
 "user": {
 "id": "jklmnop987654",
 "email": "bob@test.com",
 "first_name": "Bob",
 "last_name": "User"
 },
 "enrolled_at": "2015-02-20T07:07:01+00:00",
 "expires_at": "2015-03-20T07:07:01+00:00",
 "active": true
}

We've now created an enrollment for Bob that expires one month after we created it. You may omit the expires_at parameter to create an enrollment that does not expire. You can also omit the active parameter as it defaults to true.

Revoke user access to a course

There are times when you may want to programmatically unenroll a user from a course. For example, if you are managing an external payment system, and the user requests a refund, or has created a subscription system, and the user's subscription expires.

First, let's list the users in our example course (using IDs from the previous examples):

HTTP GET: /v1/domains/learn.example.com/published-courses/abcdefg123456/enrollments

Response:
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "defghijk123456",
            "user": {
                "id": "jklmnop987654",
                "email": "bob@test.com",
                "first_name": "Bob",
                "last_name": "User"
            },
            "enrolled_at": "2015-02-20T07:07:01+00:00",
            "expires_at": "2015-03-20T07:07:01+00:00",
            "active": true
        },
        {
            "id": "lmnopqrs123456",
            "user": {
                "id": "cdefghi567890",
                "email": "jane@example.com",
                "first_name": "Jane",
                "last_name": "Doe"
            },
            "enrolled_at": "2014-11-18T05:32:27+00:00",
            "expires_at": null,
            "active": true
        }
    ]
}

I see that I have 2 users enrolled in this course; Bob, who we enrolled previously, and Jane Doe who was already enrolled. Let's deactivate Jane's enrollment.

Her enrollment_id is lmnopqrs123456. The easiest way to deactivate an enrollment is to set the active flag to false:

HTTP PUT: /v1/domains/learn.example.com/public-courses/abcdefg123456/enrollments/lmnopqrs123456

Body:
{
    "active": false
}

Response:
{
    "id": "lmnopqrs123456",
    "user": {
        "id": "cdefghi567890",
        "email": "jane@example.com",
        "first_name": "Jane",
        "last_name": "Doe"
    },
    "enrolled_at": "2014-11-18T05:32:27+00:00",
    "expires_at": null,
    "active": false
}