Scoring Service REST API — Response Fields Reference

This article describes the fields returned in all Scoring Service API responses. These fields are consistent across both Standard Scoring and Bayes Scoring endpoints.

Response Fields

A successful response (HTTP 200) from any scoring endpoint returns the following fields:

Field Type Description
ability number The research measure used to describe the student's ability. Use this value for analysis, research purposes, or when passing a score into a subsequent API call such as a Bayes priorAbility field.
abilityDisplay string A display-ready version of the ability score with all business rules and formatting rules applied, including rounding to the nearest 5, top and bottom caps applied, conversion of negatives to BR or EM, and framework label appended (e.g. "320L" or "BR200L"). Use this value when presenting scores in user interfaces or reports.
uncertainty number The confidence range around the ability estimate. A smaller value indicates a more precise score.
framework string The scoring framework used for this response (e.g. "lexile" or "quantile").
apiVersion string The build version of the API that processed the request.

Which ability field should I use?

Both fields represent the same underlying score, but prepared differently for different purposes.

If you are... Use...
Displaying a score to a teacher, parent, or student abilityDisplay
Storing a score for research or institutional reporting ability
Passing a score back into the API as a prior (Bayes calls) ability
Logging or auditing raw API output ability

Example Response

The following example shows a response from the /api/score/form/id/standard endpoint. All other scoring endpoints return the same fields in this structure.

{
                "ability": 320,
                "abilityDisplay": "320L",
                "uncertainty": 288,
                "framework": "lexile",
                "apiVersion": "ecf08905-main"
                }

For endpoints that return BR (Below Reader) notation, the abilityDisplay value will reflect the converted format:

{
                "ability": -200,
                "abilityDisplay": "BR200L",
                "uncertainty": 288,
                "framework": "lexile",
                "apiVersion": "ecf08905-main"
                }

Display Rules Applied to abilityDisplay

The following rules are applied automatically by the API before returning the abilityDisplay value. Partners no longer need to apply these rules in their own systems.

Rule Description Example
Rounding The score is rounded to the nearest 5. 322 → 320
Range caps Scores above or below the valid range for the framework are capped at the ceiling or floor. A score above the maximum is returned as the maximum display value.
Negative conversion (Lexile) Negative Lexile scores are expressed as BR (Below Reader) followed by the absolute value. -200 → BR200L
Negative conversion (Quantile) Negative Quantile scores are expressed as EM (Emerging Math) followed by the absolute value. -200 → EM200Q
Framework label The appropriate label is appended: L for Lexile, Q for Quantile. 320 → 320L or 320Q

Related Resources