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 theDomainUserendpoint:
HTTP POST: /v1/domains/learn.example.com/usersContent-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
}
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 Response: |
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: Response: |
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 Accept: application/json
Response:
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "abcdefg123456",
"slug": "example-course",
"live": true,
"course": {
"id": "cdefghi3456789",
"title": "Example Title"
}
}
]
}
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
}