Students

A student object represents a single student within a school. We strongly recommend that the id field is used to uniquely identify students on the Platform, as it is possible for a student's UPN to change.

Access: This is a read-only resource managed directly by the school.

Permissions: A school level access token with the students scope is required to access student information. The students.upn scope is needed to return the upn and former_upn fields for a student. If you wish to access highly sensitive demographics data you will need the student_demographics scope - if you wish to access sensitive student care information you will also need the student_care scope. If you wish to access students' contacts you will need the contacts scope. If you wish to access students' addresses you will need the student_addresses scope. If you wish to access students' SEN needs information you will need the students.sen_needs scope. If you wish to access students' language information you will need the students.languages scope.

List Students

Returns a list of students for the school associated with the provided access_token.

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

Request

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

filter by school year

demographics false true

include demographics data

contacts false true

include contacts data

sen_needs false true

include SEN needs data

addresses false true

include student address data

care false true

include student care data (you must also supply the demographics parameter)

languages false true

include student language data

per_page 100 25

number of results to return

page 1 2

page number to return

URI Template: /students{?year_code,demographics,contacts,care,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": 1018,
    "total_pages": 41,
    "current_page": 1,
    "prev_page": null,
    "next_page": 2,
    "data": [
        {
            "object": "student",
            "id": 1,
            "year_code": "8",
            "upn": "N823432113104",
            "former_upn": "F820200109001",
            "mis_id": "8032",
            "pan": "A1234",
            "first_name": "Graham",
            "middle_name": "",
            "last_name": "Abbess",
            "dob": "1999-12-10",
            "start_date": "2015-02-31T00:00:00.000Z",
            "end_date": "2079-06-06T23:59:00.000Z",
            "enrolment_status": "Current (Single Registration)"
        },
        {
            "object": "student",
            "id": 3,
            "year_code": "13",
            "upn": "B820432109001",
            "former_upn": "V820200109002",
            "mis_id": "7545",
            "pan": "A4321",
            "first_name": "Jimmy",
            "middle_name": "",
            "last_name": "Abbey",
            "dob": null,
            "start_date": "2010-09-01T00:00:00.000Z",
            "end_date": "2079-06-06T23:59:00.000Z",
            "enrolment_status": "Current (Single Registration)"
        }
    ]
}

View a Student

Returns an individual student record for the given ID.

Note: the response shown includes student demographics, contacts, student SEN needs, student addresses and student care data but these will only be present if you have permission to access it and pass demographics=true, contacts=true, sen_needs=true, addresses=true and care=true respectively

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

Request

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

ID of the Student as an Integer

demographics false true

include demographics data

contacts false true

include contacts data

sen_needs false true

include SEN needs data

addresses false true

include student address data

care false true

include student care data (you must also supply the demographics parameter)

languages false true

include student language data

URI Template: /students/{student_id}{?demographics,contacts,addresses,care}

Response 200

Headers
Content-Type: application/json; charset=utf-8
Last-Modified: Mon, 13 Mar 2017 20:00:00 GMT
Payload
{
  "object": "student",
  "id": 1,
  "year_code": "8",
  "upn": "N823432113104",
  "former_upn": "F820200109001",
  "mis_id": "8032",
  "pan": "A1234",
  "first_name": "Graham",
  "middle_name": "",
  "last_name": "Abbess",
  "dob": null,
  "start_date": "2016-09-01T00:00:00.000Z",
  "end_date": "2079-06-06T23:59:00.000Z",
  "enrolment_status": "Current (Single Registration)",
  "demographics": {
    "ethnicity_code": "WENG",
    "ethnicity_group": "White",
    "gender": "M",
    "in_care": false,
    "is_eal": false,
    "is_fsm": true,
    "is_pp": false,
    "sen_category": "N",
    "sen_needs": [
      {
        "object": "sen_need",
        "id": 1,
        "start_date": "2014-09-01T00:00:00.000Z",
        "sen_need_code": "VI",
        "sen_need_name": "Visual Impairment",
        "sen_broad_need_type_code": "SENS",
        "sen_broad_need_type_name": "Sensory and/or physical",
        "priority": 1
      },
      {
        "object": "sen_need",
        "id": 2,
        "start_date": "2015-04-010T00:00:00.000Z",
        "sen_need_code": "ASD",
        "sen_need_name": "Autistic Spectrum Disorder",
        "sen_broad_need_type_code": "COMM",
        "sen_broad_need_type_name": "Communication and interaction",
        "priority": 2
      }
    ]
  },
  "contacts": [
    {
      "contact_id": 7,
      "relationship": {
        "object": "relationship",
        "relationship_type": "Father",
        "priority": 2,
        "parental_responsibility": true
      }
    },
    {
      "contact_id": 12,
      "relationship": {
        "object": "relationship",
        "relationship_type": "Mother",
        "priority": 1,
        "parental_responsibility": true
      }
    }
  ],
  "address": {
    "address_line_1": "1 King Street",
    "address_line_2": "Flat 1",
    "town_city": "Maidstone",
    "county": "Kent",
    "country": "United Kingdom",
    "postcode": "A1 1AA"
  },
  "languages": {
    "home_language_code": "POL",
    "home_language_name": "Polish",
    "first_language_code": "ENG",
    "first_language_name": "English",
    "proficiency_in_english_code": "E",
    "proficiency_in_english_name": "Fluent"
  }
}

