GO 4 Schools

INTRODUCTION

ENDPOINTS

Introduction

Welcome

The GO 4 schools API allows you to manage school data within the GO 4 Schools application using conventional HTTP requests. The endpoints are extensive and cover the majority of data we use at GO, allowing you to read from GO and eventually write to GO.

Authentication

Authentication is required for all endpoints. Claims needed are specified within the individual requests. The schools data you wish to access will be responsible for handling your authentication and will grant you access using a key, which will be needed in every request.

Errors

Status Code Error Error Message Description
400 Bad Request Invalid School The school provided does not exist.
400 Bad Request Invalid Academic Year The school does not have data for the specified academic year.
400 Bad Request Invalid Report ID The school does not have data for the specified report.
400 Bad Request Invalid Year Group The school does not have data for this year group.
400 Bad Request Invalid Cursor The cursor is less than 0.
400 Bad Request Unknown Attendance Mark The attendance mark ID provided is not in use for the school and academic year.
400 Bad Request Unknown Attendance Alias Mark The attendance alias mark ID provided is not in use for the school and academic year or is not associated with the attendance mark ID provided.
400 Bad Request Unknown student UPN The UPN provided does not belong to a student in the school provided.
400 Bad Request Attendance Invalid Mode The school does not have the correct Attendance Mode to use the endpoint.
400 Bad Request Unknown session type. The session type provided is not 'AM' or 'PM'.
400 Bad Request Invalid date. The date provided is not in the correct format or is invalid.
400 Bad Request Student not at this school. The student provided is not associated with the school.
400 Bad Request Date school not open. The date provided for the POST session attendance is a date when the school is not open.
400 Bad Request Staff not at the school. The ID provided is not a member of staff for this school.
400 Bad Request Invalid model state Invalid data in packet: Could not convert string to DateTime: 2020-15-14. Path 'date'.
401 Unauthorized The API key is invalid.
403 Forbidden Module Disabled The school does not have the specific module.
403 Forbidden Embargo Enabled The school has enabled the embargo.
403 Forbidden Not Enabled For Bromcom Endpoint not available for Bromcom schools.
404 Not found The resource could not be found.
429 Too Many Request Too many requests sent in a given amount of time.
500 Internal server We had a problem with our server. Please try again later.

Endpoints

Assessment

GET Markbooks

You need the Assessment-Markbook structure (school.assessment.read) permission to view this endpoint.

Returns the structure of markbooks in the chosen academic year, in terms of the marksheets they contain, and the markslots within each marksheet.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Request

			
			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/assessment/markbooks
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "id": 111111,
			        "marksheets": [
			            {
			                "id": 111222,
			                "name": "R1 Art Concepts",
			                "markslots": [
			                    {
			                        "id": 111333,
			                        "name": "Assessment 1: Materials",
			                        "max": 2
			                    },
			                    ...
			                ]
			            },
			            ...
			        ]
			    },
			    ...
			]

Markbooks Object

Name Type Description
id integer The unique identifier for the markbook. A subject is associated with a single markbook and they share the same Id.
marksheets array The array of marksheets within a markbook.
| id integer The unique identifier for the marksheet.
| name string The name of the marksheet.
| markslots array The array of markslots within a marksheet.
| id integer The unique identifier for the markslot (assessment).
| name string The name of the markslot.
| max integer The max mark of the markslot.

GET Marksheets

You need the Assessment-Marksheet Grades (students.assessment.marksheets.read) permission to view this endpoint.

Returns details of the grades achieved by students for individual marksheets.

• Use the GET Markbooks to match this to the name of the marksheet.

• Use the GET Students to get the personal details of the student.

Route parameters

Name Type Description
academicYear integer academic year for the requested classes

Query parameters

Name Type Description Required
cursor integer used to request further data when has_more is true no

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/assessment/marksheet-grades
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "marksheets": [
			        {
			            "id": 111222,
			            "grades": [
			                {
			                    "student_id": 987654,
			                    "grade": "U"
			                    "alias": "W/T Pass"
			                },
			                ...
			            ]
			        },
			        ...
			    ],
			    "has_more": true,
			    "cursor": 123
			}

Marksheets Object

Name Type Description
marksheets array An array of all marksheets.
| id integer The unique identifier for the marksheet.
| grades array An array of student grades for the marksheet.
| student_id integer The unique identifier for a student.
| grade string Name of the grade recorded.
| alias string, nullable School name of the grade.
has_more boolean Boolean representing if there are more results.
cursor integer, nullable Used to request further data when has_more is true.

GET Marks

You need the Assessment-Student Marks (students.assessment.markslots.read) permission to view this endpoint.

Returns details of the marks achieved by students for individual marks.

• Use the GET Markbooks to match this to the name of the assessment.

• Use the GET Students to get the personal details of the student.

Route parameters

Name Type Description
academicYear integer academic year for the requested classes

Query parameters

Name Type Description Required
cursor integer used to request further data when has_more is true no

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/assessment/marks
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "markslots": [
			        {
			            "id": 111333,
			            "marks": [
			                {
			                    "student_id": 987654,
			                    "grade": "5",
			                    "alias": "Significantly Above Average",
			                    "mark": "5.00000"
			                },
			                ...
			            ]
			        },
			        ...
			    ],
			    "has_more": true,
			    "cursor": 123
			}

Marks Object

Name Type Description
markslots array An array of markslots (assessments) within a marksheet.
| id integer The unique identifier for the markslot (assessment).
| marks array An array of student plus awarded grade for an assessment.
| student_id integer The unique identifier for a student.
| grade string The grade awarded.
| alias string, nullable School name of the grade.
| mark float The value of the awarded grade.
has_more boolean Boolean representing if there are more results.
cursor integer, nullable Used to request further data when has_more is true.

Attainment

GET Grade Types

You need the Attainment-School Grade Types (school.attainment.read) permission to view this endpoint.

Returns details of the available types of headline grades.

Route parameters

Name Type Description
academicYear integer academic year for the requested classes
yearGroup string year group for the requested data, eg. 'Reception', '11'

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/attainment/grade-types/year-group/{yearGroup}
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "id": 1,
			        "name": "External target",
			        "short_name": "External target",
			        "description": "External target",
			        "is_preferred_progress_grade": false,
			        "is_preferred_target_grade": true,
			    },
			    ...
			]

Grade Types Object

Name Type Description
id integer The grade type is one of the 10 grade types that can be configured in GO:
1 = External target
2 = Teacher target
3 = Combined target
4 = Current
5 = Projected
6 = Actual
7 = Honest
8 = Aspirational
9 = Additional target
10 = Baseline grade
name string The name of the grade for this year group.
short_name string The short name of the grade for this year group.
description string The grade description for this year group.
is_preferred_progress_grade boolean Is this grade set as the preferred progress grade for this year group.
is_preferred_target_grade boolean Is this grade set as the preferred target grade for this year group.

