Data Model

This is a one page representation of the Assembly Platform Data Model. You can click on the name of a resource to access our developer documentation for it. 

Resource -  Academic Years

An academic_year object represents a school year within a particular school.

Field Data Type Scope Description Example
id number school Internal stable ID given to academic year on Platform 4
name string school Name of academic year "2015/2016"
start_date string school Date on which academic year starts "2015-09-01"
end_date string school Date on which academic year ends "2016-07-21"
terms resource calendar Provides details of the individual terms that make up the academic year

Resource - Terms Dates

If the access token also has the  calendar scope, then term dates will also be included with academic_years where available (currently for SIMS schools only). 

Field Data Type Scope Description Example
id number calendar Internal stable ID given to term_dates on Platform 2032
name string calendar Name of the term "Summer Term"
start_date datetime calendar Date on which term begins "2016-04-11T00:00:00.000Z"
end_date datetime calendar Date on which term ends "2016-07-22T23:59:00.000Z

Resource - School Details

Returns details for the school associated with the provided access_token.

Field Data Type Scope Description Example
id number school Internal stable ID given to all schools on Platform 1231
name string school Name of the school "Test School"
urn string school Unique Reference Number (URN) of the school "123456"
la_code number school The code of the local authority that the school belongs to 123
la_name string school The name of the local authority that the school belongs to "City of London"
establishment_number number school The school's establishment or "DfE number" 4321
establishment_type string school The type of establishment "Community School"
phase string school The phase of the school (i.e. "Secondary, "Primary" or "All through") "Secondary"
street string school The street that the school is on "High Street"
town string school The town that the school is in "London"
postcode string school The postcode of the school "SE1 1AA"
head_teacher string school The school's head teacher name "Mrs A Smith"

Resource - OAuth

The OAuth endpoints are available to gain authorisation to access a school's data.

Field Data Type Description Example
access_token string Access token grants authorisation to school data (currently validfor a period of 30 days) "U10.cre0RDDZ_xfGz0"
refresh_token string Refresh tokens should be used to aquire a new access token upon expiry of access tokens "34g9hp0obobgo9g23"
token_type string Provides the client with the information to utilise the access token to make a resource request
"bearer"
level string Details whether the token gives access to application level resources or school data.  "app"
expires_in string The amount of time (in seconds) that the access token is valid for "108000"
school_id number Internal Platform ID for school that the token applies to  143

Resource - Staff Members

A staff_member object represents a single staff member within a school.

Field Data Type Scope Description Example
id number staff_members Internal stable ID given to each staff member in the Platform 24
first_name string staff_members The first name of the staff member "Trevor"
middle_name string staff_members The middle name of the staff member "Lance"
last_name string staff_members The last name of the staff member "Taylor"
title string staff_members The title of the staff member "Mr"
email string staff_members The email address of the staff member. "trevor.taylor @assembly.education"
is_teaching_staff boolean staff_members Indicates whether the staff member is a teacher true

Resource -  Students

A student object represents a single student within a school.

Field Data Type Scope Description Example
id number students Internal stable ID given to staff members in the Platform 48
first_name string students The first name of the student "Duncan"
middle_name string students The middle name of the student "Peter"
last_name string students The last name of the student "Smith"
dob string students The date of birth of the student "17/05/2004"
year_code enum students The year group the student currently belongs to "7"
upn string students.upn Unique Pupil Number (UPN) - a DfE-mandated 13-character code that identifies each pupil "M3334321444109"
mis_id string students The ID of a student from the MIS "A1234"
pan string students A student's "pupil admission number". This field is exposed in the front end of the MIS, and may be the same as mis_id "8032"
start_date datetime students Date when the student joined the school "2016-03-31T00:00:00.000Z"
end_date datetime students Date when the student left the school (this will default to 2079-06-06T23:59:00.000Z) "2017-07-21T00:00:00.000Z"
enrolment_status string students The enrolment status of the student "Current (Single Registration)"
demographics resource student_ demographics Demographics information about the student (this will only be returned if &demographics=true is included in your request)
contacts list contacts List of contact IDs for the student (this will only be returned if &contacts=true is included in your request)
address resource student_addresses The home address and postcode of a student (this will only be returned if &addresses=true is included in your request) 

Resource - Student Demographics

Demographic information about the student.

Field Data Type Scope Description Example
ethnicity_code string student_ demographics A detailed way of categorising the ethnicity of a student. There are roughly 100 DfE standard codes "MOTH"
ethnicity_group string student_ demographics A broader categorisation of ethnicity that is standardised across the country, with all ethnicity codes grouped in to 8 sections "Mixed/ Dual Background"
gender enum student_ demographics The gender of the student "M"
in_care boolean student_care Looked after status - indicates whether the student is 'looked after' by the local authority (this field will only be returned if &demographics=true and &care=true is included in your request) false
is_eal boolean student_ demographics English as an Additional Language (EAL) - this field will be true for a student whose first language is not English true
is_fsm boolean student_ demographics Free School Meals (FSM) - indicates if the student is eligible for free school meals true
is_pp boolean student_ demographics 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 true
sen_category enum student_ demographics Special Education Need (SEN) - indicates a student has learning difficulties and requires special education provision. Can be null for those not eligible "K"
sen_needs resource students.sen_needs Information about a student's  SEN Needs. This will only be returned if &sen_needs=true is included in your request

Resource - Student SEN Needs

A student's home address and postcode.

Information about a student's SEN Needs. 

Field Data Type Scope Description Example
id number students.sen_needs The id of the sen need 12
start_date datetime students.sen_needs The start date for the need "2014-09-01T00:00:00.000Z"
sen_need_code string students.sen_needs The code of the sen need "VI"
sen_need_name string students.sen_needs The name of the sen need "Visual Impairment"
sen_broad_need_type_code string students.sen_needs The code for the broad need "SENS"
sen_broad_need_type_name string students.sen_needs The name of the broad need "Sensory and/or physical"
priority number students.sen_needs The priority of the sen need 1

Resource - Student Address

A student's home address and postcode.

Field Data Type Scope Description Example
address_line_1 string student_addresses The first line of the address "1 King Street"
address_line_2 string student_addresses The second line of the address "Flat 1"
town_city string student_addresses The town or city "Maidstone"
county string student_addresses The county "Kent"
country string student_addresses The country "United Kingdom"
postcode string student_addresses The postcode "A1 1AA"

Resource - Subjects

A subject object represents an Assembly Platform subject. These subjects are mapped to one or multiple subjects within a school's MIS and are used to normalise school to school variance in subject naming to a known and fixed set within the Assembly Platform.

Field Data Type Scope Description Example
id number school Internal stable ID given to all subjects in the Platform 22
name string school Full name of subject  "Mathematics"
code string school Shortened code of subject "MAT"


Resource - Teaching Groups

A teaching_group object represents the grouping in which students are taught a subject.

Field Data Type Scope Description Example
id number teaching_groups Internal stable ID given to all teaching groups in the Platform 12
name string teaching_groups Name of teaching group "7/Ma1"
start_date datetime teaching_groups The start date of the teaching group "2015-09-01T00:00:00.000Z"
end_date datetime teaching_groups The end date of the teaching group "2016-08-31T23:59:00.000Z"
supervisor_ids number teaching_groups + staff_members The IDs of supervisors associated with the teaching group 1, 15
student_ids number teaching_groups + students The IDs of students associated with the teaching group 14, 15, 107, 222
subject string teaching_groups The ID, code and name of the subject of the teaching group 22, "Mathematics", "MAT"


Resource -  Registration Groups

A registration_group object represents the grouping in which students take AM/PM roll call (morning and afternoon registers).

Field Data Type Scope Description Example
id number school Internal stable ID given to all registration groups on the Platform 124
name string school Name of the registration group "6-Oxford"
student_ids number students The IDs of students associated with the registration group 141, 151, 307
supervisor_ids numbers staff_members The IDs of staff members associated with the registration group 76, 234

Resource - Year Groups

A year_group object represents the pastoral year group that a student belongs to.

Field Data Type Scope Description Example
code string school The code of the year that the student belongs to 7
name string school The name of internal year group that the student belongs to "Year 7"
student_ids number students The IDs of students associated with the year group 12, 233, 3323
supervisor_ids number staff_members The IDs of supervisors associated with the year group 1

Resource - Contacts

A contact object represents a parent or guardian. Students are related to contacts through a student/contact relationship.

Field Data Type Scope Description Example
id number contacts Internal stable ID given to all contacts on the Platform 87
first_name string contacts The first name of the contact "Tony"
middle_name string contacts The middle name of the contact "Peter"
last_name string contacts The last name of the contact "Smith"
gender string contacts The gender of the contact "M"
title string contacts The title of the contact "Mr"
salutation string contacts The salutation for the contact "Mr Smith"
emails list contacts A list of emails for the contact - see the Email Addresses resource
telephone_numbers list contacts A list of telephone numbers for the contact - see the Telephone Numbers resource
students list contacts  A list of student IDs that the contact is responsible for

Resource - Student Contact Relationship

A student contact relationship object represents the relationship between a student and a contact.

Field Data Type Scope Description Example
relationship_type string contacts  The relationship between the contact and the student "Mother"
priority number contacts  The priority of this contact for the student 1
parental_responsibility boolean contacts  Indicates whether the contact has parental responsibility for the student true

Resource - Telephone Numbers

The telephone_number object is available for contacts and staff members, and contains the following fields. 

Field Data Type Description Example
id number Internal stable ID given to all telephone numbers on the Platform 23
telephone_number string The telephone number "0123 456789"
type enum The location associated with the telephone number - can be Home, Work, Mobile or Other "Home"
is_primary boolean Indicates whether this is the primary telephone number true

Resource - Email Addresses

The email object is available for contacts and staff members, and contains the following fields. 

Field Data Type Description Example
id number Internal stable ID given to all email addresses on the Platform 12
email string The email address "paul.smith@example.com"
type enum The location associated with the email address - can be Home, Work, Other or null "Home"
is_primary boolean Indicates whether this is the primary email address true

Resource - Calendar Events

The calendar_events object provides details of school events. This resource is currently only available for SIMS. 

Field Data Type Scope Description Example
id number calendar Internal stable ID given to all calendar events on the Platform 1
name string calendar This details the user-defined "category" that the event is assigned to on SIMS.  "Meeting"
description string calendar The name of the instance of the event, usually more detailed and specific than the "name" "After School SLT Meeting"
start_date datetime calendar Date and time of when the event starts "2015-09-03T16:00:00.000Z"
end_date datetime calendar Date and time of when the event ends "2015-09-03T17:30:00.000Z"
is_active boolean calendar Whether the event is active or not true
is_recurrent boolean calendar Whether the event recurs and (soon) details of recurrences true
mis_type string calendar Details the type of event - whether it is a regular calendar event, a staff meeting or inset day

Resource - Assessments

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 (for example, a Key Stage national assessment, or a standardised assessment provider). 

Field Data Type Scope Description Example
id number assessments.national Internal stable ID given to all assessments on the Platform 1
name string assessments.national The name of the assessment "Standardised Assessment - Standardised Score"

Resource - Assessment Family

The Assessment Family groups together multiple assessments. In cases where Assembly gathers assessment data using multiple gradesets for the same test (e.g. a raw score, a standardised score and a percentile), the Assessment Family is the grouping that ties those multiple asessments together. 

Field Data Type Scope Description Example
family_id number assessments.national Internal stable ID given to all assessment families on the Platform 2
family_name string assessments.national The name of the assessment family "Standardised Assessment Provider 1"

Resource - Gradesets

Gradesets offer an acceptable range of values for any given assessment.

Field Data Type Scope Description Example
id number assessments.national Internal stable ID given to all gradesets on the Platform 2
name string assessments.national The name of the assessment family "Standardised Score"
grades list assessments.national See the grades resource for more information


Resource - Grades

The grades are the acceptable values and ids that make up a gradeset. 

Field Data Type Scope Description Example
id number assessments.national Internal stable ID given to all grades. Results should be written back to the Platform using the ID (as opposed to the "name") 2032
name string assessments.national The name of the grade as a string "110", "EXS", "8"
value numeric assessments.national
The value of the grade as a number 8.5, 100

Resource - Facets

All results belong to one of four facets, with each facet reflecting a different type of grade. Facets can be used to compare 2 grades of the same assessment. 

Field Data Type Scope Description Example
id number assessments.national Internal stable ID given to all facets on the Platform 6
name string assessments.national The name of the facet "achieved", "target", "prediction", "baseline"

Resource - Assessment Points

An assessment point represents a point in the school key stage, year, term or half-term that results can be attached to.

Field Data Type Scope Description Example
rank number assessments.national A stable number consistently assigned to assessment points across all environments. This field should be used to send results back to the Platform 122
name string assessments.national 
The name of the assessment point "Key Stage 2"
type string assessments.national The time period that the assessment point relates to. This can be an entire key stage, an entire year, or a single term or half-term "key_stage", "year", "term"
year_code string assessments.national This field ties an assessment point to a year group.  "Year 6 Spring 2"

Resource - Results

A result combines the other assessment principles and attaches them to a student.

Field Data Type Scope Description Example
id number assessments.national Internal stable ID given to all results on the Platform 101
student_id number assessments.national The ID of the student that the result is attached to 923
subject_id number assessments.national The ID of the subject that the result is attached to 2
assessment_id number assessments.national
The ID of the assessment that the result is attached to 1
assessment_point_rank number assessments.national The rank of the assessment point 48
aspect_id number assessments.national The ID of the aspect that the result is attached to 6
grade_id number assessments.national
The ID of the grade 157
created_at datetime assessments.national The date and time that the result was first created "2017-06-07T09:24:06.991Z"
updated_at datetime assessments.national The date and time that the result was last updated "2017-06-07T09:24:06.991Z"

Resource - Attendances

The attendances resource details AM and PM roll call attendance marks for students. 

Field Data Type Scope Description Example
id number attendances  Internal stable ID given to all attendances on the Platform 2117
student_id number attendances  The ID of the student that the attendance is attached to 1085
registration_group_id number attendances The ID of the subject that the attendance is attached to 4682
session_date datetime attendances The date of the attendance "2017-05-19T13:00:00.000Z"
session_name string attendances  Denotes whether the attendance is an AM session or PM session (morning or afternoon) "PM"
attendance_mark string attendances The attendance mark "/"
minutes_late number attendances If the attendance mark is "L" for "Late", how many minutes late the student was 15
comments string attendances Any additional comments "Missed bus"

Please note: the value of some fields may be null where the MIS doesn't provide this data. 


Creative Commons License This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.


Still need help? Contact Us Contact Us