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. By default, students are returned for today's date. This behaviour can be changed by supplying a ?date= parameter.

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

Permissions: A school level access token with the students.basic scope is required to access basic student information. To access more sensitive student data, additional scopes are required. For a full list of available fields and required scopes, please see our data model.

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 (cannot be supplied at the same time as the students parameter)

students 1019+1022

ID(s) of specific student(s) to return, as an Integer. Multiple IDs can be separated with a space (so a + URL encoded) (cannot be supplied at the same time as the year_code parameter)

date 2018-07-21

returns students for a specific date

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)

ever_in_care false true

include whether the student has ever been in care (you must also supply the demographics parameter)

languages false true

include student language data

medical false true

include student medical data

photo false true

include student photo data

per_page 100 25

number of results to return

page 1 2

page number to return

URI Template: /students{?year_code,students,date,demographics,contacts,sen_needs,addresses,care,ever_in_care,languages,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": "N825532113104",
            "former_upn": "F820550109001",
            "mis_id": "8032",
            "pan": "A1234",
            "first_name": "George",
            "legal_first_name": "George",
            "middle_name": "",
            "last_name": "Addington",
            "legal_last_name": "Addington",
            "former_last_name": "Smith",
            "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": "B825532109001",
            "former_upn": "V825500109002",
            "mis_id": "7545",
            "pan": "A4321",
            "first_name": "Jimmy",
            "legal_first_name": "James",
            "middle_name": "",
            "last_name": "Harris",
            "legal_last_name": "Harris",
            "former_last_name": null,
            "dob": "1998-11-12",
            "start_date": "2010-09-01T00:00:00.000Z",
            "end_date": "2079-06-06T23:59:00.000Z",
            "enrolment_status": "Current (Single Registration)"
        }
    ]
}

List Left Students

Returns a list of students who have left the school.

Note: This will include any students who have left the school during the current academic year. If the school has been connected to Assembly for more than one academic year, all left students will be returned. The If-Modified-Since header is optional (see the page on Conditional Requests for more details).

Request

GET /students/left
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
per_page 100 25

number of results to return

page 1 2

page number to return

URI Template: /students/left{?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": "N825532113104",
            "former_upn": "F820550109001",
            "mis_id": "8032",
            "pan": "A1234",
            "first_name": "George",
            "legal_first_name": "George",
            "middle_name": "",
            "last_name": "Addington",
            "legal_last_name": "Addington",
            "former_last_name": "Smith",
            "dob": "1999-12-10",
            "start_date": "2015-02-31T00:00:00.000Z",
            "end_date": "2017-10-06T23:59:00.000Z",
            "enrolment_status": null
        },
        {
            "object": "student",
            "id": 3,
            "year_code": "13",
            "upn": "B825532109001",
            "former_upn": "V825500109002",
            "mis_id": "7545",
            "pan": "A4321",
            "first_name": "Jimmy",
            "legal_first_name": "James",
            "middle_name": "",
            "last_name": "Harris",
            "legal_last_name": "Harris",
            "former_last_name": null,
            "dob": "1998-11-12",
            "start_date": "2010-09-01T00:00:00.000Z",
            "end_date": "2018-01-06T23:59:00.000Z",
            "enrolment_status": null
        }
    ]
}

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, student medical, dietary needs, photo 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, medical=true, photo=true, care=true and ever_in_care=true respectively

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

Photo Notes

When requesting photo information the response includes a photo.url property, this URL should be treated as confidential and used to download the students photo to your storage system of choice. The URL is not designed for hotlinking directly in the browser for end users. URLs are signed and only valid for 1 hour after which time you will receive a 400 error.

Once downloaded to avoid repeatedly syncing unchanged photos you should code your application to compare the photo.hash property to detect changes in student photos since your last sync, it is guaranteed that changes in a photo will change the hash, however the hash is only intended to be used to detect photo changes and is not guaranteed to match a checksum of the files contents.

Photos are currently provided on an "as is" basis straight from the source MIS, this means the format, quality, metadata and dimensions are not guaranteed. We reserve the right to normalise this data in the future but your application should be resistant to differing photo formats.

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

date 2018-07-21

returns the student record for a specific date

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)

ever_in_care false true

include whether the student has ever been in care (you must also supply the demographics parameter)

languages false true

include student language data

medical false true

include student medical data

photo false true

include student photo data