GET Grades

You need the Attainment-Student Grades (students.attainment.read) permission to view this endpoint.

Returns details of the headline grades for students.

• Use the GET Grade Types to determine the grade name.

• Use the GET Students to link to student personal details.

• Use the GET Subjects to determine subject details.

Route parameters

Name Type Description
academicYear integer academic year for the requested classes
yearGroup string year group for the requested data, eg. 'Reception', '11'

Query parameters

Name Type Description Required
cursor integer used to request further data when has_more is true no

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/attainment/grades/year-group/{yearGroup}
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "grades": [
			        {
			            "grade_type_id": 1,
			            "subject_id": 222222,
			            "student_id": 987654,
			            "name": "5",
			            "alias": "alias",
			        },
			        ...
			    ]
			}

Grades Object

Name Type Description
grades array Array of grades and student marks for a given grade type.
| grade_type integer One of the 10 grade types that can be configured in GO.
| subject_id integer Unique identifier for a subject.
| student_id integer Unique identifier for a student.
| name string Grade name.
| alias string School name for the grade.
has_more boolean Boolean representing if there are more results.
cursor integer, nullable Used to request further data when has_more is true.

GET Exam Results

You need the Attainment-Student Exam Results (students.attainment.exam-results.read) permission to view this endpoint.

Returns details of the exam results achieved by students.

• Use the GET Students to link to student personal details.

• Use the GET Subjects to determine subject details.

Route parameters

Name Type Description
academicYear integer academic year for the requested classes
yearGroup string year group for the requested data, eg. 'Reception', '11'

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/attainment/exam-results/year-group/{yearGroup}
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "student_id": 987654,
			        "exam_academic_year": 2019,
			        "qan": "601/4700/3",
			        "qualification_title": "Pearson Edexcel Level 1/Level 2 GCSE (9-1) in Mathematics",
			        "exam_date": "2019-01-31T00:00:00Z",
			        "grade": "3",
			        "ks123literal": "3+",
			        "subject_id": 222222,
			    },
			    ...
			]

Exam Results Object

Name Type Description
student_id integer The unique identifier for a student.
exam_academic_year integer The academic year that the exam was taken by the student.
qan string Qualification Accreditation Number.
qualification_title string The title of the qualification.
exam_date date, nullable The date that the exam was taken.
grade string The grade awarded to the student.
ks123literal string The value of the grade awarded.
subject_id integer, nullable The unique identifier for a subject.

GET Prior Attainment

You need the Students-Prior Attainment (students.prior-attainment.read) permission to view this endpoint.

Returns prior attainment for students.

• Use GET Students to resolve to personal student personal details.

Route parameters

Name Type Description
academicYear integer academic year for the requested classes

Query parameters

Name Type Description Required
cursor integer used to request further data when has_more is true no

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/attainment/prior-attainment
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "prior_attainment": [
			        {
			            "code": "priorAttainmentKS2",
			            "name": "Prior Attainment (KS2)",
			            "values": [
			            {
			                    "student_id":  987654,
			                    "value" : "MPA",
			                    "academic_year": 2019,
			                    "date": "2019-01-31T00:00:00Z"
			                },
			                ...
			            ]
			        },
			        ...
			    ],
			    "has_more": true,
			    "cursor": 123
			}

Student Prior Attainment Object

Name Type Description
prior_attainment array Array of prior attainment codes and the values held for each for a student.
| code string The unique system code for the attribute.
| name string The name of the prior attainment attribute.
| values array The array of student values for the particular prior attainment attribute.
| student_id integer The unique identifier for the student.
| value string The value recorded for the student.
| academic_year string, nullable Only populated if this value was timestamped against the requested academic year.
| date string, nullable Timestamped date.
has_more boolean Boolean representing if there are more results.
cursor integer, nullable Used to request further data when has_more is true.

Attendance

GET Attendance Codes

You need the Attendance-Session Summary (school.attendance.read) permission to view this endpoint.

This returns the Attendance codes and any aliases being used for the academic year.

Route parameters

name type description
academicYear number academic year for the requested data

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/attendance/codes
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "id": 12,
			        "code": "/",
			        "label": "Present (AM)",
			        "attendance_officer_only": true,
			        "protect_if_entered_by_attendance_officer": false,
			        "protect_if_entered_by_school_manager": false,
			        "protect_if_entered_by_behaviour_manager": false,
			        "aliases": [
			            {
			                "id": 1522,
			                "alias_code": "IR",
			                "alias_label": "Isolation Room"
			            },
			            ...
			        ]
			    },
			    ...
			]

Attendance Codes Object

Name Type Description
id int The unique identifier for the Attendance Code. This is unique for a school and academic year. It will not be unique across a trust.
code string The attendance code that staff use to record attendance.
label string The description of the attendance code.
attendance_officer_only string Only attendance officers can use this mark.
protect_if_entered_by_attendance_officer string This mark has protected access if entered by an attendance officer - in this case only an attendance officer may edit it.
protect_if_entered_by_school_manager string This mark has protected access if entered by a school manager - in this case only an attendance officer or school manager may edit it.
protect_if_entered_by_behaviour_manager string This mark has protected access if entered by a behaviour manager - in this case only an attendance officer, school manager or behaviour manager may edit it.
aliases array The array of aliases that are associated to this Attendance codes.
| id int The unique identifier for the alias.
| code string The alias code.
| label string The description of the alias.

GET Student Session Marks

You need the Attendance-Session marks (students.attendance.session.read) permission to view this endpoint.

This returns attendance details for a particular date.

• Use the GET Attendance codes to translate to attendance codes.

• Use the GET students to get the personal details of the student.

Route parameters

name type description
academicYear number academic year for the requested data
date date used to return data for a particular date. Format expected yyyy-mm-dd.

Request

			
			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/attendance/student-session-marks/date/{date}
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK

			
			[
			   {
			      "date": "2018-12-31T00:00:00Z",
			      "session": "AM",
			      "student_id": 987654,
			      "session_mark_id": 12,
			      "session_alias_id": 1522,
			      "session_minutes_late": 10,
			      "session_notes": "Bus was late"
			   },		
			   ...
			]

Attendance Session Marks Object

Name Type Description
date date The date of the session attendance.
session string Determines the session : one of AM or PM.
student_id int The unique identifier for the student.
session_mark_id int The unique identifier of the attendance mark for the particular session.
session_alias_id int, nullable The unique identifier of the attendance alias mark for the particular session.
session_minutes_late int, nullable The number of minutes late the student was for the particular session.
session_notes string, nullable Notes recorded against the particular session.

