Get Candidate Results
Retrieve assessment-level and activity-level results for a specific candidate using the Speechace Speaking Test API.
The Get Candidate Results endpoint retrieves results for a specific candidate within an assessment.
Depending on the level of detail you need, you can retrieve an assessment-level result or individual activity-level results. This allows you to review a candidate's overall assessment performance or explore their results for specific activities.
The endpoint uses the candidate's identifier together with the workspace and assessment IDs to locate the relevant results.
Understanding candidate result levels
The API supports two levels of candidate results:
Assessment level: Retrieves results for the candidate within the selected assessment, including assessment-level information and associated activity records.
Activity level: Retrieves individual activity results for the candidate within the selected assessment.
You can choose which level to retrieve using the result_level query parameter. The following section shows how to request each level and understand its response.
Retrieve results for a specific candidate within an assessment. Use result_level=assessment to include individual activity records and an overall assessment summary, or result_level=activity to retrieve the individual activity records without the assessment summary.
Workspace identifier returned by List Workspaces.
7898Assessment identifier returned by List Assessments. A candidate may have results in multiple assessments.
13971Candidate identifier, taken from speechace_user_id in Get Assessment Results.
3097239Choose assessment to include activity results and the overall assessment summary, or activity for individual activity results without the summary.
assessmentPossible values: Optional ISO 8601 timestamp including a timezone.
Optional ISO 8601 timestamp including a timezone.
Optional flag to include incomplete results (true).
Successful response containing the candidate’s activity results; assessment-level results also include an overall assessment summary.
Level of result detail requested.
The request could not be authenticated because the API key is missing or invalid.
The requested resource could not be found or accessed. Check the resource identifiers and API key permissions.
curl --request GET \
--url 'https://speak.speechace.co/api/v1/workspaces/{workspace_id}/assessments/{assessment_id}/candidates/{candidate_id}/results?result_level=assessment' \
--header 'Authorization: Bearer YOUR_RESULTS_API_KEY' \
--header 'Accept: application/json'{
"assessment": {
"id": "13971",
"title": "HR Interview",
"default_rubric": "Speechace"
},
"candidate": {
"id": "3097239",
"speechace_user_id": 3097239,
"username": "candidate1",
"full_name": "Example Candidate",
"email": "candidate1@example.com"
},
"result_level": "assessment",
"activity_records": [
{
"result_id": "5366181",
"attempt_state": "completed",
"quiz_score": 0.5,
"quiz_cefr": "A0",
"activity_id": "20471",
"activity_title": "HR Interview"
},
{
"result_id": "5356153",
"attempt_state": "completed",
"quiz_score": 0,
"quiz_cefr": "A0",
"activity_id": "20474",
"activity_title": "PM Interview"
}
],
"assessment_summary": {
"overall_score": 0.2,
"rubric": "Speechace"
}
}Why is an assessment ID needed?
A candidate can complete more than one assessment within the same workspace.
The assessment_id tells the API which assessment you want results for, while the candidate_id identifies the candidate.
For example, a candidate who has completed both an HR Interview and a Sales Manager Interview will have results associated with each assessment.
To retrieve their results, you can make a separate request for each assessment using its corresponding assessment_id and the same candidate_id.
Finding the candidate ID
Before retrieving results for a specific candidate, you'll need their candidate_id.
You can use Get Assessment Results to retrieve candidate records for an assessment. Each record includes a speechace_user_id, along with identifying information such as the candidate's name, username, and email address.
Use the speechace_user_id value as the candidate_id in your Get Candidate Results request.
For example, a candidate record might contain:
In the above example, use 3097239 as the candidate_id in your Get Candidate Results request.
A candidate may have multiple attempts, each with its own result_id, while the speechace_user_id identifies the candidate across those attempts.
Use the candidate's name, username, or email to locate the correct record before making your request.
The following section describes Get Detailed Activity Result and how to retrieve more detailed information using a specific result identifier.
Last updated