Assessments

For a full explanation of the concepts behind the Assembly assessment model, please see this support article.

The assessment endpoints are available to read school MIS and third-party assessment data (and all associated concepts). Third-party assessment data can also be written back to the Platform.

The IDs provided here are for example only, and may differ between sandbox and production environments.

List Assessments

Returns a list of assessment objects. The assessment is the grouping that knits together a range of concepts. The name of the assessment also refers to the source of the result.

Request

GET /assessments
Headers
Accept: application/vnd.assembly+json; version=1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0sZZxr3r...
Parameter Default Example Description
per_page 100 25

number of results to return

page 1 2

page number to return

URI Template: /assessments{?per_page,page}

Response 200

Headers
Content-Type: application/json; charset=utf-8
Payload
{
  "object": "list",
  "total_count": 1,
  "total_pages": 1,
  "current_page": 1,
  "prev_page": null,
  "next_page": null,
  "data": [
    {
      "object": "assessment",
      "family_id": 1,
      "family_name": "Standardised Assessment Provider 1",
      "id": 1,
      "name": "Standardised Assessment - Standardised Score"
    }
  ]
}

View an Assessment

Returns a single assessment for the given ID.

Request

GET /assessments/{assessment_id}
Headers
Accept: application/vnd.assembly+json; version=1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0sZZxr3r...
Parameter Default Example Description
assessment_id 1

the ID of the assessment as an Integer

URI Template: /assessments/{assessment_id}

Response 200

Headers
Content-Type: application/json; charset=utf-8
Payload
{
  "object": "assessment",
  "family_id": 1,
  "family_name": "Standardised Assessment Provider 1",
  "id": 1,
  "name": "Standardised Assessment - Standardised Score"
}

View Grade Set for an Assessment

Returns a grade_set (an acceptable list of values) for the assessment identified by the assessment_id. Grades should be written back to the Platform using the grade_id.

Request

GET /assessments/{assessment_id}/grade_set
Headers
Accept: application/vnd.assembly+json; version=1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0sZZxr3r...
Parameter Default Example Description
assessment_id 1

ID of the assessment as an Integer

per_page 100 25

number of results to return

page 1 2

page number to return

URI Template: /assessments/{assessment_id}/grade_set

Response 200

Headers
Content-Type: application/json; charset=utf-8
Payload
{
  "object": "assessment",
  "family_id": 1,
  "family_name": "Standardised Assessment Provider 1",
  "id": 1,
  "name": "Assembly Standardised - Standardised Score",
  "grade_set": {
      "object": "grade_set",
      "id": 1,
      "name": "Standardised Score",
      "grades": [
        {
          "object": "grade",
          "id": 145,
          "name": "70",
          "value": 70
        },
        {
          "object": "grade",
          "id": 146,
          "name": "71",
          "value": 71
        },
        {
          "object": "grade",
          "id": 147,
          "name": "72",
          "value": 72
        },
        {
          "object": "grade",
          "id": 148,
          "name": "73",
          "value": 73
        },
    ]
  }
}

View Results for an Assessment

Returns a list of results for the given assessment_id and students. For a full list of national assessment data (Key stage 1 and 2 SATs results) available on the Platform, please see this support article.

Request

GET /assessments/{assessment_id}/results?students={student_id}
Headers
Accept: application/vnd.assembly+json; version=1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0sZZxr3r...
Parameter Default Example Description
assessment_id 82

the ID of the assessment as an Integer

students 1019+1022

ID(s) of the student(s) as an Integer. Multiple IDs can be separated with a space (so a + URL encoded).

URI Template: /assessments/{assessment_id}/results?students={student_id}

Response 200

Headers
Content-Type: application/json; charset=utf-8
Payload
{
  "object": "list",
  "total_count": 2,
  "total_pages": 1,
  "current_page": 1,
  "prev_page": null,
  "next_page": null,
  "data": [
    {
      "object": "result",
      "id":                      4815,
      "student_id":              1019,
      "subject_id":              5,
      "assessment_id":           82,
      "assessment_point_rank":   4,
      "facet_id":                4,
      "grade_id":                817
    },
    {
      "object": "result",
      "id":                      4821,
      "student_id":              1022,
      "subject_id":              5,
      "assessment_id":           82,
      "assessment_point_rank":   4,
      "facet_id":                4,
      "grade_id":                819
    }
  ]
}

List Facets

Returns a list of facets. The facet is used to reflect a different type of grade and allows 2 grades of the same assessment to be compared.

Request

GET /facets
Headers
Accept: application/vnd.assembly+json; version=1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0sZZxr3r...
Parameter Default Example Description
per_page 100 25

number of results to return

page 1 2

page number to return

URI Template: /facets{?per_page,page}

Response 200

Headers
Content-Type: application/json; charset=utf-8
Payload
{
  "object": "list",
  "total_count": 4,
  "total_pages": 1,
  "current_page": 1,
  "prev_page": null,
  "next_page": null,
  "data": [
      {
        "object": "facet",
        "id": 9,
        "name": "achieved"
      },
      {
        "object": "facet",
        "id": 10,
        "name": "prediction"
      },
      {
        "object": "facet",
        "id": 11,
        "name": "target"
      },
      {
        "object": "facet",
        "id": 12,
        "name": "baseline"
      },
  ]
}

View a Facet

Returns a single facet for the given ID.

Request

GET /facet/{facet_id}
Headers
Accept: application/vnd.assembly+json; version=1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0sZZxr3r...
Parameter Default Example Description
facet_id 9

the ID of the facet as an Integer

URI Template: /facet/{facet_id}

Response 200