GET Student Lesson Marks

You need the Attendance-Lesson marks (students.attendance.lesson.read) permission to view this endpoint.

This returns attendance details for a particular date.

• Use the GET Attendance codes to translate to attendance codes.

• Use the GET Students to get the personal details of the student.

• Use the GET Class ID to get details of timetabled classes.

Route parameters

name type description
academicYear number academic year for the requested data
date date used to return data for a particular date

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/attendance/student-lesson-marks/date/{date}
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK

			
			[
			    {
			        "date": "2019-06-25T00:00:00Z",
			        "student_id": 987654,
			        "class_id": 123456,
			        "lesson_mark_id": 4,
			        "lesson_alias_id": 563,
			        "lesson_minutes_late": 5,
			        "lesson_notes": "Parent teacher meeting"
			    },
			    ...
			]

Attendance Lesson Marks Object

Name Type Description
date date The date of the lesson attendance.
student_id int The unique identifier for the student.
class_id int The unique identifier for the class.
lesson_mark_id int The unique identifier for the attendance mark for the lesson.
lesson_alias_id int, nullable The unique identifier for the attendance alias mark for the lesson.
lesson_minutes_late int, nullable The number of minutes late for the lesson.
lesson_notes string, nullable Notes against this lesson attendance.

GET Students Attendance Summary

You need the Attendance-Session Summary (school.attendance.read) permission to view this endpoint.

This returns summary session data for all students for the academic year up to (but not including) today.

• Use the GET Attendance codes to translate to attendance codes.

• Use the GET students to get the details of the student.

Route parameters

name type description
academicYear number academic year for the requested data

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/attendance/student-session-summary
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "student_id": 987654,
			        "possible_sessions": 338,
			        "present": 149,
			        "approved_educational_activity": 124,
			        "authorised_absence": 65,
			        "unauthorised_absence": 0,
			        "attendance_not_required": 0,
			        "missing_mark": 0,
			        "late": 4
			    },
			    ...
			]

Student Attendance Summary Object

Name Type Description
student_id int The unique idenitifier for the student.
possible_sessions int The total number of possible session marks.
present int The total number of present session marks.
approved_educational_activity int The total number of AEA session marks.
authorised_absence int The total number of authorsied absence session marks.
unauthorised_absence int The total number of unauthorsied absence session marks.
attendance_not_required int The total number of marks where attendance is not required.
missing_mark int The total number of missing marks.
late int The total number of late session marks (before registration closed).

POST Student Session Attendance

You need the Attendance - Session marks (write) (students.attendance.session.write) permission to view this endpoint.

Saves the detail for one session for a single student.

Route parameters

name type description
academicYear number academic year for the requested data

Query parameters

A JSON packet as defined below:

Name Type Description
attendance object A single students attendance object.
student_upn string Students Unique Pupil Number.
date string Date of the attendance session.
session string Whether morning / after session: use 'AM', 'PM'.
session_mark_id string Attendance code id.
session_mark_alias_id string, nullable Attendance alias id.
session_minutes_late int, nullable Minutes late
session_notes string, nullable Comment
student_mis_id string, nullable Identifier of the student in the MIS.

Request


			curl -X POST
			    -H "Authorization: Bearer {ApiKey}"
			    -H "Content-Type: application/json"
			    -d '{
			        "student_upn" : "UPN123456789",
			        "date" : "2019-01-05",
			        "session" : "AM",
			        "session_mark_id" : 1,
			        "session_mark_alias_id" : null,
			        "session_minutes_late" : null,
			        "session_notes" : null,
			        "student_mis_id" : null
			    }' 
			    "https://api.go4schools.com/customer/v1/academic-years/{academicYear}/attendance/student-session-marks"

Response

200 OK

Behaviour

GET Follow-up Actions

You need the Behaviour-Behaviour Scheme (school.behaviour.read) permission to view this endpoint.

This returns the current definitions for follow up behaviour actions for the supplied academic year.

Route parameters

Name Type Description
academicYear integer academic year for the requested classes

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/behaviour/actions/follow-up
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "id": 123456,
			        "name": "Remove student from classroom",
			        "alias": "Remove",
			        "type": "Standard"
			    },
			    ...
			]

Follow-up Actions Object

Name Type Description
id integer The unique identifier for the immediate action.
name string The name of the immediate action.
alias string, nullable The name displayed to parents and students for the immediate action.
type string The type of this immediate action: one of Standard or Detention.

GET Immediate Actions

You need the Behaviour-Behaviour Scheme (school.behaviour.read) permission to view this endpoint.

This returns the current definitions for immediate behaviour actions for the supplied academic year.

Route parameters

Name Type Description
academicYear integer academic year for the requested classes

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/behaviour/actions/immediate
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "id": 123456,
			        "name": "Remove student from classroom",
			        "alias": "Remove",
			        "type": "Standard"
			    },
			    ...
			]

Immediate Actions Object

Name Type Description
id integer The unique identifier for the immediate action.
name string The name of the immediate action.
alias string, nullable The name displayed to parents and students for the immediate action.
type string The type of this immediate action: one of Standard or Detention.

GET Classification

You need the Behaviour-Behaviour Scheme (school.behaviour.read) permission to view this endpoint.

This returns the current behaviour classification groups for the supplied academic year.

Route parameters

Name Type Description
academicYear integer academic year for the requested classes

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/behaviour/classification
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "id": 123456,
			        "name": "Disruptive behaviour",
			        "score": 15
			        "immediate_actions": [
			            {
			                "id": 123456,
			                "completion_type": "Optional"
			            },
			            ...
			        ],
			        "follow_up_actions": [
			            {
			                "id": 123456,
			                "completion_type": "Mandatory"
			            },
			            ...
			        ]
			    },
			    ...
			]

Classification Object

Name Type Description
id integer The unique identifier for the behaviour classification group.
name string The name of the behaviour classification group.
score integer The severity score of the behaviour classification group.
immediate_actions array The array of immediate actions defined for this event type.
| id integer The unique identifier for the immediate action.
| completion_type string Determines whether immediate action is Mandatory, Recommended or Optional.
follow_up_actions array The array of immediate actions defined for this event type.
| id integer The unique identifier for the follow up action.
| completion_type string Determines whether follow up action is Mandatory, Recommended or Optional.

GET Event Types

You need the Behaviour-Behaviour Scheme (school.behaviour.read) permission to view this endpoint.

This returns the current definition of the behaviour types for the supplied academic year.

Route parameters

