Data Model

Please don’t hesitate to get in touch if you have questions. You can email us at help@assembly.education or give us a call at 020 3897 2888

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 valid for a period of 1 day)	"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.` `basic`	Internal stable ID given to each staff member in the Platform	24
mis_id	string	`staff_members.` `mis_id`	The ID of the staff member from the MIS	"214"
staff_code	string	`staff_members.` `basic`	The staff code from the MIS	"TLA"
first_name	string	`staff_members.` `basic`	The first name of the staff member	"Trevor"
legal_first_name	string	`staff_members.` `legal_names`	The legal first name of the staff member	"Trevor"
middle_name	string	`staff_members.` `middle_names`	The middle name of the staff member	"Lance"
last_name	string	`staff_members.` `basic`	The last name of the staff member	"Taylor"
legal_last_name	string	`staff_members.` `legal_names`	The legal last name of the staff member	"Taylor"
former_last_name	string	`staff_members.` `former_names`	The former last name of the staff member	"Jones"
dob	string	`staff_members.` `dob`	The staff member's date of birth	"1979-10-30"
title	string	`staff_members.` `basic`	The title of the staff member	"Mr"
email	string	`staff_members.` `emails`	The email address of the staff member.	"trevor.taylor @assembly.education"
is_teaching_staff	boolean	`staff_members.` `teaching_status`	Indicates whether the staff member is a teacher	true
demographics	resource		Demographic information about a staff member (this will only be included if `?demographics=true` is included in your request)
qualifications	resource	`staff_members.` `qualifications`	Information about staff member qualifications (this will only be included if `?qualifications=true` is included in your request)

Resource - Staff Demographics

Demographic information about a staff member

Field	Data Type	Scope	Description	Example
gender	enum	`staff_members.` `gender`	The gender of a staff member	"M"
ethnicity_code	string	`staff_members.` `ethnicity`	A detailed, Dfe standardised way of categorising the ethnicity of a student	"MOTH"
ethnicity_group	string	`staff_members.` `ethnicity`	A broader categorisation of ethnicity that is standardised across the country, with all ethnicity codes grouped in to 8 sections	"Mixed/ Dual Background"
disability	string	`staff_members.` `disability`	The disability status of a staff member	"No"

Resource - Staff Qualification Information

Information about staff member qualifications.

Field	Data Type	Scope	Description	Example
teacher_number	string	`staff_members.` `qualifications`	The DfE Teacher Reference number (also known as GTC number). For members of staff who have one this is a unique identifier	"31333332"
qt_status	boolean	`staff_members.` `qualifications`	Whether or not the staff member holds Qualified Teacher Status	true
hlta_status	boolean	`staff_members.` `qualifications`	Whether or not the staff member holds Higher Level Teaching Assistant Status	false
qts_route	string	`staff_members.` `qualifications`	The route by which a teacher obtains Qualified Teacher Status (e.g. the Graduate Teacher programme).	"School Direct (Salaried)"
qualifications	list	`staff_members.` `qualifications`	A list of all qualifications/degrees completed by a staff member

Resource - Staff Qualifications

A list of all qualifications/degrees completed by a staff member.

Field	Data Type	Scope	Description	Example
id	number	`staff_members.` `qualifications`	Internal, stable ID given to all staff qualifications on the Platform	323
qualification_code	string	`staff_members.` `qualifications`	A code describing the type of qualification	"Other First Degree or equivalent"
degree_class	string	`staff_members.` `qualifications`	Identifies the result of the qualification	"Upper second class honours"
first_subject_code	string	`staff_members.` `qualifications`	A code identifying the main or joint main subject of the qualification	"D900"
first_subject_name	string	`staff_members.` `qualifications`	The name of the subject	"Chemistry"
second_subject_code	string	`staff_members.` `qualifications`	A code identifying the main or joint main subject of the qualification	null
second_subject_name	string	`staff_members.` `qualifications`	The name of the subject	null

Resource - Staff Absences

Details of staff absences recorded on the MIS.

Field	Data Type	Scope	Description	Example
id	number	`staff_members.` `absences`	Internal, stable ID given to all absences on the Platform	12
staff_member_id	number	`staff_members.` `absences`	The ID of the staff member who the absence is for	112
start_date	datetime	`staff_members.` `absences`	The start date of the absence	"2017-09-06T14:00:00.000Z"
end_date	datetime	`staff_members.` `absences`	The end date of the absence	2017-09-06T16:27:00.000Z"
working_days_lost	number	`staff_members.` `absences`	Number of working days that were lost during the absence	0.5
absence_category	string	`staff_members.` `absences`	The category of the absence	"OTH"
illness_category	string	`staff_members.` `absences`	If the absence category was "Illness", the specific code	null
pay_rate	string	`staff_members.` `absences`	Whether or not the staff member was paid for the absence

Resource - Students

A student object represents a single student within a school.

