Using Cirrus REST API
  • 10 Nov 2022
  • 5 Minutes to read
  • Contributors
  • Dark
  • PDF

Using Cirrus REST API

  • Dark
  • PDF

Article summary

This reference guide provides general information about the REST API and specific information about each API operation and supported entity type.

Key Benefits

Complete freedom to drive your assessment process
Enables (your) third-party system to drive the full assessment process in Cirrus exactly how your business requires.

Full Feature - No additional cost.
The Cirrus REST API is fully documented and configurable by your system administrator. Neither help nor development from Cirrus required, just your organisation's IT or partner with technical skills.

Full Candidate Lifecycle
Create a candidate, add them to an exam schedule, get a direct exam launh link to give to the candidate, receive the result after its published in Cirrus.

All key processes covered
- Managing Organisation and Content Structure
- Managing Candidates and Users and their Roles
- Managing Assessments, Schedules and Attempts
- Managing Marking
- Getting Results back through a Webhook

Example Scenario

As a lot of stakeholders are interested in this, we've included an Example Scenario, in our Integrations Overview on our regular Knowledge Base.

Readme First

Use this REST API Documentation as your reference

From 1st of July 2021 onward the "REST API Reference" (including this page you're reading) is the authoritative documentation of the Cirrus API.

Cirrus actively maintains the pages here: a) When we receive a technical question or make observations we check this documentation first, and add clarifications and/or corrections, as part of our follow-up. And b) update it when new enhancements become available.

API relies on External IDs - Missing data

If you think your missing information from Cirrus, please read External IDs for Entities

URLs (API Domains and Endpoints)

RegionEnvironment (1)API DomainRemarks URL:
EuropeProductionapi.cirrusplatform.comNot for Premium Hosting
EuropePremium Productionapi-euprem.cirrusplatform.comPremium Hosting only
EuropeRCapi.cirrusrc.euIf your Cirrus domain does not end in '', use the same ending for your API Domain, e.g. for a Cirrus at ''.
CanadaProductionapi-ca.cirrusplatform.comNotice: the '-ca' in 'api-ca'
SingaporeProductionapi-sg.cirrusplatform.comNotice: the '-sg' in 'api-sg'

(1) Normally a Sandbox (e.g. 'custx-sandbox') is hosted on one of our Production clusters (Cirrus domain ending in ''), and you should use the same domain (with a different authorization key). Our internal Test ( et al) and Acceptance Test ( environments occasionally also used by customers and partners during development are not listed.

When you know your API Domain and endpoint you can build the full API URL with your endpoint:{yourendpointgoeshere}

For example to call '/schedule' for Cirrus hosted at '' with external ID 'EXT_sch_1' (Notice how the '' part matches):
The API URL is not customer specific

The API token is customer and domain specific and ensures secure separation of the data. The API URL does not contain your custom domain.

Preparing Cirrus

Authorization using an EAPI Token

To use Cirrus external API first of all you need to generate EAPI token
This can be found via the user interface of Cirrus:

Step 1: Log in to the cirrusplatform as a user with system administrator permissions (or rather a role with the "Manage webservice" permission).

Super User of your organisation is a system administrator

If you don't have a login, please contact the Super User of your organisation to do these steps for you (or create a user for you).

Step 2: Go to Admin > Webservices Group > External API, screenshot (1), (2)
Screenshot 2020-10-08 at 22.19.12.png

Missing Menu?
  1. Check if your user has "Manage webservice", see Step 1.
  2. Still no Webservices Group > External API menu, then request access.

In "External API settings" press “Generate” button (3).
Select the user who will be an owner for all API requests (#1) and click generate button (#2).

Separate API User is recommended

We recommend creating a separate dedicated user per API configuration with all the necessary and appropriate permissions.

The EAPI token will be generated and shown in the EAPI Token field on the page (#3). You can copy it by clicking on “Copy” button

This EAPI token must be used for every API requests by passing as "Authorization" header, see also HTTP Request Headers below.

Other API Settings - Roles and Users

Default candidate roleRole, e.g. 'Candidate'Role to give to new candidate if no role provided.
Default marker roleRole, e.g. 'Marker'Role to give to new marker user if no role provided.
Select schedulerExisting UserSelected existing user, with Schedule permission, will be used by API when creating schedules.
Select invigilatorExisting UserSelected existing user, with Schedule permission, will be used by API when creating schedules.
Select assessment ownerExisting UserSelected existing user, with Manage Assessment permission, will be used by API when creating assessments.
Select collection ownerExisting UserSelected existing user, with Manage Collection permission, will be used by API when creating collections.
Select markerExisting UserSelected existing user, with Marking permission, will be used by API when marking assessments.
Select moderatorExisting UserSelected existing user, with Moderator permission, will be used by API when moderating assessments.
Select publisherSelected existing user, with Publish permission, will be used by API when publishing assessments.
Do not remove users or their permissions

Please, be careful when updating users and role permissions to always ensure the API has valid users with appropriate permissions available.

External IDs for Entities

In Cirrus entities have an external ID field so it can be matched with the ID of external systems. The Cirrus API relies exclusively on these external IDs.

Missing Entities from API

If the external ID field of an entity is empty it will NOT be returned by the API.

If a user fills an external ID Cirrus will check if it is unique (does not exist already for another entity of the same type).

Different names for "External ID"

For several entities the external ID field has a different name, e.g. for Users it's called "User ID", for Hierarchies "Organisation ID". See the different calls.

HTTP Request Headers

All API requests should contain the following headers:

AuthorizationEAPI <token>See Authorization using an EAPI Token in the previous section
Content-type: application/json
Authorization: EAPI Aw36RB7mpHEh1EApMxczgDjtZcCS5lVpjoSS6uxmUV66j8de

Response Model

NameData TypeDescription
ContentObjectResponse data (if data is empty, this field is missing)
SuccessBooleanTrue if operation was successful
ErrorsStringErrors (null if successful)

HTTP Status Codes

The Cirrus REST API follows the established best practises:

Status CodeStatus CategoryRemarks
400-499Client errorsE.g. 400 Bad Request. Fix request before retrying.
500-599Server errorsE.g. 500 Internal Server Error. An error occured while Cirrus Platform processed the request.

Fair Use

The users of the Cirrus REST API have managed to avoid hard rate limits being enforced.

Cirrus reserves the right to introduce rate limits and/or propose charges for excess usage.

Was this article helpful?

What's Next