Get Assessment Results
Get /results
There are some constraints around getting results from Cirrus:
Results must be assessed/marked
Results must be published (FYI: If assessment marking workflow is “Do not assign assessors” then results can be received immediately after the attempt has been submitted else a user needs to manually publish them).
For most use-cases Webhooks are strongly advised!
As a Cirrus Webhook will push new results to your system the moment they become available so your systems does not have to frequently check (poll) this method.
Throtteling
For the result API a API Throtteling is in place for 3000 calls per day. This will be reset automaticly on 13:30 UTC
Header
| Name | Data Type | Description |
|---|---|---|
| Content-type: | application/json | for all requests |
| Authorization: | EAPI {token} | for all requests |
Request Parameters
Parameters indicated with a * are mandatory
| Parameter | Type | Description |
|---|---|---|
| *CandidateExtId | String(64) | UserID in Cirrus (if string contains special charsets, it must be encoded. |
| ScheduleExtId | String(64) | Schedule external id (if string contains special charsets, it must be encoded. |
| AttemptExtId | String(64) | Attempt external id (If this parameter is used then CandidateExtId is not mandatory) |
If ScheduleExtId is not set then all results for user with CandidateExtId will be returned.
If ScheduleExtId is set, results for the schedule will be returned.
If AttemptExtId is used, results for this specific attempt will be returned.
Common errors
- Bad request
- Url not found
- Any missing parameters should trigger generic unsuccessful response stating the [parameter] in the response body
Sample Request URL
https://api.cirrusplatform.com/api/v1/integrations/results?CandidateExtId=eddardstark&ScheduleExtId=WINTER000
or
https://api.cirrusplatform.com/api/v1/integrations/results?AttemptExtId=attempt1
Sample successfull Response
{
"CandidateExtId": "eddardstark",
"CandidateInfo": {
"ExternalId": "eddardstark",
"FirstName": "Ext",
"LastName": "User",
"UserName": "extuser",
"Email": "eddardstark@gmail.com"
},
"Grade": "Pass",
"Score": "6",
"MaxScore": "10",
"PassScore": "5.0",
"PercentageScore": 60,
"Published": "2015-03-02T10:47:03.232Z",
"AssessmentExtId": "NORTH000",
"ScheduleExtId": "WINTER000",
"AssessmentAttemptsCount": "3", // count of attempts submitted by candidate by assessment version
"AttemptsCount": "1", // count of attempts submitted by candidate by schedule
"Status": "Satisfactory", // Satisfactory;NotSatisfactory;Voided;NotSubmitted
"PublishStatus": "FINAL", // FINAL;INTERMEDIARY;FLAGGED_FOR_REMARKING;REMARKING_IN_PROGRESS
"Presence": true,
"ResultsPerSubject": [{
"ExtId": "Subj001",
"Name": "Subject 1",
"Percentage": 71,
"Score": "5"
"LearningObjectives": [
{
"ExtId": "T1-1",
"Name": "Topic 1",
"Percentage": "50",
"Score": "2"
},
{
"ExtId": "T1-2",
"Name": "Topic 2",
"Percentage": "0",
"Score": "1"
},
{
"ExtId": "T1-3",
"Name": "Topic 3",
"Percentage": "0",
"Score": "1"
}
]
},
{
"ExtId": "Subj002",
"Name": "Subject 2",
"Percentage": 33,
"Score": "1"
"LearningObjectives": [
{
"ExtId": "T1-1",
"Name": "Topic 1",
"Percentage": "50",
"Score": "2"
},
{
"ExtId": "T1-2",
"Name": "Topic 2",
"Percentage": "0",
"Score": "1"
},
{
"ExtId": "T1-3",
"Name": "Topic 3",
"Percentage": "0",
"Score": "1"
}
]
}]
}
Sample successfull Response without ScheduleExtId
https://api.cirrusplatform.com/api/v1/integrations/results?CandidateExtId=extuser1
[{
"CandidateNumber": "extuser1",
"CandidateInfo": {
"ExternalId": "extuser1",
"FirstName": "Ext",
"LastName": "User",
"UserName": "extuser",
"Email": "extuser1@gmail.com"
},
"Grade": "E",
"Score": "1",
"MaxScore": "2",
"PassScore": "1.20",
"PercentageScore": "50",
"Published": null,
"Presence": true,
"ResultsPerSubject": [{
"ExtId": "LO1",
"Name": "LO1",
"Percentage": "50",
"Score": "1"
}
],
"AssessmentNumber": "TA1",
"BookingReference": "Test1",
"Sections": [{
"Id": "S4742-1",
"MaxScore": "20",
"CandidatePercent": "100",
"CandidateScore": "20",
"PassMark": "30",
"PassedStatus": "Passed",
"PassType": "Percent"
},
{
"Id": "S474251",
"MaxScore": "30",
"CandidatePercent": "50",
"CandidateScore": "15"
}
]
}, {
"CandidateNumber": "extuser1",
"CandidateInfo": {
"ExternalId": "extuser1",
"FirstName": "Ext",
"LastName": "User",
"UserName": "extuser",
"Email": "extuser1@gmail.com"
},
"Grade": "F",
"Score": "0",
"MaxScore": "2",
"PassScore": "1.20",
"PercentageScore": "0",
"Published": "2018-08-29T10:31:45.539Z",
"Presence": true,
"ResultsPerSubject": [{
"ExtId": "LO2",
"Name": "LO2",
"Percentage": "0",
"Score": "0"
"LearningObjectives": [
{
"ExtId": "T1-1",
"Name": "Topic 1",
"Percentage": "50",
"Score": "2"
},
{
"ExtId": "T1-2",
"Name": "Topic 2",
"Percentage": "0",
"Score": "1"
},
{
"ExtId": "T1-3",
"Name": "Topic 3",
"Percentage": "0",
"Score": "1"
}
]
}
],
"AssessmentNumber": "TA2",
"BookingReference": "Test2"
}
]
Sample successfull Response when candidate did not participate / handed in anything:
{
"CandidateNumber": "7140",
"CandidateInfo": {
"ExternalId": "7140",
"FirstName": "Ext",
"LastName": "User",
"UserName": "7140",
"Email": "7140@gmail.com"
},
"Grade": null,
"Score": "0",
"MaxScore": "0",
"PassScore": "0",
"PercentageScore": 0,
"Published": "2018-03-15T12:53:15.82Z",
"Presence": false,
"AssessmentNumber": "123",
"BookingReference": "44444"
}
Response codes
| Code | Description |
|---|---|
| 200 | Successful operation |
| 403 | Not allowed to use external API |
| 400 | Possible error codes: User/Candidate [username] was not found |
| 500 | Internal server error |