Absorb Integration API

Welcome to the documentation for Absorb Integration API.

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

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

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

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

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

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

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

8. File Uploads

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

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

10. Support

• Announcements, Knowledge Base, Community and Release Notes

When contacting the support team regarding 500 errors, please include all relevant X-Absorb-Correlation-Id and x-amzn-RequestId response header values.