Developer API

The Litmos API (Magnum) enables developers to connect their applications to the Litmos training engine. This allows for greater integration of training data generated in Litmos with any other systems that are currently used within your organization.

We’ve tried hard to make the Litmos API as RESTful as possible where each resource has a unique URI and HTTP verbs are used to specify the action to perform on that resource.

Note: The Litmos API is not enabled on trial accounts and is only avilable for Silver price plan or above. See our pricing page for more details.

What can I do using the API?

Users

Achievements

Courses

Teams

Sample Code

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 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 a few documented requests.

Authentication & Access Level

Every request to the API must be transmitted over a secure channel using HTTPS and authenticated by passing an apikey and source value in the querystring. Access to most API requests is limited to Administrators only.

Querystring Parameter Type Description
apikey String, max length 50 characters Every user in Litmos has a unique apikey. Access to requests on the API is restricted by each users AccessLevel.Eg.Learner, TeamLeader, Administrator, or Account OwnerNote: To get your API key please email support [at] litmos.com and we will set it up for you.
source String, max length 50 characters Free text description of your app. Usually a company or product name.

Making Requests

All requests listed in this document should contain a content-type (XML or JSON) in the request header and be prefixed with the following base Uri:

https://api.litmos.com/v1.svc

E.g. The Uri to GET a list of Users in XML format would be:

Content-Type: text/xml

GET https://api.litmos.com/v1.svc/users?apikey=MY-KEY&source=MY-APP

Content Type

Communication with the API can be conducted using Plain Old XML (POX) or JavaScript Object Notation (JSON).

With every request you must include a Content-Type header.

Content-Type Description
text/xml Plain Old XML (POX)
application/json JavaScript Object Notation (JSON)

The Content-Type that is sent with each request to the API indicates which format the response will be for GET requests and what format the API expects the request body to be in the case of PUT or POST requests.

Response Codes

Based on RESTful principles this 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 and sometimes it will be accompanied by XML or JSON in the response body. Eg. 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

Date Formats

All fields marked as datetime are recorded in UTC and returned in ISO 8601 format.

E.g. 2009-12-01T02:27Z

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 singly or in a combination. By default paging will return the first 100 records but you can increase this 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 Possible options detailed on each request through this document
dir Direction to sort the records ASC or DESC (Default = ASC)
search String value to filter records using String. Max length 50

More…

Revisions

One Response to “Developer API”

  1. Ben Ubois March 5, 2013 at 3:55 pm #

    In order to get JSON back for a GET request you need to set an `Accept: application/json` header maybe the `Content-Type` header is just for POST/PUT?

Leave a Reply