Field	Data Type	Scope	Description	Example
id	number	`students.` `basic`	Internal stable ID given to students in the Platform	48
first_name	string	`students.` `basic`	The first name of the student	"Duncan"
legal_first_name	string	`students.` `legal_names`	The legal first name of the student	"Duncan"
middle_name	string	`students.` `middle_names`	The middle name of the student	"Peter"
last_name	string	`students.` `basic`	The last name of the student	"Smith"
legal_last_name	string	`students.` `legal_names`	The legal last name of the student	"Smith"
former_last_name	string	`students.` `former_names`	The former last name of the student	"Jones"
dob	string	`students.` `dob`	The date of birth of the student	"2004-10-30"
year_code	enum	`students.` `basic`	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"
former_upn	string	`students.` `former_upn`	The previous UPN where a pupil has held another UPN whilst at a school	"P3444321665112"
mis_id	string	`students.` `mis_id`	The ID of a student from the MIS	"8032"
pan	string	`students.` `pan`	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`	"A1032"
start_date	datetime	`students.` `dates`	Date when the student joined the school	"2016-03-31T00:00:00.000Z"
end_date	datetime	`students.` `dates`	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.` `enrolment_status`	The enrolment status of the student	"Current (Single Registration)"
demographics	resource		Demographics information about the student (this will only be returned if `&demographics=true` is included in your request)
contacts	list		List of contact IDs for the student (this will only be returned if `&contacts=true` is included in your request)
addresses	resource		The home address and postcode of a student (this will only be returned if `&addresses=true` is included in your request)
languages	resource		Information about a student's languages (this will only be returned if `&languages=true` is included in your request)

Resource - Student Photos

Information used to retrieve a student's photo. Please consult the "Photo Notes" of our developer documentation for more information.

Field	Data Type	Scope	Description	Example
hash	string	`students.photo`	A string that can be used to determine if a student's photo has changed	"57b0f787effcwewe233232eesdasd"
url	string	`students.photo`	A confidential URL where the photo is stored.	"https://assembly-production-platform-files.s3.eu-west- 1.amazonaws.com/410/57b0f787 effcwewe233232eesdasd.jpg?X-Amz-Algorithm=AWS4..."

Resource - Student Demographics

Demographic information about the student.

Field	Data Type	Scope	Description	Example
ethnicity_code	string	`students.` `ethnicity_code`	A detailed, Dfe standardised way of categorising the ethnicity of a student	"MOTH"
ethnicity_group	string	`students.` `ethnicity_code`	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	`students.` `gender`	The gender of the student	"M"
in_care	boolean	`students.` `care`	Looked after status - indicates whether the student is 'looked after' by the local authority	false
ever_in_care	boolean	`students.` `ever_in_care`	Ever in care status - indicates whether the student is either currently 'looked after', or has been at any point in the past	false
is_eal	boolean	`students.` `eal`	English as an Additional Language (EAL) - this field will be `true` for a student whose first language is not English	true
is_fsm	boolean	`students.` `fsm`	Free School Meals (FSM) - indicates if the student is eligible for free school meals	true
fsm_review_date	datetime	`students.` `fsm_review_dates`	Free school meal review date -Review date for pupil's free school meal eligibility	"2020-01-01"
is_pp	boolean	`students.` `pp`	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	`students.` `sen_provision`	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
country_of_birth	string	`students.` `country_of_birth`	The country of birth of the student	"United Kingdom"
nationalities	list	`students.` `nationality`	The nationality or nationalities of the student	"United Kingdom"

Resource - Student Languages

A student's language information

Field	Data Type	Scope	Description	Example
home_language_code	string	`students.` `home_language`	The code of a student's home language	"POL"
home_language_name	string	`students.` `home_language`	The name of a student's home language	"Polish"
first_language_code	string	`students.` `first_language`	The code of a student's first language	"ENG"
first_language_name	string	`students.` `first_language`	The name of a student's first language	"English"
proficiency_in_english_code	string	`students.` `proficiency_in_eng`	A student's proficiency in English code	"E"
proficiency_in_english_name	string	`students.` `proficiency_in_eng`	A student's proficiency in English name	"Fluent"

Resource - Student SEN Needs

