Contents x
    Using Cirrus REST API
    • 21 Aug 2024
    • 5 Minutes to read
    • Contributors
    • Print
    • Dark
      Light
    • PDF
    Contents

    Using Cirrus REST API

    • Updated on 21 Aug 2024
    • 5 Minutes to read
    • Contributors
    • Print
    • Dark
      Light
    • 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
    AustraliaProductionapi-au.cirrusplatform.com(obsolete URL: api-aus.cirrusplatform.com)
    EuropeProductionapi.cirrusplatform.comNot for Premium Hosting
    EuropePremium Productionapi-euprem.cirrusplatform.comPremium Hosting only
    EuropeRCapi.cirrusrc.euIf 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'.
    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 '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:

    https://api-aus.cirrusplatform.com/api/v1/integrations/{yourendpointgoeshere}

    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):

    https://api.cirrusplatform.com/api/v1/integrations/schedule/EXT_sch_1
    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 Integrations" 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 Integrations", 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

    FieldValueDescription
    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.
    Region
    TimeZone
    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:

    HeaderValueRemarks
    Content-typeapplication/json
    AuthorizationEAPI <token>See Authorization using an EAPI Token in the previous section
    Example:
    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
    200-299SuccessSuccess
    300-399RedirectsN/A
    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