API Documentation

Technical documentation for our Platform API

Resources


User Guide

Introduction

The Assembly API is built around the REST and a collection of open standards/protocols in order to comply with as many consumers as possible. We recommend that developers wishing to work with our APIs are familar with the following technologies before continuing:

  • HTTP / REST All communication is handled over HTTPS using standard HTTP verbs, status codes and headers.
  • JSON All response bodies are returned in JSON format.
  • OAuth Authorisation is handled via OAuth 2.0.
  • Bearer Tokens Resource Authentication is managed with Bearer Tokens.

Endpoints

All live API calls should be made over HTTPS to:

https://api.assembly.education

All Sandbox API calls should be made over HTTPS to:

https://api-sandbox.assembly.education

All live OAuth flow requests should be made to:

https://platform.assembly.education

All Sandbox OAuth flow requests should be made to:

https://platform-sandbox.assembly.education

Versioning

The API requires that you specify the version of the api that you which to consume in the Accept request header. The current version of the API is version 1.

curl -H "Accept: application/vnd.assembly+json; version=1"

Failure to provide a valid version will result in a 406 response.

Status 406
{"error": "unsupported_version"}

Within a given API version additional features and functionality (including new: endpoints, attributes, headers or optional parameters) may be added without warning but backwards compatibility will be maintained.

Authentication

Assembly rely on OAuth to manage access to school data and Bearer Tokens to authorise API requests. The platform can issue two types of tokens to an application, app level tokens and school level tokens.

Tokens give access to data within the Assembly Platform. It is therefore vitally important that they are treated as highly confidential and handled / stored accordingly. Any suspected breach of a token's security should be reported to Assembly immediately.

App Level Tokens

These can be generated at any time through the Assembly Platform website, they never expire and give access to application level resources. At the time of writing these tokens are of limited value.

School Level Tokens

These can only be acquired by a school explicitly authorising your Application to access their data via an OAuth flow. School level access tokens have a scope and expiry time associated with them.

When requesting access to a school you must request the scopes of data that your application requires access to. The available scopes are:

Scope Description
school This includes school level information that is generally publicly available or non-sensitive. Examples include the school's name, URN and subject list.
calendar Calendar events from the school's MIS calendar, as well as details of term dates (currently available on SIMS only).
registration_groups Provides access to a school's registration groups.
teaching_groups Provides access to teaching group names and subjects. What teaching groups we pull from your MIS is governed by the subject mappings you have configured within the Assembly Platform.
students.basic Provides access to basic student information (for example first name, last name and year group).
students.middle_names Provides access to student middle names.
students.legal_names Provides access to student legal names.
students.former_names Provides access to student former names.
students.upn Provides access to unique pupil numbers for students.
students.former_upn Provides access to any former unique pupil numbers for students.
students.dates Provides access to student start and end dates.
students.dob Provides access to dates of birth for students.
students.enrolment_status Provides access to the enrolment status of students.
students.pan Provides access to student pupil admission numbers.
students.mis_id Provides access to the MIS identifier for students.
students.gender Provides access to the gender of students.
students.country_of_birth Provides access to the country of birth for students.
students.nationality Provides access to student nationalities.
students.ethnicity Provides access to the ethnicity of students.
students.first_language Provides access to the first language for students.
students.home_language Provides access to the home language for students.
students.proficiency_in_eng Provides access to proficiency in English for students.
students.eal Provides access to the English as Additional Language status for students.
students.pp Provides access to the pupil premium status of students.
students.fsm Provides access to the free school meal status for students.
students.fsm_review_dates Provides access to the review date for student free school meal eligibility.
students.care Provides access to the in care or "looked after" status for students.
students.ever_in_care Provides access to whether a student has been in care at any point.
students.service_child Provides access to whether a student is a service child.
students.siblings Provides access to a list of student siblings.
students.sen_provision Provides access to special education need provision for students.
students.sen_needs Provides access to special education needs for students.
students.medical.conditions Provides access to medical conditions for students (for example Asthma).
students.medical.dietary_needs Provides access to dietary needs for students (for example Halal).
students.medical.emergency_consent Provides access to the if the student (or guardian) has given emergency consent.
students.medical.nhs_number Provides access to the NHS number of the student.
students.medical.notes Provides access to medical notes for students and their medical conditions.
students.medical.pregnancy Provides access to the the student's pregnancy status.
students.addresses Provides access to student home addresses and postcodes.
students.photo Provides access to student photos.
contacts.basic Provides access to basic contact information (for example first name, last name, title and relationship to students).
contacts.middle_names Provides access to contact middle names.
contacts.emails Provides access to contact email addresses.
contacts.gender Provides access to the gender of contacts.
contacts.parental_responsibility Provides access to the parental responsibility flag for contacts.
contacts.priority Provides access to the priority of contacts.
contacts.telephone_numbers Provides access to contact telephone numbers.
staff_members.basic Provides access to basic staff member information (for example staff code, first name, last name and title).
staff_members.middle_names Provides access to staff member middle names.
staff_members.legal_names Provides access to staff member legal names.
staff_members.former_names Provides access to the former names of staff members.
staff_members.dates Provides access to staff member start and end dates.
staff_members.included_in_census The scope provides access to whether or not staff members are included in the School Workforce Census.
staff_members.teaching_status Provides access to the teaching status of staff members.
staff_members.mis_id Provides access to the MIS identifier for staff members.
staff_members.dob Provides access to dates of birth for staff members.
staff_members.gender Provides access to the gender of staff members.
staff_members.ethnicity Provides access to the ethnicity of staff members.
staff_members.disability Provides access to the disability status of staff members.
staff_members.emails Provides access to staff member email addresses.
staff_members.absences Provides access to staff member absences.
staff_members.qualifications Provides access to staff member qualifications (for example teacher number, QT status, HLTA status and degree information).
staff_members.contracts Provides access to staff contract information (for example NI number, payroll number, contract type, post and roles). No salary information is extracted with this scope.
staff_members.salaries Provides access to staff member salaries and allowances (for example pay scale, pay framework and additional payment amount).
attendances Provides access to morning and afternoon attendance marks (AM/PM roll call).
attendances.summaries Provides access to a summary of student attendance information.
exclusions Official student exclusions stored in the MIS.
assessments.national Provides access to students' national assessment results (for example, Key Stage 2 SATs results).
assessments.internal Provides access to the school's internal assessments. What results are exported is governed by the assessment mappings that you have configured on the Assembly Platform.
assessments.write This scope allows an application to store its assessment data securely in the Assembly platform so that you can use it later for analytics tools.