Name Type Description
academicYear integer academic year for the requested classes

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/behaviour/event-types
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			       "id": 123456,
			       "classification_id": 1234567,
			       "code": "DB1",
			       "name": "First Verbal Warning",
			       "alias": "FVW",
			       "significance": "Negative",
			       "prioritise": false
			    },
			    ...
			]

Event Types Object

Name Type Description
id integer The unique identifier for the event type.
classification_id integer The unique identifier for the classification group that the event type belongs to.
code string The code of the event type.
name string The name of the event type.
alias string, nullable The name displayed to parents and students for the event type.
significance string Significance of the event type: one of Positive, Neutral or Negative.
prioritise boolean Flag whether to prioritise for group behaviour.

GET Events

You need the Behaviour-Student Behaviour (students.behaviour.read) permission to view this endpoint.

This returns lists of events for a particular date within an academic year.

• Use the GET Event Types to get the characteristics of the event.

• Use the GET Students to get the personal details of the student.

Route parameters

Name Type Description
academicYear integer academic year for the requested classes
date date used to return data for a particular date ( yyyy-mm-dd )

Query parameters

Name Type Description Required
cursor integer used to request further data when has_more is true no

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/behaviour/events/date/{date}
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "behaviour_events": [
			        {
			            "id": 123456,
			            "event_type_id": 123456,
			            "event_date": "2019-01-31T12:45:13Z",
			            "closed": false,
			            "cancelled": false,
			            "room_name": "CP1",
			            "group_name": "11/CP1",
			            "subject_code": "Comp",
			            "year_group": "11",
			            "home_notes": "Made no effort at all to complete the work despite help being given.",
			            "school_notes": "Made no effort at all to complete the work despite help being given.",
			            "created_timestamp": "2020-01-01T00:00:00Z",
			            "created_by": 123456,
			            "modified_timestamp": "2020-01-01T00:00:00Z",
			            "modified_by": 123456,
			            "student_ids": [
			                987654,
			                ...
			            ],
			            "event_action_ids": [
			                4502,
			                ...
			            ],
			            "event_followup_type_ids": [
			                2054,
			                ...
			            ]
			        },
			        ...
			    ],
			    "has_more": true,
			    "cursor": 123
			}

Events Object

Name Type Description
behaviour_events array Array of events for specified date.
| id integer The unique identifier for the behaviour event.
| event_type_id integer The unique identifier for the type of behaviour event.
| event_date date UTC date of the event.
| closed boolean Flag to determine whether event is closed.
| cancelled boolean Flag to determine whether the event has been cancelled.
| room_name string, nullable The room where the event took place.
| group_name string, nullable The group name logged against the event.
| subject_code string, nullable The subject code logged against the event.
| year_group string, nullable The year group logged against the event.
| home_notes string, nullable Home notes logged against the event.
| school_notes string, nullable School notes logged against the event.
| created_timestamp date UTC date when the event was created.
| created_by integer Identifier for the member of staff that created the event.
| modified_timestamp date, nullable UTC date when the event was last modified.
| modified_by integer, nullable Identifier for the member of staff that last modified the event.
| student_ids array A list of student identifiers that this event was logged against.
| event_action_ids array A list of immediate actions which are attached to this event.
| event_followup_type_ids array A list of follow-up actions which are attached to this event.
has_more boolean Boolean representing if there are more results.
cursor integer, nullable
 Used to request further data when has_more is true.

Contacts

GET Parental Contacts

You need the Contacts-Student Parents (students.parents.read) permission to view this endpoint.

Returns the parental contact details for students

• Use GET Students to link to student personal details.

Request


			curl https://api.go4schools.com/customer/v1/contacts/parental
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "student_id": 987654,
			        "parent_display_name": "Mrs Jane West",
			        "priority": 1,
			        "email_address": "jane.west@example.com",
			        "home_telephone": "0123456789",
			        "main_telephone": "0123456789",
			        "mobile": "0123456789",
			        "is_main_email_address_for_contact": false,
			        "student_contact_mis_id": 12345
			    },
			    ...
			]

Contacts Object

Name Type Description
student_id integer The unique identifier for the student.
parent_display_name string Full name of the student's parent.
priority integer, nullable
 Parent's communication policy.
email_address string Parent's email address.
home_telephone string Parent's home telephone number.
main_telephone string Parent's main telephone number.
mobile string Parent's mobile telephone number.
is_main_email_address_for_contact boolean, nullable
 States whether a parent would like to be contacted via email.
student_contact_mis_id string
 The identifier for the contact from an external MIS.

Reports

GET Reports

You need the Attainment-Student Reports (students.attainment.reports.read) permission to view this endpoint.

Returns details of available progress reports in the chosen academic year, including the grades and attributes associated with each set of reports.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/attainment/reports
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "id": 123456,
			        "name": "Year 9 End of Year Report",
			        "year_group": "9",
			        "enable_comments": false,
			        "prepared_at": "2020-01-01T00:00:00Z",
			        "preferred_target_grade_type": 1,
			        "preferred_progress_grade_type": 2,
			        "presentation_name": "Year 9 Report",
			        "presentation_date": "2019-01-31T00:00:00Z",
			        "grades": [
			            {
			                "type": 3,
			                "name": "External Target Grade",
			                "description": "Excellent progress grade.",
			            },
			            ...
			        ],
			        "attributes_and_choices": [
			            {
			                "id": 4,
			                "name": "Attitude to learning",
			                "description": "Students attitude to their learning in this subject",
			                "display_name": "Attitude to Learning",
			                "choices": [
			                    {
			                        "id": 123456,
			                        "name": "Excellent",
			                        "points": 5
			                        "details": "Consistently engaged and committed."
			                    },
			                    ...
			                 ],
			            },
			            ...
			        ]
			    },
			    ...
			]

Reports Object

Name Type Description
id integer The unique identifier for the report.
name string The name of the report.
year_group string The year group that is associated with the report.
enable_comments boolean States whether the report should have comments added.
prepared_at datetime, nullable
 The date and time when the report was prepared for publication.
preferred_target_grade_type integer, nullable The grade type chosen as preferred target grade.
preferred_progress_grade_type integer, nullable The grade type chosen as preferred progress grade.
presentation_name string, nullable The name presented on the report.
presentation_date datetime, nullable The date presented on the report.
grades array Array of grades types associated with the report at point of publication.
| type integer The type of grade. One of the 10 grade types that can be configured in GO.
| name string, nullable School name of the grade at point of publication.
| description string, nullable Description of the grade at point of publication.
attributes_and_choices array Array of attributes and the available choices for the report at point of publication.
| id integer The unique identifier for the attribute.
| name string The name of the attribute.
| description string The description of the attribute.
| display_name string The display name of the attribute.
| choices array Array of the choices for an attribute.
| id integer The unique identifier for the choice.
| name string The name of the choice.
| points integer The point value for the choice.
| details integer Descirption of the attibute choice.

