Developer FAQs

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

How can I test your API?

You can sign up to your own Sandbox account here! Please see this guide for help on getting started.

Why aren't students and contacts returned in alphabetical order?

Although students and staff members may not be returned in alphabetical order by default, you can use a ?sort=true query string parameter to return the records alphabetically.

Should I use the Unique Pupil Number (UPN) to uniquely identify a student?

DfE guidance from 2013 states that "the UPN must be a ‘blind number’ not an automatic adjunct to a pupil’s name.” That document also describes the purpose of the UPN as "to provide information to the LA, central government or another school/academy to which the pupil is transferring.” However, elsewhere in the document the guidance gives the slightly more broader statement that they should not be "disclosed to anyone without valid consent or legitimate reason", which some have taken to mean that a school may justifiably give consent for UPN sharing for other uses, provided they have a sensible reason.

In practice, it is usually possible to handle your pupil identification needs without using UPN. With this in mind, we strongly recommend you use the student_id field to uniquely identify a student (an Assembly-generated identifier that is unique to every person, including students) instead of UPN.

If you need a unique identifier for data matching purposes, we recommend you use the Pupil Admission Number (PAN) together with the pupil’s admission year and the school’s URN to create a unique identifier. The PAN is available to schools in the front end of the MIS, so a school should be able to enter it themselves into your app in advance of the data migration process.

Do you use a student's "preferred" name or "legal" name?

Some MIS have the ability to list a preferred name and a legal name for a student. We initially try to pull the preferred name of a student from the MIS, but if this field is blank we will use the official or legal name as a backup, ensuring the student's name is always populated.

How is access to school data controlled?

Access to school data is controlled by a data access request. The data access request clearly shows the scopes of data that your authorisation request has asked for, and must be authorised by a school for data to flow. The available scopes can be found on our API documentation and on our data model.

Can a school use my app if they haven't given authorisation to all of the data scopes?

No. Schools must give authorisation to all data scopes your app requires in order to use it. If there is a data scope that isn't essential for your app that schools are not comfortable giving access to, you should adjust your app's authorisation request accordingly.

Why do I need access to a separate scope to retrieve looked after status?

The field is particularly sensitive, and we have therefore deemed it requires a data scope of it's own. You can return this field for a student the same way as with other student demographic information ( GET /students?demographics=true&care=true), but it will only be included if you have access to this scope.

How do I get schools connected to the Assembly Platform?

For more information on how to onboard schools, please see this support article.

Can pagination be turned off?

No. However, the per_page parameter allows you to set how many results to return per page. For example, this value could be set to 100 when returning a teaching group list. Since teaching groups generally only contain around 30 students this would ensure a full teaching group is returned. Year groups, on the other hand, tend to contain over 100 students, so you may want to adjust your per_page parameter accordingly.

How do I return teaching groups for a specific year?

To return teaching groups for a specific year, you can set the year group as a query parameter on your request like so: GET /teaching_groups?year_code=9 .

The same can also be done with registration groups and student endpoints.