Optional and Required Scopes

Scopes can be defined as either required or optional. To comply with data protection regulations and good practice, all scopes that are not necessary for the core purpose of an app should be defined as optional.

If a scope is defined as required, it will be listed on a school's Data Access Request, and the school must agree to sharing this scope of data in order to authorise an app. Scopes can be defined as required by including :required after the scope in an authorisation request (for example: students.basic:required).

If a scope is defined as optional, it will be listed on a school's Data Access Request with a check box next to it, which is by default not ticked. A school can then opt in to these scopes when authorising an app by ticking the relevant boxes. Scopes can be defined as optional by including :optional after the scope in an authorisation request (for example: students.ethnicity:optional).

Please note: if :required or :optional is not specified after the scope name, scopes behave as if they are required.

Scope Dependencies

Some scopes of data have dependencies on others. All student scopes are dependent on the students.basic scope (likewise with staff members and contacts). Therefore, requesting one of these in your access_token will also return the students scope.

Token Expiry & Refresh

School level Access Tokens are currently valid for 1 day, although your application should not rely on this as token expiry times are likely to be reduced in future.

Each successful OAuth authorization also contains a refresh_token, Refresh Tokens should be used to aquire a new access token upon expiry.

Using Tokens

All API endpoints require Bearer token authentication. The token should be set in an Authorization request header.

curl -H "Authorization: Bearer b2s7a9s8BQokikJOvBiI2HlWgH4olfQ2"

API requests that are missing an Authorization header will receive a 401 response:

Status 401
{
  "error": "invalid_request",
  "message": "an access_token is required."
}

Read More in the OAuth documentation…

Conditional Requests

Some of the API endpoint responses contain a Last-Modified header. You can use this value to make subsequent requests to these endpoints using the If-Modified-Since header; the server will then return only data which has changed since this date. If no data has changed since this date, then the server will return a response of 304 Not Modified .

Note if a 'full sync' has been performed on a school then all data will be flagged as having changed, which means that using this header will result in all data being returned.

The following endpoints currently support conditional requests:

  • Students
  • Staff members
  • Calendar events
  • Teaching groups
  • Registration groups
  • Year groups
  • Attendances

Errors

Assembly uses HTTP response status codes to indicate the status of an API request.

  • Status codes in the 200 range indicate a successful request.
  • Status codes in the 400 range indicate that the request has failed, usually due to a client error.
  • Status codes in the 500 range indicate that the request has failed due to a server error.

Generally error responses contain a JSON body made up of an error key and a more descriptive message however this is not guaranteed. For example:

Status 401
{
  "error": "invalid_request",
  "message": "an access_token is required."
}

Rate Limiting

In order to protect the availability and security of our systems all HTTP calls are subject to rate limiting. Except where noted the following limits are in place.

In extreme circumstances very abusive clients may be subject to blacklisting.

Please note: We are evaluating these limits and they are subject to change. If you feel you require a higher limit please contact support.

Each Access Token is limited to 600 requests within a 5 minute window, or two requests per second. If you exceed this limit you will receive a response that tells you:

  • count the number of requests you have made with the current token.
  • period the number of seconds until the current token may make another request.
  • limit the total number of requests the current token may make within a 5 minute window.
The response will look something like this:
Status 429
{
  "error":"too many requests",
  "data": {
    "count": 601,
    "period": 300,
    "limit": 600
  }
}

Pagination

Any request that results in a list type being returned is presented as a paged response. The response data gives you the information to navigate through the paged data set. Further pages can be requested using the page querystring parameter. Optionally the number of results to be included on each page can be specified with the querystring parameter per_page, which defaults to a value of 100 and has a maximum value of 1500.

Status 200
{
  "object": "list",
  "total_count": 10,
  "total_pages": 2,
  "current_page": 1,
  "prev_page": null,
  "next_page": 2,
  "data": [ 1, 2, 3, 4, 5 ]
}

Data Model

Full field level documentation on our data model can be found here.