A student's SEN Need information.

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	`students.addresses`	The first line of the address	"1 King Street"
address_line_2	string	`students.addresses`	The second line of the address	"Flat 1"
town_city	string	`students.addresses`	The town or city	"Maidstone"
county	string	`students.addresses`	The county	"Kent"
country	string	`students.addresses`	The country	"United Kingdom"
postcode	string	`students.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	"10/Ma1"
start_date	datetime	`teaching_groups`	The start date of the teaching group	"2017-09-01T00:00:00.000Z"
end_date	datetime	`teaching_groups`	The end date of the teaching group	"2018-08-31T23:59:00.000Z"
supervisor_ids	number	`teaching_groups` + `staff_members.basic`	The IDs of supervisors associated with the teaching group	1, 15
student_ids	number	`teaching_groups` + `students.basic`	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"
mis_level	string	`teaching_groups`	The official examination or assessment "level" of the teaching group taken directly from the MIS	"GCSE 9 - 1 Full Course"
assessment	resource	`teaching_groups` + `assessments.internal`	The linked Assembly Assessment, derived from the `mis_level` and mapped to normalised Assembly model

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	`registration_groups`	Internal stable ID given to all registration groups on the Platform	124
name	string	`registration_groups`	Name of the registration group	"6-Oxford"
student_ids	number	`registration_groups + students.basic`	The IDs of students associated with the registration group	141, 151, 307
supervisor_ids	numbers	`registration_groups + staff_members.basic`	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.basic`	The IDs of students associated with the year group	12, 233, 3323
supervisor_ids	number	`staff_members.basic`	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.` `basic`	Internal stable ID given to all contacts on the Platform	87
first_name	string	`contacts.` `basic`	The first name of the contact	"Tony"
middle_name	string	`contacts.` `middle_names`	The middle name of the contact	"Peter"
last_name	string	`contacts.` `basic`	The last name of the contact	"Smith"
gender	string	`contacts.` `gender`	The gender of the contact	"M"
title	string	`contacts.` `basic`	The title of the contact	"Mr"
salutation	string	`contacts.` `basic`	The salutation for the contact	"Mr Smith"
emails	list	`contacts.` `emails`	A list of emails for the contact - see the Email Addresses resource
telephone_numbers	list	`contacts.` `telephone_numbers`	A list of telephone numbers for the contact - see the Telephone Numbers resource
students	list	`contacts.` `basic`	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.` `basic`	The relationship between the contact and the student	"Mother"
priority	number	`contacts.` `priority`	The priority of this contact for the student	1
parental_responsibility	boolean	`contacts.` `parental_responsibility`	Indicates whether the contact has parental responsibility for the student	true

Resource - Telephone Numbers

The telephone number object is available for contacts 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 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). This resource can be accessed using either the assessments.national, assessments.internal or assessments.write scopes.

Field	Data Type	Description	Example
id	number	Internal stable ID given to all assessments on the Platform	1
name	string	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. This resource can be accessed using either the assessments.national, assessments.internal or assessments.write scopes.

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

Resource - Gradesets

Gradesets offer an acceptable range of values for any given assessment. This resource can be accessed using either the assessments.national, assessments.internal or assessments.write scopes.

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

Resource - Grades

The grades are the acceptable values and ids that make up a gradeset. This resource can be accessed using either the assessments.national, assessments.internal or assessments.write scopes.

Field	Data Type	Description	Example
id	number	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	The name of the grade as a string	"110", "EXS", "8"
value	numeric	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. This resource can be accessed using either the assessments.national, assessments.internal or assessments.write scopes.

Field	Data Type	Description	Example
id	number	Internal stable ID given to all facets on the Platform	6
name	string	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. This resource can be accessed using either the assessments.national, assessments.internal or assessments.write scopes.

Field	Data Type	Description	Example
rank	number	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	The name of the assessment point	"Key Stage 2"
type	string	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	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. This resource can be accessed using either the assessments.national, assessments.internal or assessments.write scopes.

Field	Data Type	Description	Example
id	number	Internal stable ID given to all results on the Platform	101
student_id	number	The ID of the student that the result is attached to	923
subject_id	number	The ID of the subject that the result is attached to	2
assessment_id	number	The ID of the assessment that the result is attached to	1
assessment_point_rank	number	The rank of the assessment point	48
aspect_id	number	The ID of the aspect that the result is attached to	6
grade_id	number	The ID of the grade	157
result_date	date	The date on which the result was recorded in the MIS or standardised assessment system	"2013-06-26T00:00:00.000Z"
created_at	datetime	The date and time that the result was first created on Assembly	"2017-06-07T09:24:06.991Z"
updated_at	datetime	The date and time that the result was last updated on Assembly	"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"

Resource - Exclusions

The exclusions resource details official exclusions from a school.

Field	Data Type	Scope	Description	Example
id	number	`exclusions`	Internal stable ID given to all exclusions on the Platform	243
student_id	number	`exclusions`	The ID of the student that the exclusion is attached to	15085
exclusion_type	string	`exclusions`	The exclusions type	"Fixed Term"
exclusions_reason	string	`exclusions`	The exclusion reason	"Drug and alcohol related"
start_date	string	`exclusions`	The date on which the exclusions starts	"2017-12-07T00:00:00.000Z"
start_session	string	`exclusions`	The session in which the exclusion starts	"AM"
end_date	string	`exclusions`	The date on which the exclusion ends	"2017-12-09T00:00:00.000Z"
end_session	string	`exclusions`	The session (AM/PM) in which the exclusion ends	"PM"
exclusion_length	number	`exclusions`	The total length, in sessions, of the exclusion	6

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

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