URI Template: /students/{student_id}{?demographics,date,contacts,sen_needs,addresses,care,ever_in_care,languages}

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": "N825532113104",
  "former_upn": "F820550109001",
  "mis_id": "8032",
  "pan": "A1234",
  "first_name": "George",
  "legal_first_name": "George",
  "middle_name": "",
  "last_name": "Addington",
  "legal_last_name": "Addington",
  "former_last_name": "Smith",
  "dob": "1999-12-10",
  "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,
    "ever_in_care": false,
    "is_eal": false,
    "is_fsm": true,
    "fsm_review_date": "2016-09-01",
    "is_pp": false,
    "service_child": false,
    "country_of_birth": "United Kingdom",
    "nationalities": [
      "United Kingdom"
    ],
    "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
      }
    ]
  },
  "siblings": {
      "student_id": 900
  },
  "medical": {
    "dietary_needs": ["HLAL", "GLUT"]
  },
  "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"
  },
  "photo": {
    "url": "https://assembly-production-platform-files.s3.aws.amazon.com/123/2346ad27d7568ba9896f1b7da6b5991251debdf2.jpg?...",
    "hash": "2346ad27d7568ba9896f1b7da6b5991251debdf2"
  }
}

Response Structure

Attribute Type Description
object string "student"
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 enum The enrolment status of the student
  Value Description
  Current (single registration at this school)
  Current Main (dual registration)
  Guest
  Current Subsidiary (dual registration)
  Previous
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.ever_in_care boolean Indicates whether the student has ever been looked after by a care authority
demographics.is_fsm boolean Indicates whether the student is eligible for a free school meal
demographics.fsm_review_date string Review date for pupil's free school meal eligibility
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.country_of_birth string The country of birth of the student
demographics.nationalities string The nationalities of the student
demographics.ethnicity_code string A detailed way of categorising the ethnicity of a student. There are roughly 100 DfE standard codes
demographics.ethnicity_group enum A broader categorisation of ethnicity that is standardised across the country, with all ethnicity codes grouped in to 8 sections
  Value Description
  White
  Mixed / Dual Background
  Asian or Asian British
  Black or Black British
  Chinese
  Any Other Ethnic group
  Infortmation Not Yet Obtained
  Refused
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
medical.object string "student_medical"
medical.nhs_number string The student's NHS number
medical.has_emergency_consent boolean Whether the student (or their guardian) has given emergency consent
medical.is_pregnant boolean The student's pregnancy status
medical.conditions[].object string "student_medical_condition"
medical.conditions[].id string Internal stable ID given to the medical condition
medical.conditions[].information_recieved_on string Datetime that the medical condition was associated with the student
medical.conditions[].code string The short name of the medical condition
medical.conditions[].name string The long name of the medical condition
medical.conditions[].notes[].object string "student_medical_note"
medical.conditions[].notes[].id string Internal stable ID given to the medical condition
medical.conditions[].notes[].status string Status of the note as specified in the MIS (may be null, "PUBLIC", "CONFIDENTIAL", etc.). Clients should restrict access to notes based on thie field
medical.conditions[].notes[].summary string A short piece of text summarising the note
medical.conditions[].notes[].detail string More detailed information, may be null or identical to the summary
medical.conditions[].notes[].created_by_id string The internal stable ID of the (possibly left) staff member who created this note
medical.conditions[].notes[].last_modified_by_id string The internal stable ID of the (possibly left) staff member who last modified this note
medical.conditions[].notes[].last_modified_date string The datetime this note was last modified
medical.dietary_needs[] string A list of dietary need codes associated with the student, the name of each can be obtained from the school endpoint
medical.notes[].object string "student_medical_note"
medical.notes[].id string Internal stable ID given to the medical condition
medical.notes[].status string Status of the note as specified in the MIS (may be null, "PUBLIC", "CONFIDENTIAL", etc.). Clients should restrict access to notes based on thie field
medical.notes[].summary string A short piece of text summarising the note
medical.notes[].detail string More detailed information, may be null or identical to the summary
medical.notes[].created_by_id string The internal stable ID of the (possibly left) staff member who created this note
medical.notes[].last_modified_by_id string The internal stable ID of the (possibly left) staff member who last modified this note
medical.notes[].last_modified_date string The datetime this note was last modified
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
photo.url string A signed URL you can use to download the students photo. Valid for 1 hour
photo.hash string A SHA1 digest hash of the photos contents, you should use this to detect changed photos