GET Report Attributes

You need the Attainment-Student Reports (students.attainment.reports.read) permission to view this endpoint.

Returns the attributes for students for the chosen report.

• Use GET Reports to find the name and points value for an attribute choice for the student.

Route parameters

Name Type Description
academicYear integer academic year for the requested data
reportId integer report id for the requested data

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/attainment/reports/{reportId}/attributes
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "subject_id": 222222,
			        "choices": [
			            {
			                "choice_id": 123456,
			                "student_id": 987654
			            },
			            ...
			        ]
			    }
			    ...
			]

Report Attributes Object

Name Type Description
subject_id integer The unique identifier for the subject.
choices array Array of student and chosen attribute for the report.
| choice_id integer The unique identifier for the attribute choice.
| student_id integer The unique identifier for the student.

GET Report Grades

You need the Attainment-Student Reports (students.attainment.reports.read) permission to view this endpoint.

Returns the subjects and student grade values for a chosen report.

• Use GET Reports to determine the report name and the name of the grade types.

• Use GET Students to match to student personal details.

• Use GET Subjects to find the subject details.

Route parameters

Name Type Description
academicYear integer academic year for the requested data
reportId integer report id for the requested data

Query parameters

Name Type Description Required Default
applyTakeHomeReportExclusions boolean Whether students/subjects excluded from the report are removed from the response no true

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/attainment/reports/{reportId}/grades
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "subject_id": 222222,
			        "qan": "601/8575/2",
			        "qualification_title": "AQA Level 1/Level 2 GCSE (9-1) in Drama",
			        "grades": [
			            {
			                "type": 1,
			                "name": "1",
			                "student_id": 987654
			            },
			            ...
			        ]
			    },
			    ...
			]

Report Grades Object

Name Type Description
subject_id integer The unique identifier for the subject.
qan string, nullable The qualification accreditation number.
qualification_title string, nullable The name of the qualification.
grades array An array of student and grades captured in the report.
| type integer The type of grade. One of the 10 grade types that can be configured in GO.
| name string, nullable The name of the grade.
| student_id integer The unique identifier for the student.

GET Report Comments

You need the Attainment-Student Report Comments (students.attainment.reports.comments.read) permission to view this endpoint.

Returns the comments entered by teachers for the chosen report. The report must have been prepared for publication for data to be returned.

• Use GET Reports to determine the report name and the name of the grade types.

• Use GET Students to match to student personal details.

• Use GET Subjects to find the subject details.

Route parameters

Name Type Description
academicYear integer academic year for the requested data
reportId integer report id for the requested data

Query parameters

Name Type Description Required
cursor integer used to request further data when has_more is true no

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/attainment/reports/{reportId}/comments
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "report_comments": [
			        {
			            "subject_id": 222222,
			            "student_id": 987654,
			            "author": "Ms M Jones"
			            "details": "You produce accurate writing which is clear and relevant. Remember to meet deadlines."
			        },
			        ...
			    ],
			    "has_more": true,
			    "cursor": 123
			}

Report Comments Object

Name Type Description
report_comments array Array of report comment details
| subject_id integer The unique identifier for the subject.
| student_id integer The unique identifier for the student.
| author string, nullable The author of the comment.
| details string The comment entered by the author.
has_more boolean Boolean representing if there are more results.
cursor integer, nullable Used to request further data when has_more is true.

Schools

GET Schools

You need the General-School (school.read) permission to view this endpoint.

Returns details of the school and the available academic years.

Request


			curl https://api.go4schools.com/customer/v1/school
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "code": "DEMO",
			    "name": "Demo School",
			    "academic_years": [
			        2019,
			        ...
			    ],
			    "current_academic_year": 2019
			}

Schools Object

Name Type Description
code string Schools unique code.
name string The name of the school.
academic_years integer array Array of academic years in a school.
current_academic_year integer The current academic year of a school.

Students

GET Students

You need the Student-Students (students.read) permission to view this endpoint.

Returns the current personal details of the students that were at school in the chosen academic year.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/students
				-H  "Authorization: Bearer {ApiKey}"

Response

Non-MIS Schools: 200 OK


			[
			    {
			        "id": 987654,
			        "date_of_birth": "2005-01-31T00:00:00Z",
			        "sex": "M",
			        "legal_first_name": "Robert",
			        "legal_last_name": "Smith",
			        "preferred_first_name": "Bob",
			        "preferred_last_name": "Smith",
			        "middle_names": "Jon",
			        "student_mis_id": "12345"
			
			    },
			    ...
			]

MIS Schools: 200 OK


			[
			    {
			        "id": 987654,
			        "date_of_birth": "2005-01-31T00:00:00Z",
			        "sex": "M",
			        "legal_first_name": "Robert",
			        "legal_last_name": "Smith",
			        "preferred_first_name": "Bob",
			        "preferred_last_name": "Smith",
			        "middle_names": "Jon"
	
			    },
			    ...
			]

Students Object

Name Type Description
id integer The unique identifier for the student.
date_of_birth datetime The date of birth for the student.
sex string The gender of the student.
legal_first_name string The legal forename of the student.
legal_last_name string The legal last name od the student.
preferred_first_name string The preferred forename of the student.
preferred_last_name string The preferred last name of the student.
middle_names string Any middle names of the student.
student_mis_id string The identifier for the student from an external MIS.

GET General Attributes

You need the Students-Attributes (students.attributes.read) permission to view this endpoint.

Returns general student attributes for the chosen academic year. This will include all custom attributes and also system attributes not returned by other endpoints.

• Use GET Students to match to student personal details.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Query parameters

Name Type Description Required
cursor integer used to request further data when has_more is true no

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/students/attributes
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "students_and_attributes": [
			        {
			            "id": 123456,
			            "code": "admissionDate",
			            "name": "Admission date",
			            "is_system": true,
			            "students_and_attribute_values": [
			                {
			                    "student_id": 987654,
			                    "value": "01/01/2020 00:00:00"
			                    "academic_year": 2019
			                    "date": "2019-01-31T00:00:00Z"
			                },
			                ...
			            ]
			         },
			         ...
			    ],
			    "has_more": true,
			    "cursor": 123
			}

General Attributes Object

Name Type Description
students_and_attributes array Array of all students and their attribute values.
| id integer The unique identifier for the attribute.
| code string Attribute code.
| name string Attribute name.
| is_system boolean If the attribute is a system attribute (whether the attribute has been retrieved from the MIS).
| students_and_attribute_values array Array of student values for the particular attribute.
| student_id integer Unique identifier for the student.
| value string Value recorded for this attribute and student.
| academic_year string, nullable
 Only populated if this value was timestamped against the requested academic year.
