Score

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

/api/v10/scoresheets/ID/scores/ID

GET Get a score

Retrieve information about a specific score on a scoresheet.

GET /api/v10/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/v10/scoresheets/123/scores/321"

Response headers

Response codes

Example response

{
  "scored": "2025-12-17T08:45:44+00:00",
  "scoresheet": "/api/v10/scoresheets/4",
  "application": "/api/v10/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 the provided value and update the score metadata.

The difference between the PUT and PATCH methods is the following:

• PUT cleanly overwrites all score metadata
• PATCH only updates the metadata provided in the API request

The points value must be specified in both cases. The metadata fields — such as comments and date — are all optional.

This API request runs all validation checks and does not accept illegal point values that fall out of the accepted range (as defined in the scoresheet settings). If mapped values are set (for example, if 5 = Excellent), the numeric value must be sent.

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

Raw request body

The request body must contain the score points and metadata formatted as a valid JSON object.

The points value must be a string. You can set 0 points (which is perfectly valid) as 0 or 0.0 or 0.00. However, you cannot clear the score 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 DreamApply portal.

• comments: The allowed length is 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: The allowed length is up to 64 characters
• subject: The allowed length is up to 64 characters

This API request allows omitting a metadata field, even if it is marked as required and enforced for Administrators or applicants.

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/v10/scoresheets/123/scores/321"

Response headers

Response codes

PATCH Set a score

Set the points of a scoresheet score to the provided value and update the provided score metadata. Other metadata remain unchanged.

The difference between the PUT and PATCH methods is the following:

• PUT cleanly overwrites all score metadata
• PATCH only updates the metadata provided in the API request

The points value must be specified in both cases. The metadata fields — such as comments and date — are all optional.

This API request runs all validation checks and does not accept illegal point values that fall out of the accepted range (as defined in the scoresheet settings). If mapped values are set (for example, if 5 = Excellent), the numeric value must be sent.

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

Raw request body

The request body must contain the score points and metadata formatted as a valid JSON object.

The points value must be a string. You can set 0 points (which is perfectly valid) as 0 or 0.0 or 0.00. However, you cannot clear the score 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 DreamApply portal.

• comments: The allowed length is 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: The allowed length is up to 64 characters
• subject: The allowed length is up to 64 characters

This API request allows omitting a metadata field, even if it has been marked as required and is enforced as such for Administrators or applicants.

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/v10/scoresheets/123/scores/321"

Response headers

Response codes