Headers
Content-Type: application/json; charset=utf-8
Payload
{
  "object": "facet",
  "id": 9,
  "name": "achieved"
}

List Assessment Points

Returns a list of assessment points. An assessment_point object represents a point in the school key stage, year, term or half-term that results can be attached to. When sending results back to the Platform, the assessment_point_rank should be used - this will remain constant across all environments.

Request

GET /assessment_points
Headers
Accept: application/vnd.assembly+json; version=1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0sZZxr3r...
Parameter Default Example Description
year_code 6

filter by school year

type half_term

filter by assessment point type

per_page 100 25

number of results to return

page 1 2

page number to return

URI Template: /assessment_points{?year_code,type,per_page,page}

Response 200

Headers
Content-Type: application/json; charset=utf-8
Payload
{
  "object": "list",
  "total_count": 166,
  "total_pages": 2,
  "current_page": 1,
  "prev_page": null,
  "next_page": null,
  "data": [
     {
      "object": "assessment_point",
      "rank": 3,
      "name": "Key Stage 2",
      "type": "key_stage",
      "year_code": null
    },
     {
      "object": "assessment_point",
      "rank": 15,
      "name": "Year 6",
      "type": "year",
      "year_code": "6"
    },
     {
      "object": "assessment_point",
      "rank": 48,
      "name": "Year 6 Spring",
      "type": "term",
      "year_code": "6"
    },
     {
      "object": "assessment_point",
      "rank": 122,
      "name": "Year 6 Spring 2",
      "type": "half_term",
      "year_code": "6"
    },
  ]
}

View an Assessment Point

Returns a single assessment point for the given rank.

Request

GET /assessment_points/{assessment_point_rank}
Headers
Accept: application/vnd.assembly+json; version=1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0sZZxr3r...
Parameter Default Example Description
assessment_point_rank 3

the rank of the assessment point as an Integer

URI Template: /assessment_points/{assessment_point_rank}

Response 200

Headers
Content-Type: application/json; charset=utf-8
Payload
{
    "object": "assessment_point",
    "rank": 3,
    "name": "Key Stage 2",
    "type": "key_stage",
    "year_code": null
}

List Results

Returns a list of results for the student ID(s) specified by the students parameter.

Note the If-Modified-Since header is optional (see the page on Conditional Requests for more details).

Request

GET /results
Headers
Accept: application/vnd.assembly+json; version=1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0sZZxr3r...
If-Modified-Since: Mon, 13 Mar 2017 20:00:00 GMT
Parameter Default Example Description
students 112

ID(s) of the student(s) as an Integer. Multiple IDs can be separated with a space (so a + URL encoded).

per_page 100 25

number of results to return

page 1 2

page number to return

URI Template: /results{?students,per_page,page}

Response 200

Headers
Content-Type: application/json; charset=utf-8
Last-Modified: Mon, 13 Mar 2017 20:00:00 GMT
Payload
{
  "object": "list",
  "total_count": 1,
  "total_pages": 1,
  "current_page": 1,
  "prev_page": null,
  "next_page": null,
  "data": [
      {
        "object": "result",
        "id":                    1,
        "subject_id":            2,
        "grade_set_id":          1,
        "facet_id":              1,
        "assessment_point_rank": 122,
        "assessment_id":         1,
        "student_id":            210,
        "grade_id":              147
      },
  ]
}

Write Results

Given a subject_id, facet_id, assessment_point_rank and assessment_id results can be sent to the Platform, along with a student_id and the grade_id.

Permissions: A school level access token with the assessments.write scope is needed to write results back to the Platform.

Request

POST /results
Headers
Content-Type: application/json; charset=utf-8
Payload
{
   "subject_id":            2,
   "facet_id":              1,
   "assessment_point_rank": 122,
   "assessment_id":         1,
   "results": [
     { "student_id": 210, "grade_id": 147 },
     { "student_id": 211, "grade_id": 148 }
   ]
 }

Response 200

Headers
Content-Type: application/json; charset=utf-8
Payload
{
  "message": "ok",
  "data": [
    {
      "object": "result",
      "id": 333,
      "student_id": 210,
      "grade_id": 147,
      "created_at": "2017-06-07T09:24:06.991Z",
      "updated_at": "2017-06-07T09:24:06.991Z"
    },
    {
      "object": "result",
      "id": 334,
      "student_id": 211,
      "grade_id": 148,
      "created_at": "2017-06-07T09:24:06.991Z",
      "updated_at": "2017-06-07T09:24:06.991Z"
    }
  ]
}

Update a Single Result

Once a result has been created, it can be updated on the Platform by passing the required field values in the request body. A list of the fields that were changed are returned in the response.

Request

PATCH /results/{result_id}
Headers
Content-Type: application/json; charset=utf-8
Payload
{
   "grade_id": 147
}

Response 200

Headers
Content-Type: application/json; charset=utf-8
Payload
{
  "message":        "ok",
  "updated_fields": ["grade_id"]
}

Update Multiple Results

Multiple results can be updated simultaneously by providing the relevant result_ids in the body of your request. The response will tell you whether the batch of updates has either been successful or failed.

Request

PATCH /results
Headers
Content-Type: application/json; charset=utf-8
Payload
{
   "results": [
      { "result_id": 119198, "grade_id": 102 },
      { "result_id": 119199, "grade_id": 109 },
      { "result_id": 119200, "grade_id": 102 },
      { "result_id": 119201, "grade_id": 103 },
      { "result_id": 119202, "grade_id": 109 }
    ]
}

Response 200

Headers
Content-Type: application/json; charset=utf-8
Payload
{
  "message":        "ok"
}