| date string, nullable
 Dated timestamp.
has_more boolean Boolean representing if there are more results.
cursor integer, nullable Used to request further data when has_more is true.

GET Demographic Attributes

You need the Students-Attributes(demographic) (students.attributes.demographic.read) permission to view this endpoint.

Returns the following attributes for students for the chosen academic year: Country of birth, Home Language, First Language and Nationality.

• Use GET Students to match to student personal details.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Query parameters

Name Type Description Required
cursor integer used to request further data when has_more is true no

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/students/attributes/demographic
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "students_and_attributes": [
			        {
			            "id": 123456,
			            "code": "countryOfBirth",
			            "name": "Country of Birth",
			            "is_system": true,
			            "students_and_attribute_values": [
			                {
			                    "student_id": 987654,
			                    "value": "United Kingdom",
			                    "academic_year": 2019
			                    "date": "2019-01-31T00:00:00Z"
			                },
			                ...
			            ]
			         },
			         ...
			    ],
			    "has_more": true,
			    "cursor": 123
			}

Demographic Attributes Object

Name Type Description
students_and_attributes array Array of all students and their attribute values.
| id integer The unique identifier for the attribute.
| code string Attribute code.
| name string Attribute name.
| is_system boolean If the attribute is a system attribute (whether the attribute has been retrieved from the MIS).
| students_and_attribute_values array Array of student values for the particular attribute.
| student_id integer Unique identifier for the student.
| value string Value recorded for this attribute and student.
| academic_year string, nullable
 Only populated if this value was timestamped against the requested academic year.
| date string, nullable
 Dated timestamp.
has_more boolean Boolean representing if there are more results.
cursor integer, nullable Used to request further data when has_more is true.

GET SEND Attributes

You need the Students-Attributes(SEND) (students.attributes.send.read) permission to view this endpoint.

Returns the following attributes for students for the chosen academic year: Sen Code, Sen Status, Educational Needs, Gifted/Talented, Gifted/Talented Subject.

• Use GET Students to match to student personal details.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Query parameters

Name Type Description Required
cursor integer used to request further data when has_more is true no

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/students/attributes/send
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "students_and_attributes": [
			        {
			            "id": 1,
			            "code": "senNeed",
			            "name": "Educational needs",
			            "is_system": false,
			            "students_and_attribute_values": [
			                {
			                    "student_id": 987654,
			                    "value": "Learning Difficulty Level 1",
			                    "academic_year": 2019
			                    "date": nullable
			                },
			                ...
			            ]
			         },
			         ...
			    ],
			    "has_more": true,
			    "cursor": 100
			}

SEND Attributes Object

Name Type Description
students_and_attributes array Array of all students and their attribute values.
| id integer The unique identifier for the attribute.
| code string Attribute code.
| name string Attribute name.
| is_system boolean If the attribute is a system attribute (whether the attribute has been retrieved from the MIS).
| students_and_attribute_values array Array of student values for the particular attribute.
| student_id integer Unique identifier for the student.
| value string Value recorded for this attribute and student.
| academic_year string, nullable
 Only populated if this value was timestamped against the requested academic year.
| date string, nullable
 Dated timestamp.
has_more boolean Boolean representing if there are more results.
cursor integer, nullable Used to request further data when has_more is true.

GET Sensitive Attributes

You need the Students-Attributes(sensitive) (students.attributes.sensitive.read) permission to view this endpoint.

Returns the following attributes for students for the chosen academic year: FSM, FSMEver6, EAL, Disadvantaged, Ethnicity, Ethnicity code, Ever In Care, Looked after, Pupil Premium Indicator, Service Child, Traveller type.

• Use GET Students to match to student personal details.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Query parameters

Name Type Description Required
cursor integer used to request further data when has_more is true no

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/students/attributes/sensitive
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "students_and_attributes": [
			        {
			            "id": 1,
			            "code": "ethnicity",
			            "name": "Ethnicity",
			            "is_system": false,
			            "students_and_attribute_values": [
			                {
			                    "student_id": 987654,
			                    "value": "Any other White background",
			                    "academic_year": 2019
			                    "date": nullable
			                },
			                ...
			            ]
			         },
			         ...
			    ],
			    "has_more": true,
			    "cursor": 100
			}

Sensitive Attributes Object

Name Type Description
students_and_attributes array Array of all students and their attribute values.
| id integer The unique identifier for the attribute.
| code string Attribute code.
| name string Attribute name.
| is_system boolean If the attribute is a system attribute (whether the attribute has been retrieved from the MIS).
| students_and_attribute_values array Array of student values for the particular attribute.
| student_id integer Unique identifier for the student.
| value string Value recorded for this attribute and student.
| academic_year string, nullable
 Only populated if this value was timestamped against the requested academic year.
| date string, nullable
 Dated timestamp.
has_more boolean Boolean representing if there are more results.
cursor integer, nullable Used to request further data when has_more is true.

GET Education Details

You need the Students-Education Details (students.education.read) permission to view this endpoint.

Returns education details for students.

• Use GET Students to match to student personal details.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Query parameters

Name Type Description Required
cursor integer used to request further data when has_more is true no

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/students/education-details
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "students_and_education_details": [
			        {
			            "student_id": 987654,
			            "upn": "Z0123456789012",
			            "former_upn": "Z0123456789011",
			            "national_curriculum_year": "11",
			            "registration_group": "11East",
			            "house": "Newton",
			            "admission_date": "2017-01-31T00:00:00Z",
			            "deleted_from_source": true,
			            "leaving_date": "2019-01-31T00:00:00Z",
			            "student_education_attributes": [
			                {
			                    "attribute_id": 123456,
			                    "code": "proficiencyInEnglish",
			                    "name": "Proficiency in English",
			                    "is_system": true,
			                    "attribute_values": [
			                       {
			                           "value": "D - Competent",
			                           "academic_year": 2019,
			                           "date": "2019-01-31T00:00:00Z",
			                       },
			                       ...
			                     ]
			                },
			                ...
			            ]
			         },
			         ...
			    ],
			    "has_more": true,
			    "cursor": 123
			}

Education Details Object

