The Absorb Integration 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. 

For more information on the terminology used in this article, please see the Integration API Glossary.

For a full list of API calls available, and examples for operations such as OAuth 2.0 authentication, review the Absorb Integration API documentation:

• Absorb API Documentation 

What You'll Need to Get Started

REST Client

For this guide, we will use the Postman app for Chrome as our REST client. This article will cover everything you need to know to use with the Absorb Integration 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 Integration 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 an API Private Key, please work with your Absorb account team to discuss access to the Integration API.

The Service Gateway

All Integration API endpoints will need to go through the service gateway, meaning you’ll put the service gateway URL before all requests in your Portal listed in the Integration API documentation.

Absorb offers region-specific access, which would align with the region where your Portal is hosted.

• US – https://rest.myabsorb.com
• CA – https://rest.myabsorb.ca
• EU – https://rest.myabsorb.eu
• AU – https://rest.myabsorb.com.au

To connect to a sandbox environment, you must use one of these four additional endpoints.

Note: A sandbox environment must be created, not all Portals contain an active sandbox.  

• US – https://rest.sandbox.myabsorb.com
• CA – https://rest.sandbox.myabsorb.ca
• EU – https://rest.sandbox.myabsorb.eu
• AU – https://rest.sandbox.myabsorb.com.au

Your Admin Credentials

Your LMS Admin credentials will be used as 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. 

Integration API Documentation

Your System Admin will be able to access the API documentation by navigating to https://docs.myabsorb.com/ after subscribing to our API service. The Integration API documentation contains general API information and lists the resources. Each resource has its own URL that defines the API operations on it. Meanwhile, the Integration API documentation describes a resource, including its API calls and models. There is one file per resource.

• For more information about our API technical documentation, please click here.

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 Admin 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). 

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 request to the following request URL:

.../authenticate 

1. Add the service gateway URL of your environment to the beginning of the above string. 
2. Change your request type to “POST”.
3. 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.
4. Enter "Content-Type" in the HEADER field and "application/json" in the VALUE field.
5. You will also need to include the “x-api-key" in the https header by adding “x-api-key" as the key in the header type and the value of it is the private API key.
   
6. While on the body tab in Postman click on the content-type dropdown and select JSON (application/json).
   
7. Enter your credentials and privateKey as they are shown below:
   
8. Click SEND.
9. 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:

.../users/{userId}

1. Add the service gateway URL of your environment to the beginning of the above string.
2. Change your request type to GET.
3. 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. 
   
4. You will also need to include the “x-api-key" in the https header by adding “x-api-key" as the key in the header type and the value of it is the private API key.
5. 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.
6. Click SEND.
7. 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:

.../create-absorb-account

1. Add the service gateway URL of your environment to the beginning of the above string
2. Change your request type to POST
3. 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.
4. Similar to the authentication, select content-type for the KEY field and the Value to application/json.
5. You will also need to include the “x-api-key" in the https header by adding “x-api-key" as the key in the header type and the value of it is the private API key.

6. Please refer to our Integration API documentation 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": "613048f5-87c9-442a-915e-edf63cf517b2",
   "firstName": "Sample First Name",
   "lastName": "Sample Last Name",
   "username": "Sample.user",
   "password": "Absorb2022!"
   } 

7. 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:

How to Use Integration API Documentation

Our Integration API documentation lists 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. For example, all course related API requests are contained in the Courses section. In each section, you'll find a list of available request URLs as well as a description.

This documentation can be found here.

• You can find the list of the functional areas on the left navigation and each one of them has its own section.
  
• Each functional area has a list of the endpoints underneath it. Select the top-level section in the documentation and you will be presented with all related endpoints.
  
• Clicking each one of the endpoints redirects to the location of the endpoint in the page. The endpoint path and sample responses will display on the right side of the page
• The query parameters, header parameters, body schema and attributes needed are shown in the center of the page.

Error Messages

Error messages for Integration API 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:

Pagination Best Practices

In the newer version of our Integration API, support for Pagination was added to several open-ended GET endpoints. These endpoints were both highly used and tended to return the largest data sets. While a single open-ended GET call is efficient from the client’s perspective, this is not the case at scale. When many clients make open-ended GET calls, job queues can get backed up, leading to poor response time for all API users. Like time-sliced multi-threading, breaking large jobs into small pieces allows many simultaneous requests to be serviced while maintaining responsiveness.

Best Practices 

When paginating through a dataset that is being constantly updated, there is a risk that returned records will differ from the database. It is possible that records are altered during Pagination shift position in the record set, causing them to be returned on more than one page, or in extreme cases not be returned at all. 

Two new attributes: dateAdded and dateEdited have been added to resources returned from paginated calls. Not only do they enable highly targeted filtering, but they also can be used to reduce the risk of data accuracy issues described above.

Below we describe two commonly used methods:

Frozen Snapshot

To closely emulate the behavior of an open-ended GET call, use filtering to return only records added or updated before the first pagination call. Like a non-paginated open-ended call, anything added after Pagination starts will not be included.

Sorting Oldest to Newest

To reduce the risk of excluding added records, use sorting to return the oldest records first (sorting on dateAdded), and any records added after Pagination started should show up on the last page(s). It’s a best practice to never sort results from newest to oldest.

If you have any questions or feedback about this article, please contact your Customer Success Manager or Account Manager for further assistance.

Frequently Asked Questions (FAQ)

The follow address frequently asked questions related to the Integration API.

• 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?
  • Yes, Webhooks are currently available with Integration API.
• 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 Integration 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.
  • EX: "2021-01-21" or optionally yyyy-MM-ddTHH:mm:ss.fff, e.g. "2021-01-21T18:25:13.000".
• Does Absorb have an API call limit?
  • Yes. The Absorb Integration API uses a number of safeguards against bursts of incoming traffic to help maximize its stability and reliability. Consumers who send many requests in quick succession might see error responses that show up as status code 429 - Too Many Requests.
  • Requests to the API are limited to a 100 request burst allowance on top of 200 calls per second.