Skip to main content

Register API documentation

This is API documentation for the Department for Education (DfE)’s Register trainee teachers (Register) service.

The Register API is replacing the HESA service for teacher trainees from the 2025/26 collection cycle. All vendors of student record systems (SRS) and some training providers will need to make changes to integrate with Register.

What this API is for

The Register API allows providers to import trainee records from their student record systems and to keep those records synchronised as they are modified.

Providers can use the API for:

  • looking up a trainee record in Register and returning details about that trainee.
  • retrieving a list of trainee records in Register for a given academic year.
  • creating new trainee records.
  • updating individual trainee records.
  • withdrawing and deferring a trainee.

How do I connect to this API?

Authentication and authorisation

Requests to the API must be accompanied by an authentication token.

Each token is associated with a single provider. It will grant access to trainee records registered by that provider. You can get a token by writing to registertraineeteachers@education.gov.uk.

For instructions on how to authenticate see the API reference.

Design principles

Trainee identifiers

Trainees are identified in the API by an internally generated unique id value. The API uses the id to specify a particular trainee record. For example, the API endpoint that updates a single trainee record requires that id value as part of its URL.

For example, the following request updates the trainee record identified by id value gQGecNYwLCqPMTgzW7N2bURi.

PUT https://www.register-trainee-teachers.service.gov.uk/api/v1.0-pre/trainees/gQGecNYwLCqPMTgzW7N2bURi

You can obtain id values from the following request which returns the list of trainees for the current provider:

GET https://www.register-trainee-teachers.service.gov.uk/api/v1.0-pre/trainees

Alternatively an id value is given as part of the response to a request to create a new trainee record:

POST https://www.register-trainee-teachers.service.gov.uk/api/v1.0-pre/trainees

Reference data and data encoding

Trainee records have a number of attributes that refer to reference data of various sorts. For example, we record the nationality of trainees.

This section provides guidance on how those attributes are serialised in the requests and responses processed by the API.

Dates

All dates and datetimes in the API specification are intended to be ISO 8601 compliant.

Nationalities

Nationality is expressed as an ISO 3166-2 country code.

Degrees

A list of valid values for the subject, degree type, institution and grade attributes can be obtained from the reference data endpoint. Details are provided in the API reference.

Placements

Placement schools are identified by their URN (unique reference number).

API versioning strategy

When we provide new features through the API, we sometimes make changes that require you to update student record systems.

We give a new number to the new version of the API. The change of version number shows whether we’ve made breaking or non-breaking changes to the API.

Breaking changes

Breaking changes usually involve modifying or deleting parts of the API, such as:

  • removing features
  • removing fields
  • changing the behaviour of endpoints, for example requiring a new parameter in order for data to be synced

You must update student record systems before you move to a new version with breaking changes.

Non-breaking changes

When we make non-breaking changes the API remains ‘backward compatible’. This means that the changes do not affect the existing functionality of the API.

Non-breaking changes include adding new:

  • endpoints, for example to allow a new action to be performed on a trainee record
  • nested resources and objects, for example details of a trainee’s placements
  • fields, for example when a reason for a deferral is added
  • optional query parameters, for example to allow optional pagination when data is synced

You do not need to update student record systems before moving to a new version with non-breaking changes. You only need to make updates if you want to use the version’s new features.

How the API version number reflects the changes we’ve made

We use an academic-year-based Calendar Versioning (CalVer variant).

The format is YYYY.MAJOR (for example, 2025.1) where YYYY is the year that the version enters production and MAJOR is the major version number.

MAJOR will increment for breaking changes. Non-breaking changes are included within the current version.

Pre-release versions are suffixed with -pre and release candidate versions (no changes expected before go-live) are suffixed with -rc.

Changes are documented in our release notes.

Using the correct version of the API

When an API version is released, version updates will be made available on their own version URL.

For example, after version 2025.2 is released you can use:

Testing

To get familiar with our system and perform testing, you can use our sandbox environment.

You will need an authentication token for the sandbox environment. These will be provided by the Register team.