Name Type Description
students_and_education_details array Array of student education details.
| student_id integer The unique identifier for the student.
| upn string Unique pupil number for the student.
| former_upn string The former UPN for the student.
| national_curriculum_year string The year group of the student.
| registration_group string The registration group of the student.
| house string The students house.
| admission_date datetime The admission date of the student.
| deleted_from_source boolean The leaver status of the student.
| leaving_date datetime The leaving date of the student.
| student_education_attributes array The array of educational attributes for this student.
| attribute_id integer The unique identifier for the attribute.
| code string The code for the attribute.
| name string The name for the attribute.
| is_system boolean If the attribute is a system attribute (whether the attribute has been retrieved from the MIS).
| attribute_values array The array of educational attribute values for this student.
| value string The actual attribute value recorded at this time for this student.
| academic_year string, nullable Only populated if this value was timestamped against the requested academic year.
| date string, nullable Populated with the dated timestamp of the attribute regardless of academic year.
has_more boolean Boolean representing if there are more results.
cursor integer, nullable Used to request further data when has_more is true.

GET Photos

You need the Students-Photos (students.photos.read) permission to view this endpoint.

Returns student photos.

• Use GET Students to match to student personal details.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Query parameters

Name Type Description Required
cursor integer used to request further data when has_more is true no

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/students/photos
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "students_and_photos": [
			        {
			            "student_id": 987654,
			            "photo": "data:image/jpeg;base64,..."
			        },
			        ...
			    ],
			    "has_more": true,
			    "cursor": 123
			}

Photos Object

Name Type Description
students_and_photos array Array of all students and photos.
student_id integer The unique identifier for the student.
photo string Base 64 encoded string.
has_more boolean Boolean representing if there are more results.
cursor integer, nullable Used to request further data when has_more is true.

GET Medical Conditions

You need the Students-Attributes (medical) (students.medical.read) permission to view this endpoint.

Returns medical conditions for students.

• Use GET Students to resolve to students personal details.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Query parameters

Name Type Description Required
cursor integer used to request further data when has_more is true no

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/students/medical-conditions
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "students_and_medical_conditions": [
			        {
			            "student_id": 987654,
			            "medical_conditions": "Other Allergies; Other Medical"
			        },
			        ...
			    ],
			    "has_more": true,
			    "cursor": 123
			}

Medical Conditions Object

Name Type Description
student_id integer The unique identifier for the student.
| medical_details string Medical conditions taken from the schools MIS.
| has_more boolean Boolean representing if there are more results.
cursor integer, nullable Used to request further data when has_more is true.

Teaching

GET Departments

You need the Teaching-Curriculum (school.curriculum.read) permission to view this endpoint.

Returns details of departments in the chosen academic year.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/teaching/departments
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "id": 222111,
			        "name": "Computing"
			    },
			    ...
			]

Departments Object

Name Type Description
id integer The unique identifier for the department.
name string Department name.

GET Subjects

You need the Teaching-Curriculum (school.curriculum.read) permission to view this endpoint.

Returns all subjects in the academic year.

• Use GET Departments to resolve to department details.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/teaching/subjects
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "id": 222222,
			        "name": "Computing and ICT",
			        "code": "Cp",
			        "year_group": "10",
			        "department_id": 123456,
			        "qan": "601/8355/X",
			        "qualification_title": "OCR Level 1/Level 2 GCSE (9-1) in Computer Science",
			        "qualification_scheme_name": "Fine GCSE grades, e.g. 9+, 9, 9-, 8+, 8, 8- etc",
			        "include_in_stats": true
			    },
			    ...
			]

Subjects Object

Name Type Description
id integer The unique identifier for the subject.
name string The name of the subject.
code string The code of the subject.
year_group string The year group of the subject.
department_id integer The department that the subject belongs to.
qan string The Qualification Accreditation Number associated with the subject.
qualification_title string The qualification title associated with the subject.
qualification_scheme_name string, nullable The scheme name of the subject.
include_in_stats boolean Whether the subject is included in the year group statistics.

GET Teachers

You need the Teaching-Teachers (school.teachers.read) permission to view this endpoint.

Returns details of the teachers in the chosen academic year.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/teaching/teachers
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "id": 123456,
			        "title": "Mrs",
			        "first_name": "Anne",
			        "last_name": "Burgess",
			        "preferred_first_name": "Anne",
			        "preferred_last_name": "Burgess",
			        "initials": "AXB",
			        "code": "AXB"
			    },
			    ...
			]

Teachers Object

Name Type Description
id integer The unique identifier for the teacher.
title string The title associated with the teacher.
first_name string The forename of the teacher.
last_name string The surnane of the teacher.
preferred_first_name string Preferred forename of the teacher.
preferred_last_name string Preferred surname of the teacher.
initials string The initials of the teacher.
code string The code associated with the teacher.

GET Groups

You need the Teaching-Curriculum (school.curriculum.read) permission to view this endpoint.

Returns details of teaching groups for each subject in the chosen academic year.

• Use GET Subjects to resolve to the subject details.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/teaching/groups
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "id": 123456,
			        "name": "9/Bu1",
			        "code": "9/Bu1",
			        "subject_id": 222222
			    },
			    ...
			]

Groups Object

Name Type Description
id integer The unique identifier for the group.
name string The name of the group.
code string The code of the group.
subject_id integer The subject that the group belongs to.

GET Groups and Students

You need the Teaching-Curriculum (school.curriculum.read) permission to view this endpoint.

Returns details of the students in each teaching group in the chosen academic year.

• Use GET Groups to resolve the group details.

• Use GET Students to find student personal details.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/teaching/groups/students
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "group_id": 123456,
			        "student_ids": [
			            123456,
			            ...
			        ]
			    },
			    ...
			]

Groups and Students Object

Name Type Description
group_id integer The unique identifier for the group.
student_ids integer array Array of student identifiers associated with this group.

GET Groups and Teachers

You need the Teaching-Curriculum (school.curriculum.read) permission to view this endpoint.

Returns details of teachers assigned to each teaching group in the chosen academic year.

• Use GET Groups to resolve the group details.

• Use GET Teachers to find the teacher details.

Route parameters

Name Type Description
academicYear integer academic year for the requested data

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/teaching/groups/teachers
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "group_id": 123456,
			        "teacher_ids": [
			            123456,
			            ...
			        ]
			    },
			    ...
			]

Groups and Teachers Object

Name Type Description
group_id integer The unique identifier for the group.
teacher_ids integer array Array of teacher identifiers for this group.

Timetables

GET Timetables

You need the Timetable-School Timetable (school.timetable.read) permission to view this endpoint.

Returns details of the timetables and their associated periods for the chosen academic year.

Route parameters

Name Type Description
academicYear integer academic year for the requested classes

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/timetables
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "id": 123456,
			        "periods": [
			            {
			                "id": 123456,
			                "name": "Monday Tutorial",
			                "display_name": "Tutorial",
			                "week": 1,
			                "day_of_week": "Monday",
			                "start": "2020-01-01T00:00:00Z",
			                "end": "2020-01-01T00:00:00Z"
			            },
			            ...
			        ]
			    },
			    ...
			]

