The Absorb RESTful API has been designed to allow customized interactions with your LMS data including learners, courses, departments, grades, etc. You can also use it to build specialized interfaces, unique reports, integrations, and so on. The use of the API will require technical web experience on your part but this guide should serve as a jumping-off point for those interested.
Frequently Asked Questions (FAQ)
- Is there a limit to the number of users I can set up with API access? No, you can set up as many users as you wish. We recommend creating a user for each unique workflow that is in place
- Does Absorb provide webhooks? Unfortunately, webhooks are not currently available with RESTful API
- Which data formats are available? Data from the RESTful API can be returned in either JSON, HTML, or XML formats by using the appropriate 'content-type' parameter in a request. Each example in the help documentation is presented in all three formats for reference
- Does Absorb have an API call limit? No, however, Absorb reserves the right to restrict API usage if client API calls impact system performance
- Is there pagination or limits for API calls? Some endpoints support pagination using the limit and offset parameters. The limit parameter determines how many records will be returned, and the offset parameter determines the page of results (starting with 0) to return. For endpoints that don't support pagination, a useful alternative is to use the ModifiedSince parameter, which is available for most of the larger API calls, to effectively paginate the data (i.e. first return all records modified since 2019-01-01, then 2020-01-01, etc.)
- Can I request a token or carry out API calls from another domain that's not Absorb? This is known as Cross Origin Resource Sharing (CORS). Absorb's RESTful API does not support CORS
- What date formats are supported by Absorb's API? Any date fields will accept a 'plain' date in the yyyy-MM-dd format, e.g. "2021-01-21" or optionally yyyy-MM-ddTHH:mm:ss.fff, e.g. "2021-01-21T18:25:13.000".
What You'll Need To Get Started
RESTful Client
For this guide we will be using the Postman app for Chrome as our RESTful client. This article will cover everything you need to know to use it with the Absorb LMS RESTful API, but you can visit Postman - Getting Started if you'd like to learn more about this app. While the workflow in this guide may not be step-by-step the exact same as in your software, the concepts discussed should be universal.Your API Private Key
If you are an Absorb LMS RESTful API customer, you will have been provided with an API private key that is tied to your LMS portal. This key is used to authenticate prior to any requests via the API. If you do not yet have a key, please contact us to discuss purchasing one.Your Site URL
Your LMS URL will be the root location for all API requests, meaning you'll put your site URL before all requests listed in this article. This will be the URL used to access your learner interface.Your Admin Credentials
Your LMS admin credentials will be used as a part of the authentication process. Similar to the admin interface, your admin role will determine which areas of the LMS you are permitted to access through the API.RESTful API HelpRESTful API Help lists out all of the requests available through the Absorb RESTful API, sorted by various functions/areas in the LMS.
Generating An API Token
All requests to the LMS must include an API token as authentication. This token is generated using your API Private Key and your Absorb user account credentials and will be used to verify both client access to the API as well as a specific admin's access to certain LMS data (based on their admin roles set up in the LMS).
Tokens are only valid for 4 hours after they have been generated or until the same username requests a token, whichever comes first.
It is important to note that requesting an API token will invalidate any previous token that existed for that user. If you require multiple API workflows we recommend creating one admin user for each workflow to prevent workflows from invalidating each other's tokens.
To generate a token you'll need to make a POST to the following request URL (the examples in red will be replaced with your own variables):
/api/Rest/v1/Authenticate
- Add your site URL to the beginning of the above string
- Change your request type to POST
- The POST will contain the authentication data in the body of the request. Before you can do this, you'll need to specify a content-type as a header in the request or from the content-type dropdown.
- Enter "Content-Type" in the HEADER field and "application/json" in the VALUE field.
- While on the body tab in Postman click on the content-type dropdown and select JSON (application/json)
-
- Enter your credentials as they are shown below
- Click SEND
- Your API token will be returned in the body of the response below
Making A GET Request
GET requests pull data from the LMS and display it in the body of the API response. For example, you could make a request to return a list of all enrollments for a particular user or return information on a particular resource.
In this example, we'll send a GET request to return all the information for a particular user. This request can be made to the following request URL:
/api/Rest/v1/Users/{id}
- Add your site URL to the beginning of the above string
- Change your request type to GET
- Add your API token as a header to authorize the request. In Postman you can enter this after clicking the HEADERS button in the top-right. Enter "Authorization" in the HEADER field and your API token in the VALUE field.
- Fill in the Absorb userID for the user you are returning data for. This can be found in the Id column in Absorb's USERS report, or alternatively returned via the API in other GET requests.
- Click SEND
- A list of learner data will be returned in the body of the response
Making A POST Request
POST requests add new data to the LMS and display a confirmation in the body of the API response. For example, you could add a new department or enroll a user in a course.
In this example, we'll send a POST request to add a new user to our LMS. This request can be made to the following request URL:
/api/Rest/v1/createabsorbaccount
- Add your site URL to the beginning of the above string
- Change your request type to POST
- Add your API token as a header to authorize the request. In Postman you can enter this after clicking the HEADERS tab just below the address bar. Select "Authorization" in the KEY field and your API token in the VALUE field.
- Similar to the authentication, select content-type for the KEY field and the Value to application/json.
- Alternatively, you can set this value on the Body tab as we did in the ‘Generating An API Token’ section.
- In this example, we'll send the body of this request in JSON. Change your data mode to RAW and select JSON as the data type for the editor below.
- Click Here for a full list of body parameters that can be sent with this request, but to create a new Absorb user we only need a handful of required parameters. The DepartmentId can be found in the Id column in Absorb's DEPARTMENTS report, or alternatively returned via the API in other GET requests. The rest of these parameters will be the data you are entering for this user. {
"DepartmentId": "399c6b48-9c91-413f-94ca-0a259f773839",
"FirstName": "Sample",
"LastName": "User2",
"Username": "sample.user2",
"Password": "ab5orb!ap1",
"EmailAddress": "sampleuser2@absorblms.com"
} - Click SEND
- A confirmation will be returned in the body of the response containing the Id of the newly created user, as well as their username. You can verify that this user has been added by checking the USERS report in the admin interface.
These are some commonly seen HTTP status codes for the API calls
200 OK
This means that the call was successful.
201 Created
This means that a post to create a user, course, etc. was successful
400 Bad Request
This means that the payload within the API call has some sort of error in it (ie. incorrect data value, syntax, etc.)
401 Unauthorized/403 Forbidden
This means that user who created the API session token is unauthorized to access that area of the LMS, or that an API session token was invalidated by another call (rendering the previous call unauthorized)
500 Internal Server Error
This means that there is an error on our end, please contact support if you see this.
How To Use Absorb LMS RESTful API Help
Our Absorb LMS RESTful API Help site documents every API request we currently have in our system, as well as detailed information on all request and response parameters. This page is divided up based on different areas of functionality, called controllers. For example, all resource-related API requests are located in the ResourcesController. In each controller section, you'll find a list of available request URLs as well as a description.
Each request has its own page that will outline detailed information about that request.
- Required Permissions will tell you which admin role permissions are necessary to work with the request
- Request Information provides a list of both URL parameters (included in the request URL) and body parameters (included in the body of the request). This list will include a description of each parameter, its data type, and if that parameter is required in the request. Request formats are also included for several requests that will give you a few examples of how your request body can be formatted.
- Response Information provides a list of response parameters that will be returned upon the successful execution of the request. Response formats are also included for several requests that will give you a few examples of how your response body can be formatted.
Note: You can click the Code button and select a listed programming language to see how Postman recommends you program the related API call.
API Object Diagram
Error Messages
Error messages for Restful API V1 endpoints will include a message so that you know what action is needed to resolve the problem. The following is an example of an error message:
