Developer API
Litmos' Application Programming Interface (API) enables developers to connect external applications to Litmos LMS. The API gives organizations the ability to streamline data and processes across information systems for operational efficiency, including the automation of training assignments and the moderation of administrative tasks.
The Litmos API is not enabled on Trial accounts. See our SAP Litmos pricing page for more details.
Important Note: Most of the actions performed via the Litmos UI are available via the API. If there is something in particular that you’re looking for and you can’t find it in the documentation please let us know and we will work on making that available!
HTTP Verbs
Any requests for a single resource or list of resources (e.g. course list) will use a GET.
Insert (POST) or update (PUT) requests often require structured XML or JSON in the HTTP request body.
At this stage DELETE requests are not available on all resources and are limited to certain objects.
Authentication & Access Level
Every request to the API must be transmitted over a secure channel using HTTPS and authenticated by passing an apikey as a Header parameter. Access to API requests is limited to Account Owners only.
Header Parameter |
Type |
Description |
---|---|---|
apikey |
String, max length 50 characters |
Every user in Litmos has a unique API KEY. Access to requests on the API is restricted by each users Access Level (i.e Learner, Team Leader, Administrator, or Account Owner). Only Account Owners will be able to view their API Key in their profile. Note: Contact an Account owner to retrieve a valid API Key. |
Making Requests
All requests will flow through the API URL paths based below, depending on the application environment:
Environment |
Uri |
---|---|
AU environment |
https://api.litmos.com.au/v1.svc
|
EU environment |
https://api.litmoseu.com/v1.svc
|
US environment |
https://api.litmos.com/v1.svc
|
Required Parameters: The "source" parameter is required on all API paths and must be appended to the Uri. This value can be any particular value, so long as it is not blank. The source can be used for a variety of logging purposes, for example, to keep track which program the calls originated from or who the calls were executed on behalf of.
Example: https://api.litmos.com/v1.svc/users?source={source}
Content Type
Communication with the API can be conducted using Plain Old XML (POX) or JavaScript Object Notation (JSON).
Any requests that includes data in the body must include a Content-Type header (i.e. POST/PUT/DELETE).
Content-Type |
Description |
---|---|
application/xml |
Plain Old XML (POX) |
application/json |
JavaScript Object Notation (JSON) |
The Content-Type that is passed with each request to the API indicates the format with which the response will take for GET requests, and, what format the API expects the request body to be in the case of PUT or POST requests. In order to receive JSON format response, please append "&format=json" to the Uri.
Example:
GET https://api.litmos.com/v1.svc/users?source=(source)&format=json
Response Codes
Based on RESTful principles the API returns relevant HTTP Status codes when actions succeed or fail.
If a request is successful you will get a status code response in the 200 range. Sometimes it will be accompanied by XML or JSON in the response body. For example, if you successfully update a user then you would get a 200 but if you successfully create a new user you will get a 201 (Created) response back with the XML/JSON for that new user in the body.
If a request fails you will get a non 200 status code and often a description of why the request failed.
Here are some of the common responses codes and things to check
HTTP Status Code | Description |
---|---|
200 |
Success. User/Course etc updated, deleted or retrieved |
201 |
Success. User/Course etc created |
400 |
Bad Request. Check that your URI and request body is well formed |
403 |
Forbidden. Check your API key, HTTPS setting, Source parameter etc |
404 |
Not Found. The User/Course etc that you requested does not exist |
409 |
Conflict. Often occurs when trying to create an item that already exists |
503 |
(Service Unavailable) - Rating Limit Exceeded |
Date Formats
All fields marked as datetime are recorded in UTC where the XML format is returned in ISO 8601 and the JSON format is returned as a JSON .NET DataContractJsonSerializer string.
Example:
XML "2020-12-31T15:36:30"
JSON "/Date(1606879800000+0530)/"
API Usage Limits
Under our standard agreement, there is a limit of 100 requests per minute that a provider can make against a particular Litmos account. This rate limit is based on a rolling 60-second window. If the API token has been used more than 100 times in the past 60 seconds you will have exceeded the rate limit and the API will return HTTP 503 (Service Unavailable) - Rating Limit Exceeded.
Search & Paging Parameters
Many of the list based GET requests support searching and paging. If a request is documented as supporting paging the following parameters can be used to filter or restrict the result set returned.
All of the search and paging parameters are optional and can be used singularly or in a combination. By default paging will return the first 100 records but you can increase this to a maximum of 1000 records as required by using the limit parameter.
Querystring Parameter | Description | Possible Values |
---|---|---|
start |
Start record |
0+ (Default = 0) |
limit |
Total records to return |
1 – 1000 (Default = 100) |
sort |
Field to sort results using |
FirstName, LastName, UserName, Active, Email |
dir |
Direction to sort the records |
ASC or DESC (Default = ASC) |
search |
String value to filter records using |
String. Max length 50 |
Links to API Call Details
Single Sign On
Log straight into a course index/landing page
Courses
Get a list of users Assigned to a Course
User Profile information
Users and Courses/ Modules
List Courses assigned to a User
List all User Results for a Course
List Course and Module Results for a User
List All Course Results for All Users Since a Specific Date
Get a list of Recent Achievements
Reset Course Results for a Learner
Team Leaders
Remove a Team Leader from a Team
Course Assignment to Teams
Team Profile Information
Get a list of Courses assigned to a Team
Add & Remove Users from a Team
Assign a User to a List of Teams
Get a List of All the Teams a User is Assigned to
Gamification
Get Total Badges and Points For User
Get List of Badges Earned By User
Get List of Achievements Earned By User
Get List of Achievements Earned By Team
Learning Paths
Get Learning paths assigned to a specific User
Assign users to a Learning Path
Remove a user from a Learning Path
Get all Learning Paths assigned to a Team
Assign Learning Paths to a Team
Remove Learning Paths from a Team
Instructor Lead Training (ILT)
Get Session List for an Instructor
Mark Session complete and add score
Date Range Delta Query APIs
Self-Signup Tokens
eLearning Files
POST, PUT & GET SCORM/Tin Can courses (modules)
Add AICC/SCORM/Tin Can modules to courses & Remove AICC/SCORM/Tin Can modules from courses
Learning Record Store (xAPI)
Webhooks
Achievement.earned (course and learning path)
Comments
0 comments
Article is closed for comments.