Skip to main content
Version: v2

Absorb Integration API

Welcome to the documentation for Absorb Integration API.

1. API Routes​

Integration API requests should be routed to the appropriate route based on your environment. The routes can be found below:

2. Private API Key​

The Absorb Integration API requires a private key provided by X-API-Key header for authorizing each request. The private key can be obtained in the portal settings. Accessing the Absorb Integration API without a valid key results in a 401 Unauthorized response.

3. Authentication​

The Integration API offers different methods of authenticating to the API. Please see the list below for available methods:

  • OAuth 2.0
    • This is the recommended authentication flow, as it offers more security and does not require credentials be provided to authenticate everytime.
      • We have an entire workflow process here: OAuth 2.0
    • Supports on-behalf-of flows.
      • on-behalf-of allows a User to request a token for another User without requiring their credentials. This allows you to perform actions and make requests on behalf of the User.
  • /authenticate

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.

note

All authentication methods will return a token that is valid for four hours after generation. However, only one token can exist for a specific user for tokens generated through the /authenticate method. This means that if a new token is generated for a user, any previously generated token for that user will be invalidated.

4. Pagination​

Supply both _offset=[numeric value] & _limit=[numeric value] query string parameters on specific GET requests to paginate returned results. Offset is the current page, with 0 being the first. Increment this value on successive calls until no records are returned. If no pagination parameters supplied, default pagination settings are _offset=0&_limit=20. The max limit is 1000 and the max offset is 65535.

For example:
https://[path]/[endpoint]?_offset=0&_limit=100

tip

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.

Paginated endpoints will typically return two properties: dateAdded and dateEdited. These can be used in combination with filters and/or sorting to ensure that records are not missed or duplicated during pagination. For example, you could sort by dateAdded in ascending order and filter for records with dateAdded greater than the time of your first pagination call to ensure that you are not missing any records.

5. Sorting​

Use _sort query string parameter on specific GET requests. Supply a comma-separated list of sort keys. The default sort order is ascending. Prefixing '-' before the sort key will return results in descending order.

For example:
https://[path]/[endpoint]?_sort=-relevance

Sorting Nested Properties - e.g. User Custom Fields​

Some endpoints support the ability to sort on nested properties. For example, we support sorting on a user's custom fields. The above syntax rules are still applicable. The difference is in how the property is accessed. Nested properties can be assessed using the syntax [parentProperty]/[property].

For example:
https://[path]/[endpoint]?_sort=-customFields/decimal1

6. Filtering​

Use _filter query string parameter on specific GET requests. Supported operations (based on OData filter syntax) include:

  • Operators: eq, ne, gt, ge, it, le, and, or, not, ()
  • Functions: substringof, endswith, startswith, tolower, toupper

For example:
https://[path]/[endpoint]?_filter=startsWith(lastname, ‘leb’) or dateAdded ge datetime‘1999-0306T20:38:07Z’

Filtering Nested Properties - e.g. User Custom Fields​

Some endpoints support the ability to filter on nested properties. For example, we support filtering on a user's custom fields. The above syntax rules are still applicable. The difference is in how the property is accessed. Nested properties can be assessed using the syntax [parentProperty]/[property].

For example:
https://[path]/[endpoint]?_filter=customFields/string1 eq 'test'

note

Due to technical limitations, we do not support blank string ('') and null as values in nested property filters.

7. Dynamic Rules and User Updates​

Assets that use dynamic rules to control users' access may take a short delay to process and reflect modified user values. For example, an online course that has an automatic enrollment rule 'Job Title equals "Supervisor"' may not immediately enroll a newly created learner who has the "Supervisor" job title for up to 10 minutes. This delay allows the system to process multiple updates together in a more efficient manner and avoid overloading the queue with individual updates.

8. Versioning​

The Integration API supports multiple versions concurrently in order to allow consumers to update their integrations at their own pace. Each request will accept a new version header x-api-version. This header is not required, but is recommended for consumers that may not always have the resources to adopt the latest changes to the API. The value of the header will be the version number you wish to use. For example, if you wish to use v2, specify x-api-version=2. In addition, each response from the API will include a version header to help indicate which version you are currently receiving for the given endpoint from the API. Version specific documentation is available to be selected in the dropdown menu on the navigation sidebar. Please note that while backwards compatibility is enabled, you will be restricted to version 1.

9. Rate Limiting​

The Absorb Integration API uses a number of safeguards against bursts of incoming traffic to help maximize its stability. 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 200 per second. There is a burst limit of an additional 100 requests, to act as a buffer if you have a short overrun. Treat these limits as maximums. If you suddenly see a rising number of rate limited requests, please contact support.

tip

A basic technique for integrations to gracefully handle limiting is to watch for 429 status codes and build in a retry mechanism. The retry mechanism should follow an exponential backoff schedule to reduce request volume when necessary. We'd also recommend building some randomness into the backoff schedule to smooth out the retried traffic, avoiding another burst.

Another option to consider would be to control traffic to Absorb at a global level, and throttle back if substantial rate limiting is detected in the API responses.

10. File Uploads​

The Absorb Integration API does not currently support file uploads. If you require file uploads, please utilize the Absorb UI instead.

11. Data Consistency​

We recommend implementing robust data consistency checks on your end to ensure the integrity of the information processed through the API. This would involve validating the data you receive from our system, ensuring that it meets the expected formats, ranges, and types. Additionally, performing regular audits of key transactions and cross-referencing critical data points against your internal records will help quickly identify and resolve any discrepancies. These checks will ensure that the data remains accurate and consistent throughout its lifecycle.

12. 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?

    • Yes, webhooks are currently available and intended to be used in unison with the 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 ISO 8601 date (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 Integration API has rate limits. More information can be found in the Rate Limiting section of this article.

  • Does the Integration API documentation support a "Try It Now" feature?

    • Yes, the Integration API documentation supports a "Try It Now" feature that allows you to make API calls directly from the documentation. This feature is only available on Absorb sandbox environments. If you do not have a sandbox, please reach out to your Absorb contact to get one created.

13. Support​

All responses returned from Absorb should include an X-Absorb-Correlation-Id header. To assist with any troubleshooting you may have, it is best practice to log the correlation ID for all requests. Additionally, most requests also contain a x-amzn-RequestId header that is similar in nature to the previous header. If present, it is also best practice to include this value for requests. When contacting the support team, please include all relevant X-Absorb-Correlation-Id and x-amzn-RequestId response header values.