Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Get Candidate Results

get

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.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
workspace_idstringRequired

Workspace identifier returned by List Workspaces.

Example: 7898
assessment_idstringRequired

Assessment identifier returned by List Assessments. A candidate may have results in multiple assessments.

Example: 13971
candidate_idstringRequired

Candidate identifier, taken from speechace_user_id in Get Assessment Results.

Example: 3097239
Query parameters
result_levelstring · enumOptional

Choose assessment to include activity results and the overall assessment summary, or activity for individual activity results without the summary.

Default: assessmentPossible values:
date_fromstring · date-timeOptional

Optional ISO 8601 timestamp including a timezone.

date_tostring · date-timeOptional

Optional ISO 8601 timestamp including a timezone.

include_incompletebooleanOptional

Optional flag to include incomplete results (true).

Responses
200

Successful response containing the candidate’s activity results; assessment-level results also include an overall assessment summary.

application/json
result_levelstring · enumRequired

Level of result detail requested.

Possible values:
get/api/v1/workspaces/{workspace_id}/assessments/{assessment_id}/candidates/{candidate_id}/results
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