Inspera Assessment API

v1.1 

General information

The Inspera Assessment API is a set of open REST APIs allowing external systems to access a subset of Inspera Assessment functionality using Inspera Assessment user privileges. The functionality provided will include creating and updating tests, assigning and removing learners and contributors from tests, exporting results and responses after grading, as well as user management. 

We develop and update and add new APIs continuously. All changes and additions to existing APIs, as well as new developed APIs and API roadmap plans are announced through Inspera's release notes. Please see our product site to learn about how to subscribe to release notes here: https://support.inspera.com/hc/en-us/articles/360038889831-Product-updates-release-notes-2020

Inspera APIs in customer landscape

Illustration of how APIs fit into customer system landscape (APIs and integration in general are presented as blue blocks)

Open

Inspera's APIs are build as groups of APIs, depending on the functions and modules in Inspera Assessment they touch upon:

• Candidate API group (handle export of learner submissions and results export)

  • Export of learners submissions (PDF)

  • Export of learners results (JSON)

• Test API group (APIs to transfer test events to Inspera Assessment)

  • Create or update tests

  • Assign or remove learners and contributors

  • Export of test materials (PDF / QTI)

  • Export of test metadata

  • Register or redraw appeals

  • Set or change test settings New

  • Register or export explanations

  • Search tests based on criteria

•  Users API group (transfer users from external systems to Inspera Assessment)

  • Create, update or delete administrative users

  • Create or update learners (students)

  • Search for users

  • Export user information

We also provide set of Webhooks and events to make  machine - to - machine integrations possible. Inspera provides a set of events that systems can subscribe to and act accordingly to make workflows between systems possible. We update and add new events continuously, full overview over available events can be obtained from GET action on the following: https://ia.inspera.no/apidoc/#/webhooks_(beta)/listAllSubscriptions

Getting started

First steps

To get started, you will need a user in Inspera Assessment, with Administrator privileges. From the user profile interface, you will then be able to access the API key details for either yourself or other Inspera users in your organization. These authorization details will include an API key (authorization code). In addition to this code,  client id is needed to be able to send API call to obtain authentication token. This will be explained later in this document.

The API key will be accessible only once and if a user loses or forgets their API key, any administrator for your organization will be able to revoke that user's access and generate a new code for them.

Where is API key in Inspera Assessment user interface?

Open "User administration" from Inspera Assessment main page and search for user you want to generate key for. The following will appear on the screen:

Open

How to obtain client_ID?

"client_ID" is a parameter needed for the correct access token to be generated. This value is, in most cases, host-part of the domain of your Inspera Assessment url. For instance, if your Inspera URL is https://test.inspera.com/ , clientID will be "test".  However, this may not be the case for all clients, in which case, please contact us at api@inspera.com.

Once a user has their authorization code and have obtained client id, they will be able to start using the APIs.

Update release December 2020:

ClientID is now visible in Inspera Assessment together with API key generation field:

Authentication and access tokens

An authentication code and client id are not directly used to access the APIs - a user will first have to call the Authenticate API (see below) and acquire a short-lived access token. All of the actual API calls will then be made using this token. Once a token expires, users will need to acquire a new one, using either the original authentication code, or using a refresh token provided by the Authenticate API (refresh tokens are not implemented at the moment).

Making API calls

The APIs listed below are available via HTTPS requests (see the specific API documentation for details).

To obtain access token, call should be made in the following format:

curl -d "" -H "code:<your user API authorization code>" "https://<your inspera domain>/api/authenticate/token/ ?grant_type=authorization_code&client_id=<your client_id>"

All the APIs assume a base url in the following format:

https://<your inspera domain>/api 

In this table you will find key values for API authentication:

Sample scenario using command line tools to authenticate and get test results

Below we go through using the API from the command line, assuming the curl tool is installed. Since all messages are in JSON, jq is also very handy and will give you color coding and easy data extraction when working from the command line or in shell scripts.

This scenario is not covering all details - please see the actual API documentation for the specifics on the formats of the requests and responses.

Sample

Required data used in this sample

Step 1: authenticate and obtain access token

Note:

The option -d "" makes curl send a POST request with empty body and content type application/x-www-form-urlencoded, which the authentication API requires.

This will, if successful, return a JSON containing an access bearer token (in this example: "xyz-abcd-efg" and a lifetime in seconds)

The response will look like:

Step 2: Send API call

Example 1:

In this example, API call is made to get test metadata for test with testID=12312312 using this API https://ia.inspera.no/apidoc/#/test/getTestMetadata

Or, if we wanted to keep the access token from the command line, we can use jq to just store it as an environment variable and reuse it:

Example 2:

In this example, API call is made to export results for a learner on a given test using this

test_id= 12312312

user_id=987654

Since this API can fetch a significant amount of data, it will, instead of immediate results, return a callback url:

Performing a get for this will return either the status of the export, or, once it's done (usually under 5s), a short-lived url for downloading the JSON of the export.

Finally, the admin user can take the provided url and download and use the export of the test results.

Code Example

See Code Example.