This is a new service - your feedback (opens in a new tab) will help us to improve it.

  1. Home
  2. APIs
  3. FMSSubmissionAPI_V1

FMS Submission API

Lifecycle stageLive
Open API fileView Open API file
GuidelineDownload guideline
Supported Authorisation types
  • User-Restricted
  1. Overview
  2. Versioning
  3. API browser and swagger file
  4. Authentication
  5. Consent process
  6. HTTP status codes
  7. API error codes
  8. Rate Limiting
  9. Endpoints


This API is designed to support Academy Trusts with completion of financial returns to DfE. This is normally done using an online form allowing the trust user to fill in the details and get immediate feedback of any issues. By using this API, the trust can transfer much of the information directly from their finance software saving time and helping to ensure better accuracy.

The API described within this document is used on the first stage allowing trusts to transfer a set of data across to the online form staging area. Once received, the trust preparer can choose whether or not to use the data to pre-populate the online form.

For more information about how to develop your own client applications, including example clients for this API, see Tutorials. Please download the API Guide for all details.


When an API changes, we will strive to make backwards compatible changes were possible. When this is not possible, we will provide a notice on deprecated endpoints and make a new endpoint available.

API browser and swagger file

For more detailed schema information on the DfE Submission API , you can:

  • Open an API browser like Swagger Editor
  • Copy the swagger file content in to the Swagger Editor
  • You can also generate a client library from the swagger file using Swagger Editor
  • This project uses the OpenAPI 3.0 specification so Swagger tools used need to support this specification.


To be able to access the DfE Submission API you need to be authenticated. If you don’t already have a developer hub account you will need to create one. Please refer to the ‘overview’ link within the top navigation of the developer hub for details on how to set up authentication for your organisation. The submission api is an application-restricted endpoint see the developer hub documentation for details.

Access to the DfE Submission API does utilise a consent process.

It is important to recognise that trusts retain ownership of this data so as a pre-requisite to calling the API, we ask that trusts approve the transfer of this data. The end user provides consent to connect with the Department for Education (DfE) without sharing their access credentials. The end user who intends to provide that consent must have the specific role of ‘Data Transfer Approver (DTA)’ assigned in the DfE ‘IDAMS’ identity management service.

We use the open standard OAuth 2.0 for API authorisation. You will need to implement the authorisation user journey listed in the api guide in order to receive the OAuth 2.0 access token. Please download the API Guide.

You will need to use the access token and subscription key to call the Financial Return Submission API.

HTTP status codes

The DfE Submission API uses standard HTTP response code conventions:

  • 100 codes are informational
  • 200 codes indicate success
  • 300 codes indicate a redirection
  • 400 codes indicate a client-side error
  • 500 codes indicate a server-side error

Common status codes are:

HTTP Status codeMessageComments
200OKThis status code indicates that the request has been processed successfully
204DeletedSubmission deleted successfully.
400Bad RequestThis status code indicates that the incoming request body or parameters do not conform with the OpenAPI/Swagger document which describes the API, This error code could also include specific message to indicate the problem in the requested payload .
401Unauthorised This status code indicates authentication or authorisation error. This could be sent due to various reason such as missing JWT header, Invalid claims, Invalid subscription key etc. For security reasons, error responses for this status code will not include reason.
403Forbidden request Forbidden request (Examples include API request to delete a Submission which doesn’t belong to the Academy Trust)
404Submission not found Submission not found (Submission doesn’t exist for the Submission ID)
503Service UnavailableThe API is temporarily unavailable because it is overloaded or down for maintenance. Please wait for a short time and try again.
504Gateway TimeoutThis status code indicates that there is a network connection problem within the layers of the API fulfillment stack

API error codes

There are specific API error codes for the DfE Submission API. We are using http status code to indicate a successful call to API or any failure. In case of validation failure or malformed payload HTTP error code 400 .

Please see the API Guide for details of validation errors that may be returned on when a submission is made with a valid URN but with data element(s) that contain errors. .

Rate Limiting

We have introduced limits on API usage rates in terms of requests per minute.

If you exceed this limit, you will receive a 429 Too Many Requests HTTP status code for each request made within the remainder of the time.

Per minute, you can make:

  • Up to 500 requests per endpoint for the same API client/IP address.

Rate limiting threshold is subject to change based on the further engagement with API client developer.