Timetables Object

Name Type Description
id integer The unique identifier for the timetable.
periods array Array of period information.
| id integer Unique identifier for the period associated with this timetable.
| name string The name of the period.
| display_name string The display name of the period.
| week integer The week the period belongs to. Values can be 1 or 2.
| day_of_week string The name of the day of the week the period falls on.
| start datetime The time the period begins.
| end datetime The time the period ends.

GET Calendar

You need the Timetable-School Timetable (school.timetable.read) permission to view this endpoint.

Returns details of when the school is open, closed or open for staff training only in the chosen academic year.

• Use GET Timetables to link the date to the week number and school periods.

Route parameters

Name Type Description
academicYear integer academic year for the requested classes

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/timetables/calendar
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "timetable_id": 123456,
			        "week": 1,
			        "date": "2020-01-31T00:00:00Z",
			        "day_type_code": "TRAINING"
			    },
			    ...
			]

Calendars Object

Name Type Description
timetable_id integer, nullable The unique identifier for the timetable.
week integer, nullable The week the calendar is in. Values 1 or 2.
date datetime The date of the calendar day.
day_type_code string The type of day the calendar day is. One of 'Open', 'Closed', 'Training', 'Unknown'. 'Unknown' is used when GO has not received data in its feed for a date.

GET Classes

You need the Timetable-School Timetable (school.timetable.read) permission to view this endpoint.

Returns details of all timetabled classes in the chosen academic year.

• Use GET Timetables to determine week number and period details from the period identifier.

• Use GET Teachers to link to teacher details

Route parameters

Name Type Description
academicYear integer academic year for the requested classes

Query parameters

Name Type Description Required
cursor integer used to request further data when has_more is true no

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/timetables/classes
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "classes": [
			        {
			            "id": 123456,
			            "year_group": "7",
			            "subject_code": "As",
			            "group_code": "7/As1",
			            "period_id": 123456,
			            "rooms": [
			                "H4",
			                ...
			            ],
			            "teacher_ids": [
			                123456,
			                ...
			            ]
			        },
			        ...
			    ],
			    "has_more": true,
			    "cursor": 123
			}

Classes Object

Name Type Description
classes array Array of class details.
| id integer The unique identifier for the class.
| year_group string The year group associated with the class.
| subject_code string The subject code associated with the class.
| group_code integer The group code associated with the class.
| period_id integer The unique identifier for the period assigned to the class.
| rooms string array An array of room names.
| teacher_ids integer array An array of teacher ids.
has_more boolean Boolean representing if there are more results.
cursor integer, nullable Used to request further data when has_more is true.

GET Student Classes

You need the Timetable-Student Timetables (students.timetable.read) permission to view this endpoint.

Returns details of which students are linked to which timetabled classes in the chosen academic year.

• Use GET Classes to find class details.

• Use GET Students to get the student personal details.

Route parameters

Name Type Description
academicYear integer academic year for the requested classes

Query parameters

Name Type Description Required
cursor integer used to request further data when has_more is true no

Request


			curl https://api.go4schools.com/customer/v1/academic-years/{academicYear}/timetables/student-classes
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			{
			    "student_classes": [
			        {
			            "student_id": 987654,
			            "classes": [
			                {
			                    "id": 123456,
			                    "start": "2020-01-01T00:00:00Z",
			                    "end": "2020-01-01T00:00:00Z",
			                },
			                ...
			            ]
			        },
			        ...
			    ],
			    "has_more": true,
			    "cursor": 123
			}

Student Classes Object

Name Type Description
student_classes array Array of students and their classes.
| student_id integer The unique identifier for the student.
| classes array Array of classes the student has.
| id integer The unique identifier for the class.
| start datetime The start time of the class.
| end datetime, nullable The end time of the class.
has_more boolean Boolean representing if there are more results.
cursor integer, nullable Used to request further data when has_more is true.

User Accounts

GET Parents

You need the Users-Parent Accounts (school.accounts.parents.read) permission to view this endpoint.

Returns details of parent user accounts.

Request


			curl https://api.go4schools.com/customer/v1/users/parents
				-H  "Authorization: Bearer {ApiKey}"

Response

200 OK


			[
			    {
			        "email_address": "steve.thomas@example.com",
			        "display_name": "Mr Stephen Thomas",
			        "student_id": 987654
			    },
			    ...
			]

User Parents Object

Name Type Description
email_address string The email address for the parent account.
display_name string The display name of the parent.
student_id integer The unique identifier for the student associated with this parent.

GET Staff

You need the Users-Staff Accounts (school.accounts.staff.read) permission to view this endpoint.

Returns details of staff user accounts.

Request


			curl https://api.go4schools.com/customer/v1/users/staff
				-H  "Authorization: Bearer {ApiKey}"

Response

Non-MIS Schools: 200 OK


				[
				    {
				        "id": 1,
				        "email_address": "sandra.jones@example.com",
				        "first_name": "Sandra",
				        "last_name": "Jones",
				        "display_name": "Mrs S Jones",
				        "title": "Mrs",
				        "is_current": true,
				        "teacher_id": 1,
				        "start_date": null,
				        "end_date": null
				
				    },
				    ...
				]

MIS Schools: 200 OK


				[
				    {
				        "id": 1,
				        "email_address": "sandra.jones@example.com",
				        "legal_first_name": "Sandra",
				        "legal_last_name": "Jones",
				        "preferred_first_name": "Sandra",
				        "preferred_last_name": "Jones",
				        "display_name": "Mrs S Jones",
				        "title": "Mrs",
				        "is_current": true,
				        "teacher_id": 1,
				        "start_date": 2021-09-01T00:00:00Z,
				        "end_date": 2022-08-31T00:00:00Z,
				
				    },
				    ...
				]

User Staff Object

Name Type Description
id integer The unique identifier for the staff member.
email_address string, nullable The email address for the staff member.
first_name (non-MIS Only) string The forename of the staff member.
last_name (non-MIS Only) string The surname of the staff member.
legal_first_name (MIS Only) string The legal first name of the staff member.
legal_last_name (MIS Only) string The legal surname of the staff member.
preferred_first_name (MIS Only) string The preferred first name of the staff member.
preferred_last_name (MIS Only) string The preferred surname of the staff member.
display_name string, nullable for MIS only The display name of the staff member.
title string, nullable The title of the staff member.
is_current boolean The current status of the staff member.
teacher_id integer, nullable The corresponding teacher unique identifier if the staff member is a teacher.
start_date datetime, nullable The start date for the teacher (non-null value for MIS schools only).
end_date datetime, nullable The contract end date for the teacher (non-null value for MIS schools only).