Score

Represents a single score on the scoresheet (points & metadata).

/api/v9/scoresheets/ID/scores/ID

GET Get a score

Return information about a scoresheet score.

GET /api/v9/scoresheets/123/scores/321
Host: apply.example.edu
Authorization: DREAM apikey="..."

Example request

curl \
  -X GET \
  -H "Authorization: DREAM apikey=\"YOUR-API-KEY\"" \
  "https://apply.example.edu/api/v9/scoresheets/123/scores/321"

Response headers

Response codes

Example response

{
  "scored": "2025-12-17T08:45:44+00:00",
  "scoresheet": "/api/v9/scoresheets/4",
  "application": "/api/v9/applications/123",
  "offer": null,
  "points": "87.00",
  "comments": "Copied from transcript",
  "date": "2025-02-01",
  "reference": "BG450-009",
  "subject": null,
  "language": "en",
}

PUT Set a score

Set the points of a scoresheet score to a particular value, along with any additional metadata that is specified.

The difference between the PUT and PATCH methods comes down to the fact that PUT will cleanly overwrite all the metadata, while PATCH only touches the metadata that is specified in the request. The “points” value must be specified in both cases. Metadata fields are all optional.

This will still run all validation checks and will not permit illegal point values to be entered that fall out of the accepted range as set in the scoresheet settings. If setting mapped values (for example if 5 = Excellent), the numeric value must be sent.

PUT /api/v9/scoresheets/123/scores/321
Host: apply.example.edu
Authorization: DREAM apikey="..."

Request headers

Raw request body

Write the points and metadata into the request body as a JSON object.

Note that the points value must be a string. You can set 0 points (which is perfectly valid) as 0 or 0.0 or 0.00, as you please. But you cannot clear the points using this request.

{
  "points": "3.14",
  "comments": "Some comments",
  "date": "2025-01-30",
  "language": "it",
  "reference": "Diploma nr. 789",
  "subject": "Mathematics"
}

The metadata fields are validated and sanitised, similarly to the admin interface.

• comments: up to 2048 characters
• date: a valid YYYY-MM-DD date (must not be in the future)
• language: a valid ISO 639-1 Alpha2 abbreviation
• reference: up to 64 characters
• subject: up to 64 characters

However, the API will allow omitting a metadata field, even if it has been marked as required and is enforced as such for regular administrators or applicants.

Alternatively, it is also possible to pass the parameters as URL query parameters, such as ?points=10&language=es.

Example request

curl \
  -X PUT \
  -H "Authorization: DREAM apikey=\"YOUR-API-KEY\"" \
  -H "Content-Type: application/json" \
  -d '{
  "points": "80.00",
  "comments": "Some comments",
  "date": "2025-01-30",
  "language": "it",
  "reference": "Diploma nr. 789",
  "subject": "Mathematics"
}' \
  "https://apply.example.edu/api/v9/scoresheets/123/scores/321"

Response headers

Response codes

PATCH Set a score

Set the points of a scoresheet score to a particular value. Any specified metadata will also be updated. Other metadata will remain unchanged.

The difference between the PUT and PATCH methods comes down to the fact that PUT will cleanly overwrite all the metadata, while PATCH only touches the metadata that is specified in the request. The “points” value must be specified in both cases. Metadata fields are all optional.

This will still run all validation checks and will not permit illegal point values to be entered that fall out of the accepted range as set in the scoresheet settings. If setting mapped values (for example if 5 = Excellent), the numeric value must be sent.

PATCH /api/v9/scoresheets/123/scores/321
Host: apply.example.edu
Authorization: DREAM apikey="..."

Raw request body

Write the points and metadata into the request body as a JSON object.

Note that the points value must be a string. You can set 0 points (which is perfectly valid) as “0” or “0.0” or “0.00”, as you please. But you cannot clear the points using this request.

{
  "points": "3.14",
  "comments": "Some comments",
  "date": "2025-01-30",
  "language": "it",
  "reference": "Diploma nr. 789",
  "subject": "Mathematics"
}

The metadata fields are validated and sanitised, similarly to the admin interface.

• comments: up to 2048 characters
• date: a valid YYYY-MM-DD date (must not be in the future)
• language: a valid ISO 639-1 Alpha2 abbreviation
• reference: up to 64 characters
• subject: up to 64 characters

However, the API will allow omitting a metadata field, even if it has been marked as required and is enforced as such for regular administrators or applicants.

Alternatively, it is also possible to pass the parameters as URL query parameters, such as ?points=10&language=es.

Example request

curl \
  -X PATCH \
  -H "Authorization: DREAM apikey=\"YOUR-API-KEY\"" \
  -H "Content-Type: application/json" \
  -d '{
  "points": "80.00",
  "comments": "Some comments",
  "date": "2025-01-30",
  "language": "it",
  "reference": "Diploma nr. 789",
  "subject": "Mathematics"
}' \
  "https://apply.example.edu/api/v9/scoresheets/123/scores/321"

Response headers

Response codes