This reference guide provides general information about the REST API and specific information about each API operation and supported entity type.
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
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.
If you think your missing information from Cirrus, please read External IDs for Entities
URLs (API Domains and Endpoints)
|Region||Environment (1)||API Domain||Remarks|
|Australia||Production||api-au.cirrusplatform.com||(obsolete URL: api-aus.cirrusplatform.com)|
|Europe||Production||api.cirrusplatform.com||Not for Premium Hosting|
|Europe||Premium Production||api-euprem.cirrusplatform.com||Premium Hosting only|
|Europe||RC||api.cirrusrc.eu||If your Cirrus domain does not end in 'cirrusplatform.com', use the same ending for your API Domain, e.g. api.cirrusrc.eu for a Cirrus at 'mytest-cirrusrc.eu'.|
|Canada||Production||api-ca.cirrusplatform.com||Notice: the '-ca' in 'api-ca'|
|Singapore||Production||api-sg.cirrusplatform.com||Notice: 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 'cirrusplatform.com'), and you should use the same domain (with a different authorization key). Our internal Test (api.cirrus1.eu et al) and Acceptance Test (api.cirrusat.eu) 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:
For example to call '/schedule' for Cirrus hosted at 'custx.cirrusplatform.com' with external ID 'EXT_sch_1' (Notice how the 'cirrusplatform.com' part matches):
The API token is customer and domain specific and ensures secure separation of the data. The API URL does not contain your custom domain.
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).
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)
- Check if your user has "Manage webservice", see Step 1.
- 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).
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 role||Role, e.g. 'Candidate'||Role to give to new candidate if no role provided.|
|Default marker role||Role, e.g. 'Marker'||Role to give to new marker user if no role provided.|
|Select scheduler||Existing User||Selected existing user, with Schedule permission, will be used by API when creating schedules.|
|Select invigilator||Existing User||Selected existing user, with Schedule permission, will be used by API when creating schedules.|
|Select assessment owner||Existing User||Selected existing user, with Manage Assessment permission, will be used by API when creating assessments.|
|Select collection owner||Existing User||Selected existing user, with Manage Collection permission, will be used by API when creating collections.|
|Select marker||Existing User||Selected existing user, with Marking permission, will be used by API when marking assessments.|
|Select moderator||Existing User||Selected existing user, with Moderator permission, will be used by API when moderating assessments.|
|Select publisher||Selected existing user, with Publish permission, will be used by API when publishing assessments.|
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.
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).
HTTP Request Headers
All API requests should contain the following headers:
|See Authorization using an EAPI Token in the previous section|
Content-type: application/json Authorization: EAPI Aw36RB7mpHEh1EApMxczgDjtZcCS5lVpjoSS6uxmUV66j8de ...
|Content||Object||Response data (if data is empty, this field is missing)|
|Success||Boolean||True if operation was successful|
|Errors||String||Errors (null if successful)|
HTTP Status Codes
The Cirrus REST API follows the established best practises:
|Status Code||Status Category||Remarks|
|400-499||Client errors||E.g. 400 Bad Request. Fix request before retrying.|
|500-599||Server errors||E.g. 500 Internal Server Error. An error occured while Cirrus Platform processed the request.|
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.