Response Structure

Attribute Type Description
object string
id number Internal stable ID given to student
first_name string The first name of the student
middle_name string The middle name of the student
last_name string The last name of the student
dob string The date of birth of the student
year_code enum The year group the student currently belongs to
  Value Description
  N1 Nursery first year
  N2 Nursery second year
  R Reception
  1 Year 1
  2 Year 2
  3 Year 3
  4 Year 4
  5 Year 5
  6 Year 6
  7 Year 7
  8 Year 8
  9 Year 9
  10 Year 10
  11 Year 11
  12 Year 12
  13 Year 13
upn string Unique Pupil Number (UPN) - a DfE-mandated 13-character code that identifies each pupil. The students.upn scope is needed to access this field
former_upn string The previous UPN where a student has held another UPN whilst at a school. The students.upn scope is needed to access this field
mis_id string The student identifier used by the source MIS
pan string The student's Pupil Admission Number
start_date string Date when the student joined the school
end_date string Date when the student left the school
enrolment_status string The enrolment status of the student
demographics.gender enum The gender of the student
  Value Description
  M Male
  F Female
demographics.in_care boolean Indicates whether the student is looked after by a care authority
demographics.is_fsm boolean Indicates whether the student is eligible for a free school meal
demographics.is_eal boolean English as an Additional Language (EAL) - this field will be Yes for a student whose first language is not English
demographics.is_pp boolean Pupil Premium (PP) - schools receive extra funding for students who qualify as Pupil Premium. The includes any student who has qualified for Free School Meals (FSM) in the last 6 years, and any student in local-authority care
demographics.ethnicity_code string A detailed way of categorising the ethnicity of a student. There are roughly 100 DfE standard codes
demographics.ethnicity_group string A broader categorisation of ethnicity that is standardised across the country, with all ethnicity codes grouped in to 8 sections
demographics.sen_category enum Special Education Need (SEN) - indicates a student has learning difficulties and requires special education provision
  Value Description
  N None
  S Statement
  E Education, Health and Care Plan
  K SEN Support
  'A' School Action (no longer valid)
  'P' School Action Plus (no longer valid)
demographics.sen_needs.start_date string The date on which the SEN need started
demographics.sen_needs.sen_need_code string The code of the SEN need
demographics.sen_needs.sen_need_name string The name of the SEN need
demographics.sen_needs.sen_broad_need_type_code string The code of the broad level SEN need
demographics.sen_needs.sen_broad_need_type_name string The name of the broad level SEN need
demographics.sen_needs.priority number The priority of the SEN need
contacts.student_id number The ID of the student for which the contact is responsible
contacts.relationship.relationship_type string The relationship between the contact and the student, e.g. "Mother"
contacts.relationship.priority number The priority of the contact
contacts.relationship.parental_responsibility boolean Indicates whether the contact has parental responsibility for the student
address.address_line_1 string The first line of the address
address.address_line_2 string The second line of the address
address.town_city string The town or city
address.county string The county
address.country string The country
address.postcode string The postcode
languages.home_language_code string The code of the language spoken at home
languages.home_language_name string The name of the language spoken at home
languages.first_language_code string The code of the student's first language
languages.first_language_name string The name of the student's first language
languages.proficiency_in_english_code string The code of the student's proficiency in English
languages.proficiency_in_english_name string The name of the student's proficiency in English