Register API reference

This API allows you to access information about trainees and provides endpoints to update and create trainee data.

Contents

API versioning strategy

Find out about how we make updates to the API, including:

  • the difference between breaking and non-breaking changes
  • how the API version number reflects changes
  • using the correct version of the API

Draft version 0.1

Version 0.1 is a draft version of the API. It was released on 22 April 2024.

It is designed for testing and feedback purposes only.

It will have some seed data to help you test the API.

It will only be available on the sandbox environment.

Developing on the API

Reference spreadsheet

You can use the Register API reference spreadsheet to map trainee data from your student record system into the Register service via the Register API.

Register API reference spreadsheet contains the following information:

  • field requirement
  • entity
  • description
  • whether a field is optional or mandatory
  • whether it allows multiple values
  • minimum and maximum instances
  • character length
  • format rules
  • HESA data type, alignment, code examples, labels, link to their data reference webpage and confirmation if the HESA validation is applicable

You must only use the reference spreadsheet v0.1 for use in testing and feedback of API v0.1 within the sandbox environment.

Download Register API reference spreadsheet v0.1 (Excel)

OpenAPI

The OpenAPI spec for this API is available in YAML format.

Authentication

All requests must be accompanied by an Authorization request header (not as part of the URL) in the following format:

Authorization: Bearer {token}

Unauthenticated requests will receive an UnauthorizedResponse with a 401 status code.

Authentication tokens will be provided by the Register team.

Endpoints

GET /info

Provides general information about the API.

Request

GET /api/v0.1/info

Possible responses

HTTP 200 - Information about the API status 
    {
      "status": "ok"
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }

GET /trainees

Get many trainees.

Note that this endpoint always returns the trainees for a single academic cycle. If no academic cycle parameter is specified we return trainees in the current academic cycle.

Request

GET /api/v0.1/trainees

Parameters

Parameter In Type Required Description
academic_cycle query string false The academic cycle year (default is the current academic cycle).
status query string false Include only trainees with a particular status. Valid values are course_not_yet_started, in_training, deferred, awarded, withdrawn
since query string false Include only trainees changed or created on or since a date and time. DateTimes should be in ISO 8601 format.
has_trn query boolean false Include only trainees with or without a trn
page query integer false Page number (defaults to 1, the first page).
per_page query integer false Number of records to return per page (default is 50)
sort_order query string false Sort in ascending or descending order. Valid values are asc or desc (default is desc)

Possible responses

HTTP 200 - An array of trainees 
    {
      "data": [
        {
          "trainee_id": "vcGjpBCn987jJSqMQxjhdv9Y",
          "provider_trainee_id": "abc1234",
          "first_names": "Trainee",
          "last_name": "TraineeUser644065",
          "date_of_birth": "2000-01-01",
          "created_at": "2023-10-20T14:54:47.374Z",
          "updated_at": "2024-01-24T16:03:28.721Z",
          "email": "trainee_644065@example.com",
          "middle_names": null,
          "training_route": "11",
          "sex": "10",
          "diversity_disclosure": "diversity_disclosed",
          "ethnic_group": "black_ethnic_group",
          "ethnic_background": "African",
          "additional_ethnic_background": null,
          "disability_disclosure": "no_disability",
          "course_subject_one": "100425",
          "itt_start_date": "2023-09-04",
          "outcome_date": null,
          "itt_end_date": "2023-10-17",
          "trn": "6440650",
          "submitted_for_trn_at": "2024-01-18T08:02:41.420Z",
          "state": "deferred",
          "withdraw_date": null,
          "withdraw_reasons_details": null,
          "defer_date": "2023-10-17",
          "recommended_for_award_at": null,
          "trainee_start_date": "2023-09-04",
          "reinstate_date": null,
          "course_min_age": 5,
          "course_max_age": 11,
          "course_subject_two": null,
          "course_subject_three": null,
          "awarded_at": null,
          "training_initiative": "009",
          "applying_for_bursary": false,
          "bursary_tier": null,
          "study_mode": "01",
          "ebacc": false,
          "region": null,
          "applying_for_scholarship": false,
          "course_education_phase": "primary",
          "applying_for_grant": false,
          "course_uuid": null,
          "lead_partner_not_applicable": false,
          "employing_school_not_applicable": false,
          "submission_ready": true,
          "commencement_status": null,
          "discarded_at": null,
          "created_from_dttp": false,
          "hesa_id": "87960005710008762",
          "additional_dttp_data": null,
          "created_from_hesa": false,
          "hesa_updated_at": null
          "record_source": "api",
          "iqts_country": null,
          "hesa_editable": true,
          "withdraw_reasons_dfe_details": null,
          "placement_detail": null,
          "ukprn": "10000571",
          "ethnicity": "120",
          "course_qualification": "QTS",
          "course_title": null,
          "course_level": "undergrad",
          "course_itt_start_date": "2022-09-01",
          "course_age_range": null,
          "expected_end_date": "2023-07-01",
          "employing_school_urn": null,
          "lead_partner_ukprn": null,
          "lead_partner_urn": null,
          "fund_code": "7",
          "bursary_level": "4",
          "course_year": "2",
          "funding_method": "4",
          "itt_aim": "201",
          "itt_qualification_aim": "004",
          "ni_number": null,
          "previous_last_name": null,
          "hesa_disabilities": null,
          "additional_training_initiative": null,
        }
      ]
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "No trainees found"
        }
      ]
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }
HTTP 422 - Unprocessable Entity 
    {
      "message": "Validation failed: 1 error prohibited this request being run",
      "errors": {
        "status": [
          "busy is not a valid status"
        ]
      }
    }

GET /trainees/{trainee_id}

Get a single trainee.

Request

GET /api/v0.1/trainees/{trainee_id}

Parameters

Parameter In Type Required Description
trainee_id path string true The unique ID of the trainee

Possible responses

HTTP 200 - A trainee 
    {
      "data": {
        "trainee_id": "vcGjpBCn987jJSqMQxjhdv9Y",
        "provider_trainee_id": "abc1234",
        "first_names": "Trainee",
        "last_name": "TraineeUser644065",
        "date_of_birth": "2000-01-01",
        "created_at": "2023-10-20T14:54:47.374Z",
        "updated_at": "2024-01-24T16:03:28.721Z",
        "email": "trainee_644065@example.com",
        "middle_names": null,
        "training_route": "11",
        "sex": "10",
        "diversity_disclosure": "diversity_disclosed",
        "ethnic_group": "black_ethnic_group",
        "ethnic_background": "African",
        "additional_ethnic_background": null,
        "disability_disclosure": "no_disability",
        "course_subject_one": "100425",
        "itt_start_date": "2023-09-04",
        "outcome_date": null,
        "itt_end_date": "2023-10-17",
        "trn": "6440650",
        "submitted_for_trn_at": "2024-01-18T08:02:41.420Z",
        "state": "deferred",
        "withdraw_date": null,
        "withdraw_reasons_details": null,
        "defer_date": "2023-10-17",
        "recommended_for_award_at": null,
        "trainee_start_date": "2023-09-04",
        "reinstate_date": null,
        "course_min_age": 5,
        "course_max_age": 11,
        "course_subject_two": null,
        "course_subject_three": null,
        "awarded_at": null,
        "training_initiative": "009",
        "applying_for_bursary": false,
        "bursary_tier": null,
        "study_mode": "01",
        "ebacc": false,
        "region": null,
        "applying_for_scholarship": false,
        "course_education_phase": "primary",
        "applying_for_grant": false,
        "course_uuid": null,
        "lead_partner_not_applicable": false,
        "employing_school_not_applicable": false,
        "submission_ready": true,
        "commencement_status": null,
        "discarded_at": null,
        "created_from_dttp": false,
        "hesa_id": "87960005710008762",
        "additional_dttp_data": null,
        "created_from_hesa": false,
        "hesa_updated_at": null
        "record_source": "api",
        "iqts_country": null,
        "hesa_editable": true,
        "withdraw_reasons_dfe_details": null,
        "placement_detail": null,
        "ukprn": "10000571",
        "ethnicity": "120",
        "course_qualification": "QTS",
        "course_title": null,
        "course_level": "undergrad",
        "course_itt_start_date": "2022-09-01",
        "course_age_range": null,
        "expected_end_date": "2023-07-01",
        "employing_school_urn": null,
        "lead_partner_ukprn": null,
        "lead_partner_urn": null,
        "fund_code": "7",
        "bursary_level": "4",
        "course_year": "2",
        "funding_method": "4",
        "itt_aim": "201",
        "itt_qualification_aim": "004",
        "ni_number": null,
        "previous_last_name": null,
        "hesa_disabilities": null,
        "additional_training_initiative": null,
        "placements": [
          {
            "placement_id": "AXsRAS4LfwZZXvSX7aAfNUb4",
            "urn": "123456",
            "name": "Meadow Creek School",
            "address": "URN 123456, AB1 2CD",
            "postcode": "AB1 2CD",
            "created_at": "2024-01-18T08:02:42.672Z",
            "updated_at": "2024-01-18T08:02:42.672Z"
          }
        ],
        "degrees": [
          {
            "degree_id": "E1phsAcP3hDFMhx19qVGhchR",
            "uk_degree": "083",
            "non_uk_degree": null,
            "created_at": "2024-01-18T08:02:41.955Z",
            "updated_at": "2024-01-18T08:02:41.955Z",
            "subject": "100425",
            "institution": "0116",
            "graduation_year": 2022,
            "grade": "02",
            "country": null,
            "other_grade": null,
            "institution_uuid": "0271f34a-2887-e711-80d8-005056ac45bb",
            "uk_degree_uuid": "db695652-c197-e711-80d8-005056ac45bb",
            "subject_uuid": "bf8170f0-5dce-e911-a985-000d3ab79618",
            "grade_uuid": "e2fe18d4-8655-47cf-ab1a-8c3e0b0f078f"
          }
        ]
      }
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "Trainee(s) not found"
        }
      ]
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }

GET /trainees/{trainee_id}/placements

Get many placements for a trainee.

Request

GET /api/v0.1/trainees/{trainee_id}/placements

Parameters

Parameter In Type Required Description
trainee_id path string true The unique ID of the trainee

Possible responses

HTTP 200 - An array of placements 
    {
      "data": [
        {
          "placement_id": "AXsRAS4LfwZZXvSX7aAfNUb4",
          "urn": "123456",
          "name": "Meadow Creek School",
          "address": "URN 123456, AB1 2CD",
          "postcode": "AB1 2CD",
          "created_at": "2024-01-18T08:02:42.672Z",
          "updated_at": "2024-01-18T08:02:42.672Z"
        }
      ]
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "Trainee(s) not found"
        }
      ]
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }

GET /trainees/{trainee_id}/placements/{placement_id}

Get a single placement for a trainee.

Request

GET /api/v0.1/trainees/{trainee_id}/placements/{placement_id}

Parameters

Parameter In Type Required Description
trainee_id path string true The unique ID of the trainee
placement_id path string true The unique ID of the placement

Possible responses

HTTP 200 - A placement 
    {
      "data": {
        "placement_id": "AXsRAS4LfwZZXvSX7aAfNUb4",
        "urn": "123456",
        "name": "Meadow Creek School",
        "address": "URN 123456, AB1 2CD",
        "postcode": "AB1 2CD",
        "created_at": "2024-01-18T08:02:42.672Z",
        "updated_at": "2024-01-18T08:02:42.672Z"
      }
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "Placement(s) not found"
        }
      ]
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }

GET /trainees/{trainee_id}/degrees

Get many degrees for a trainee.

Request

GET /api/v0.1/trainees/{trainee_id}/degrees

Parameters

Parameter In Type Required Description
trainee_id path string true The unique ID of the trainee

Possible responses

HTTP 200 - An array of degrees 
    {
      "data": [
        {
          "degree_id": "E1phsAcP3hDFMhx19qVGhchR",
          "uk_degree": "083",
          "non_uk_degree": null,
          "created_at": "2024-01-18T08:02:41.955Z",
          "updated_at": "2024-01-18T08:02:41.955Z",
          "subject": "100425",
          "institution": "0116",
          "graduation_year": 2022,
          "grade": "02",
          "country": null,
          "other_grade": null,
          "institution_uuid": "0271f34a-2887-e711-80d8-005056ac45bb",
          "uk_degree_uuid": "db695652-c197-e711-80d8-005056ac45bb",
          "subject_uuid": "bf8170f0-5dce-e911-a985-000d3ab79618",
          "grade_uuid": "e2fe18d4-8655-47cf-ab1a-8c3e0b0f078f"
        }
      ]
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "Degree(s) not found"
        }
      ]
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }

GET /trainees/{trainee_id}/degrees/{degree_id}

Get a single degree for a trainee.

Request

GET /api/v0.1/trainees/{trainee_id}/degrees/{degree_id}

Parameters

Parameter In Type Required Description
trainee_id path string true The unique ID of the trainee
degree_id path string true The unique ID of the degree

Possible responses

HTTP 200 - A degree 
    {
      "data": {
        "degree_id": "E1phsAcP3hDFMhx19qVGhchR",
        "uk_degree": "083",
        "non_uk_degree": null,
        "created_at": "2024-01-18T08:02:41.955Z",
        "updated_at": "2024-01-18T08:02:41.955Z",
        "subject": "100425",
        "institution": "0116",
        "graduation_year": 2022,
        "grade": "02",
        "country": null,
        "other_grade": null,
        "institution_uuid": "0271f34a-2887-e711-80d8-005056ac45bb",
        "uk_degree_uuid": "db695652-c197-e711-80d8-005056ac45bb",
        "subject_uuid": "bf8170f0-5dce-e911-a985-000d3ab79618",
        "grade_uuid": "e2fe18d4-8655-47cf-ab1a-8c3e0b0f078f"
      }
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "Degree(s) not found"
        }
      ]
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }

POST /trainees

Create a trainee.

Request

POST /api/v0.1/trainees

Request body

Trainee details

data

Trainee object with nested Placement and Degree objects

Example request body 
    {
      "data": {
        "provider_trainee_id": "12345678",
        "first_names": "John",
        "last_name": "Doe",
        "date_of_birth": "1990-01-01",
        "sex": "11",
        "email": "john.doe@example.com",
        "training_route": "11",
        "itt_start_date": "2023-09-01",
        "itt_end_date": "2024-07-01",
        "course_subject_one": "100425",
        "study_mode": "01",
        "nationality": "GB",
        "ethnicity": "120",
        "disability1": "58",
        "itt_aim": "201",
        "itt_qualification_aim": "004",
        "course_year": "2",
        "course_age_range": "13918",
        "fund_code": "7",
        "funding_method": "4",
        "hesa_id": "1210007145123456",
        "placements_attributes": [
          {
            "urn": "123456",
            "name": "Placement"
          }
        ],
        "degrees_attributes": [
          {
            "grade": "02",
            "subject": "100425",
            "institution": "0116",
            "uk_degree": "083",
            "graduation_year": "2012-07-31"
          }
        ]
      }
    }

Possible responses

HTTP 201 - A trainee 
    {
      "data": {
        "trainee_id": "vcGjpBCn987jJSqMQxjhdv9Y",
        "provider_trainee_id": "abc1234",
        "first_names": "Trainee",
        "last_name": "TraineeUser644065",
        "date_of_birth": "2000-01-01",
        "created_at": "2023-10-20T14:54:47.374Z",
        "updated_at": "2024-01-24T16:03:28.721Z",
        "email": "trainee_644065@example.com",
        "middle_names": null,
        "training_route": "11",
        "sex": "10",
        "diversity_disclosure": "diversity_disclosed",
        "ethnic_group": "black_ethnic_group",
        "ethnic_background": "African",
        "additional_ethnic_background": null,
        "disability_disclosure": "no_disability",
        "course_subject_one": "100425",
        "itt_start_date": "2023-09-04",
        "outcome_date": null,
        "itt_end_date": "2023-10-17",
        "trn": "6440650",
        "submitted_for_trn_at": "2024-01-18T08:02:41.420Z",
        "state": "deferred",
        "withdraw_date": null,
        "withdraw_reasons_details": null,
        "defer_date": "2023-10-17",
        "recommended_for_award_at": null,
        "trainee_start_date": "2023-09-04",
        "reinstate_date": null,
        "course_min_age": 5,
        "course_max_age": 11,
        "course_subject_two": null,
        "course_subject_three": null,
        "awarded_at": null,
        "training_initiative": "009",
        "applying_for_bursary": false,
        "bursary_tier": null,
        "study_mode": "01",
        "ebacc": false,
        "region": null,
        "applying_for_scholarship": false,
        "course_education_phase": "primary",
        "applying_for_grant": false,
        "course_uuid": null,
        "lead_partner_not_applicable": false,
        "employing_school_not_applicable": false,
        "submission_ready": true,
        "commencement_status": null,
        "discarded_at": null,
        "created_from_dttp": false,
        "hesa_id": "87960005710008762",
        "additional_dttp_data": null,
        "created_from_hesa": false,
        "hesa_updated_at": null
        "record_source": "api",
        "iqts_country": null,
        "hesa_editable": true,
        "withdraw_reasons_dfe_details": null,
        "placement_detail": null,
        "ukprn": "10000571",
        "ethnicity": "120",
        "course_qualification": "QTS",
        "course_title": null,
        "course_level": "undergrad",
        "course_itt_start_date": "2022-09-01",
        "course_age_range": null,
        "expected_end_date": "2023-07-01",
        "employing_school_urn": null,
        "lead_partner_ukprn": null,
        "lead_partner_urn": null,
        "fund_code": "7",
        "bursary_level": "4",
        "course_year": "2",
        "funding_method": "4",
        "itt_aim": "201",
        "itt_qualification_aim": "004",
        "ni_number": null,
        "previous_last_name": null,
        "hesa_disabilities": null,
        "additional_training_initiative": null,
        "placements": [
          {
            "placement_id": "AXsRAS4LfwZZXvSX7aAfNUb4",
            "urn": "123456",
            "name": "Meadow Creek School",
            "address": "URN 123456, AB1 2CD",
            "postcode": "AB1 2CD",
            "created_at": "2024-01-18T08:02:42.672Z",
            "updated_at": "2024-01-18T08:02:42.672Z"
          }
        ],
        "degrees": [
          {
            "degree_id": "E1phsAcP3hDFMhx19qVGhchR",
            "uk_degree": "083",
            "non_uk_degree": null,
            "created_at": "2024-01-18T08:02:41.955Z",
            "updated_at": "2024-01-18T08:02:41.955Z",
            "subject": "100425",
            "institution": "0116",
            "graduation_year": 2022,
            "grade": "02",
            "country": null,
            "other_grade": null,
            "institution_uuid": "0271f34a-2887-e711-80d8-005056ac45bb",
            "uk_degree_uuid": "db695652-c197-e711-80d8-005056ac45bb",
            "subject_uuid": "bf8170f0-5dce-e911-a985-000d3ab79618",
            "grade_uuid": "e2fe18d4-8655-47cf-ab1a-8c3e0b0f078f"
          }
        ]
      }
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }
HTTP 409 - Conflict 
    {
      "errors": "This trainee is already in Register",
      "data": [
        {
          "first_names": "John",
          "last_name": "Doe",
          "date_of_birth": "1990-01-01",
          "created_at": "2024-09-11T15:12:45.067Z",
          "updated_at": "2024-09-11T15:12:45.067Z",
          "email": "john.doe@example.com",
          "middle_names": null,
          "training_route": "11",
          "sex": "99",
          "diversity_disclosure": "diversity_disclosed",
          "ethnic_group": "mixed_ethnic_group",
          "ethnic_background": "Black Caribbean and White",
          "additional_ethnic_background": null,
          "disability_disclosure": "disabled",
          "course_subject_one": "100511",
          "itt_start_date": "2023-01-01",
          "outcome_date": null,
          "itt_end_date": "2023-10-01",
          "trn": null,
          "submitted_for_trn_at": "2024-09-11T15:12:45.345Z",
          "withdraw_date": null,
          "withdraw_reasons_details": null,
          "defer_date": null,
          "recommended_for_award_at": null,
          "trainee_start_date": "2023-01-01",
          "reinstate_date": null,
          "course_min_age": 5,
          "course_max_age": 11,
          "course_subject_two": "100346",
          "course_subject_three": "101410",
          "awarded_at": null,
          "training_initiative": null,
          "study_mode": "63",
          "ebacc": false,
          "region": null,
          "course_education_phase": "primary",
          "course_uuid": null,
          "lead_partner_not_applicable": true,
          "employing_school_not_applicable": true,
          "submission_ready": true,
          "commencement_status": null,
          "discarded_at": null,
          "created_from_dttp": false,
          "hesa_id": "0310261553101",
          "additional_dttp_data": null,
          "created_from_hesa": false,
          "hesa_updated_at": null,
          "record_source": "api",
          "iqts_country": null,
          "hesa_editable": false,
          "withdraw_reasons_dfe_details": null,
          "slug_sent_to_dqt_at": null,
          "placement_detail": null,
          "provider_trainee_id": "99157234/2/01",
          "ukprn": "81239124",
          "ethnicity": "142",
          "disability1": "58",
          "disability2": "57",
          "course_qualification": "QTS",
          "course_title": null,
          "course_level": "undergrad",
          "course_itt_start_date": "2023-01-01",
          "course_age_range": "13914",
          "expected_end_date": "2023-10-01",
          "employing_school_urn": null,
          "lead_partner_ukprn": null,
          "lead_partner_urn": null,
          "fund_code": "7",
          "bursary_level": "4",
          "previous_last_name": "Smith",
          "itt_aim": "202",
          "course_study_mode": "63",
          "course_year": "1",
          "pg_apprenticeship_start_date": "2024-03-11",
          "funding_method": "4",
          "ni_number": null,
          "additional_training_initiative": null,
          "itt_qualification_aim": "001",
          "hesa_disabilities": {
            "disability1": "58",
            "disability2": "57"
          },
          "nationality": "GB",
          "withdraw_reasons": [],
          "placements": [
            {
              "urn": "900020",
              "name": "London School",
              "address": "URN 900020",
              "postcode": null,
              "created_at": "2024-09-11T15:12:45.090Z",
              "updated_at": "2024-09-11T15:12:45.090Z",
              "placement_id": "D8VsiEck1ueqigL1Pu9ESAaR"
            }
          ],
          "degrees": [
            {
              "uk_degree": "083",
              "non_uk_degree": null,
              "created_at": "2024-09-11T15:12:45.069Z",
              "updated_at": "2024-09-11T15:12:45.069Z",
              "subject": "100485",
              "institution": "0117",
              "graduation_year": 2003,
              "grade": "02",
              "country": null,
              "other_grade": null,
              "institution_uuid": "1271f34a-2887-e711-80d8-005056ac45bb",
              "uk_degree_uuid": "1b6a5652-c197-e711-80d8-005056ac45bb",
              "subject_uuid": "e78170f0-5dce-e911-a985-000d3ab79618",
              "grade_uuid": "e2fe18d4-8655-47cf-ab1a-8c3e0b0f078f",
              "degree_id": "cPTm9iXPbLzER8UqReEFGvNn"
            }
          ],
          "state": "submitted_for_trn",
          "trainee_id": "EMHhWRF33g53PReREX6rdPwd",
          "application_id": null
        }
      ]
    }
HTTP 422 - Unprocessable Entity 
    {
      "errors": [
        {
          "error": "UnprocessableEntity",
          "message": "First names can't be blank"
        }
      ]
    }

POST /trainees/{trainee_id}/placements

Create a placement for this trainee.

Request

POST /api/v0.1/trainees/{trainee_id}/placements

Parameters

Parameter In Type Required Description
trainee_id path string true The unique ID of the trainee

Request body

Placement details

data

Placement object

Example request body 
    {
      "data": {
        "urn": "123456",
        "name": "Placement"
      }
    }

Possible responses

HTTP 201 - A placement 
    {
      "data": {
        "placement_id": "AXsRAS4LfwZZXvSX7aAfNUb4",
        "urn": "123456",
        "name": "Meadow Creek School",
        "address": "URN 123456, AB1 2CD",
        "postcode": "AB1 2CD",
        "created_at": "2024-01-18T08:02:42.672Z",
        "updated_at": "2024-01-18T08:02:42.672Z"
      }
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "Trainee(s) not found"
        }
      ]
    }
HTTP 409 - Conflict 
    {
      "errors": [
        {
          "error": "Conflict",
          "message": "Urn has already been taken"
        }
      ]
    }
HTTP 422 - Unprocessable Entity 
    {
      "errors": [
        {
          "error": "UnprocessableEntity",
          "message": "Name can't be blank"
        }
      ]
    }

POST /trainees/{trainee_id}/degrees

Create a degree for this trainee.

Request

POST /api/v0.1/trainees/{trainee_id}/degrees

Parameters

Parameter In Type Required Description
trainee_id path string true The unique ID of the trainee

Request body

Degree details

data

Degree object

Example request body 
    {
      "data": {
        "grade": "02",
        "subject": "100425",
        "institution": "0116",
        "uk_degree": "083",
        "graduation_year": "2012-07-31"
      }
    }

Possible responses

HTTP 201 - A degree 
    {
      "data": [
        {
          "degree_id": "E1phsAcP3hDFMhx19qVGhchR",
          "uk_degree": "083",
          "non_uk_degree": null,
          "created_at": "2024-01-18T08:02:41.955Z",
          "updated_at": "2024-01-18T08:02:41.955Z",
          "subject": "100425",
          "institution": "0116",
          "graduation_year": 2022,
          "grade": "02",
          "country": null,
          "other_grade": null,
          "institution_uuid": "0271f34a-2887-e711-80d8-005056ac45bb",
          "uk_degree_uuid": "db695652-c197-e711-80d8-005056ac45bb",
          "subject_uuid": "bf8170f0-5dce-e911-a985-000d3ab79618",
          "grade_uuid": "e2fe18d4-8655-47cf-ab1a-8c3e0b0f078f"
        }
      ]
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "Trainee(s) not found"
        }
      ]
    }
HTTP 409 - Conflict 
    {
      "errors": [
        {
          "error": "Conflict",
          "message": "This is a duplicate degree"
        }
      ]
    }
HTTP 422 - Unprocessable Entity 
    {
      "errors": [
        {
          "error": "UnprocessableEntity",
          "message": "Param is missing or the value is empty: data"
        }
      ]
    }

POST /trainees/{trainee_id}/recommend-for-qts

Recommend a trainee for a QTS Award.

Request

POST /api/v0.1/trainees/{trainee_id}/recommend-for-qts

Parameters

Parameter In Type Required Description
trainee_id path string true The unique ID of the trainee

Request body

Recommendation details

qts_standards_met_date

string, required

The date when the Trainee met the QTS standards. Dates should be in ISO 8601 format.

Example: 2000-01-01

Example request body 
    {
      "data": {
        "qts_standards_met_date": "2024-06-17"
      }
    }

Possible responses

HTTP 202 - A trainee 
    {
      "data": {
        "trainee_id": "vcGjpBCn987jJSqMQxjhdv9Y",
        "provider_trainee_id": "abc1234",
        "first_names": "Trainee",
        "last_name": "TraineeUser644065",
        "date_of_birth": "2000-01-01",
        "created_at": "2023-10-20T14:54:47.374Z",
        "updated_at": "2024-01-24T16:03:28.721Z",
        "email": "trainee_644065@example.com",
        "middle_names": null,
        "training_route": "11",
        "sex": "10",
        "diversity_disclosure": "diversity_disclosed",
        "ethnic_group": "black_ethnic_group",
        "ethnic_background": "African",
        "additional_ethnic_background": null,
        "disability_disclosure": "no_disability",
        "course_subject_one": "100425",
        "itt_start_date": "2023-09-04",
        "outcome_date": null,
        "itt_end_date": "2023-10-17",
        "trn": "6440650",
        "submitted_for_trn_at": "2024-01-18T08:02:41.420Z",
        "state": "recommended_for_award",
        "withdraw_date": null,
        "withdraw_reasons_details": null,
        "defer_date": "2023-10-17",
        "recommended_for_award_at": "2024-06-17T09:05:48Z",
        "trainee_start_date": "2023-09-04",
        "reinstate_date": null,
        "course_min_age": 5,
        "course_max_age": 11,
        "course_subject_two": null,
        "course_subject_three": null,
        "awarded_at": null,
        "training_initiative": "009",
        "applying_for_bursary": false,
        "bursary_tier": null,
        "study_mode": "01",
        "ebacc": false,
        "region": null,
        "applying_for_scholarship": false,
        "course_education_phase": "primary",
        "applying_for_grant": false,
        "course_uuid": null,
        "lead_partner_not_applicable": false,
        "employing_school_not_applicable": false,
        "submission_ready": true,
        "commencement_status": null,
        "discarded_at": null,
        "created_from_dttp": false,
        "hesa_id": "87960005710008762",
        "additional_dttp_data": null,
        "created_from_hesa": false,
        "hesa_updated_at": null
        "record_source": "api",
        "iqts_country": null,
        "hesa_editable": true,
        "withdraw_reasons_dfe_details": null,
        "placement_detail": null,
        "ukprn": "10000571",
        "ethnicity": "120",
        "course_qualification": "QTS",
        "course_title": null,
        "course_level": "undergrad",
        "course_itt_start_date": "2022-09-01",
        "course_age_range": null,
        "expected_end_date": "2023-07-01",
        "employing_school_urn": null,
        "lead_partner_ukprn": null,
        "lead_partner_urn": null,
        "fund_code": "7",
        "bursary_level": "4",
        "course_year": "2",
        "funding_method": "4",
        "itt_aim": "201",
        "itt_qualification_aim": "004",
        "ni_number": null,
        "previous_last_name": null,
        "hesa_disabilities": null,
        "additional_training_initiative": null,
        "placements": [
          {
            "placement_id": "AXsRAS4LfwZZXvSX7aAfNUb4",
            "urn": "123456",
            "name": "Meadow Creek School",
            "address": "URN 123456, AB1 2CD",
            "postcode": "AB1 2CD",
            "created_at": "2024-01-18T08:02:42.672Z",
            "updated_at": "2024-01-18T08:02:42.672Z"
          }
        ],
        "degrees": [
          {
            "degree_id": "E1phsAcP3hDFMhx19qVGhchR",
            "uk_degree": "083",
            "non_uk_degree": null,
            "created_at": "2024-01-18T08:02:41.955Z",
            "updated_at": "2024-01-18T08:02:41.955Z",
            "subject": "100425",
            "institution": "0116",
            "graduation_year": 2022,
            "grade": "02",
            "country": null,
            "other_grade": null,
            "institution_uuid": "0271f34a-2887-e711-80d8-005056ac45bb",
            "uk_degree_uuid": "db695652-c197-e711-80d8-005056ac45bb",
            "subject_uuid": "bf8170f0-5dce-e911-a985-000d3ab79618",
            "grade_uuid": "e2fe18d4-8655-47cf-ab1a-8c3e0b0f078f"
          }
        ]
      }
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "Trainee(s) not found"
        }
      ]
    }
HTTP 422 - Unprocessable Entity 
    {
      "errors": [
        {
          "error": "UnprocessableEntity",
          "message": "Qts standards met date can't be blank"
        }
      ]
    }

POST /trainees/{trainee_id}/defer

Defer a trainee.

Request

POST /api/v0.1/trainees/{trainee_id}/defer

Parameters

Parameter In Type Required Description
trainee_id path string true The unique ID of the trainee

Request body

Deferral details

defer_date

string, required

The date when the Trainee deferred. Dates should be in ISO 8601 format.

Example: 2000-01-01

Example request body 
    {
      "data": {
        "defer_date": "2024-06-17"
      }
    }

Possible responses

HTTP 200 - A trainee 
    {
      "data": {
        "trainee_id": "vcGjpBCn987jJSqMQxjhdv9Y",
        "provider_trainee_id": "abc1234",
        "first_names": "Trainee",
        "last_name": "TraineeUser644065",
        "date_of_birth": "2000-01-01",
        "created_at": "2023-10-20T14:54:47.374Z",
        "updated_at": "2024-01-24T16:03:28.721Z",
        "email": "trainee_644065@example.com",
        "middle_names": null,
        "training_route": "11",
        "sex": "10",
        "diversity_disclosure": "diversity_disclosed",
        "ethnic_group": "black_ethnic_group",
        "ethnic_background": "African",
        "additional_ethnic_background": null,
        "disability_disclosure": "no_disability",
        "course_subject_one": "100425",
        "itt_start_date": "2023-09-04",
        "outcome_date": null,
        "itt_end_date": "2023-10-17",
        "trn": "6440650",
        "submitted_for_trn_at": "2024-01-18T08:02:41.420Z",
        "state": "recommended_for_award",
        "withdraw_date": null,
        "withdraw_reasons_details": null,
        "defer_date": "2024-06-17",
        "recommended_for_award_at": nil,
        "trainee_start_date": "2023-09-04",
        "reinstate_date": null,
        "course_min_age": 5,
        "course_max_age": 11,
        "course_subject_two": null,
        "course_subject_three": null,
        "awarded_at": null,
        "training_initiative": "009",
        "applying_for_bursary": false,
        "bursary_tier": null,
        "study_mode": "01",
        "ebacc": false,
        "region": null,
        "applying_for_scholarship": false,
        "course_education_phase": "primary",
        "applying_for_grant": false,
        "course_uuid": null,
        "lead_partner_not_applicable": false,
        "employing_school_not_applicable": false,
        "submission_ready": true,
        "commencement_status": null,
        "discarded_at": null,
        "created_from_dttp": false,
        "hesa_id": "87960005710008762",
        "additional_dttp_data": null,
        "created_from_hesa": false,
        "hesa_updated_at": null
        "record_source": "api",
        "iqts_country": null,
        "hesa_editable": true,
        "withdraw_reasons_dfe_details": null,
        "placement_detail": null,
        "ukprn": "10000571",
        "ethnicity": "120",
        "course_qualification": "QTS",
        "course_title": null,
        "course_level": "undergrad",
        "course_itt_start_date": "2022-09-01",
        "course_age_range": null,
        "expected_end_date": "2023-07-01",
        "employing_school_urn": null,
        "lead_partner_ukprn": null,
        "lead_partner_urn": null,
        "fund_code": "7",
        "bursary_level": "4",
        "course_year": "2",
        "funding_method": "4",
        "itt_aim": "201",
        "itt_qualification_aim": "004",
        "ni_number": null,
        "previous_last_name": null,
        "hesa_disabilities": null,
        "additional_training_initiative": null,
        "placements": [
          {
            "placement_id": "AXsRAS4LfwZZXvSX7aAfNUb4",
            "urn": "123456",
            "name": "Meadow Creek School",
            "address": "URN 123456, AB1 2CD",
            "postcode": "AB1 2CD",
            "created_at": "2024-01-18T08:02:42.672Z",
            "updated_at": "2024-01-18T08:02:42.672Z"
          }
        ],
        "degrees": [
          {
            "degree_id": "E1phsAcP3hDFMhx19qVGhchR",
            "uk_degree": "083",
            "non_uk_degree": null,
            "created_at": "2024-01-18T08:02:41.955Z",
            "updated_at": "2024-01-18T08:02:41.955Z",
            "subject": "100425",
            "institution": "0116",
            "graduation_year": 2022,
            "grade": "02",
            "country": null,
            "other_grade": null,
            "institution_uuid": "0271f34a-2887-e711-80d8-005056ac45bb",
            "uk_degree_uuid": "db695652-c197-e711-80d8-005056ac45bb",
            "subject_uuid": "bf8170f0-5dce-e911-a985-000d3ab79618",
            "grade_uuid": "e2fe18d4-8655-47cf-ab1a-8c3e0b0f078f"
          }
        ]
      }
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "Trainee(s) not found"
        }
      ]
    }
HTTP 422 - Unprocessable Entity 
    {
      "errors": [
        {
          "error": "UnprocessableEntity",
          "message": "Defer date can't be blank"
        }
      ]
    }

DELETE /trainees/{trainee_id}/degrees/{degree_id}

Deletes an existing degree for this trainee.

Request

DELETE /api/v0.1/trainees/{trainee_id}/degrees/{degree_id}

Parameters

Parameter In Type Required Description
trainee_id path string true The unique ID of the trainee
degree_id path string true The unique ID of the degree

Possible responses

HTTP 200 - A trainee 
    {
      "data": {
        "trainee_id": "vcGjpBCn987jJSqMQxjhdv9Y",
        "provider_trainee_id": "abc1234",
        "first_names": "Trainee",
        "last_name": "TraineeUser644065",
        "date_of_birth": "2000-01-01",
        "created_at": "2023-10-20T14:54:47.374Z",
        "updated_at": "2024-01-24T16:03:28.721Z",
        "email": "trainee_644065@example.com",
        "middle_names": null,
        "training_route": "11",
        "sex": "10",
        "diversity_disclosure": "diversity_disclosed",
        "ethnic_group": "black_ethnic_group",
        "ethnic_background": "African",
        "additional_ethnic_background": null,
        "disability_disclosure": "no_disability",
        "course_subject_one": "100425",
        "itt_start_date": "2023-09-04",
        "outcome_date": null,
        "itt_end_date": "2023-10-17",
        "trn": "6440650",
        "submitted_for_trn_at": "2024-01-18T08:02:41.420Z",
        "state": "deferred",
        "withdraw_date": null,
        "withdraw_reasons_details": null,
        "defer_date": "2023-10-17",
        "recommended_for_award_at": ,
        "trainee_start_date": "2023-09-04",
        "reinstate_date": null,
        "course_min_age": 5,
        "course_max_age": 11,
        "course_subject_two": null,
        "course_subject_three": null,
        "awarded_at": null,
        "training_initiative": "009",
        "applying_for_bursary": false,
        "bursary_tier": null,
        "study_mode": "01",
        "ebacc": false,
        "region": null,
        "applying_for_scholarship": false,
        "course_education_phase": "primary",
        "applying_for_grant": false,
        "course_uuid": null,
        "lead_partner_not_applicable": false,
        "employing_school_not_applicable": false,
        "submission_ready": true,
        "commencement_status": null,
        "discarded_at": null,
        "created_from_dttp": false,
        "hesa_id": "87960005710008762",
        "additional_dttp_data": null,
        "created_from_hesa": false,
        "hesa_updated_at": null
        "record_source": "api",
        "iqts_country": null,
        "hesa_editable": true,
        "withdraw_reasons_dfe_details": null,
        "placement_detail": null,
        "ukprn": "10000571",
        "ethnicity": "120",
        "course_qualification": "QTS",
        "course_title": null,
        "course_level": "undergrad",
        "course_itt_start_date": "2022-09-01",
        "course_age_range": null,
        "expected_end_date": "2023-07-01",
        "employing_school_urn": null,
        "lead_partner_ukprn": null,
        "lead_partner_urn": null,
        "fund_code": "7",
        "bursary_level": "4",
        "course_year": "2",
        "funding_method": "4",
        "itt_aim": "201",
        "itt_qualification_aim": "004",
        "ni_number": null,
        "previous_last_name": null,
        "hesa_disabilities": null,
        "additional_training_initiative": null,
        "placements": [
          {
            "placement_id": "AXsRAS4LfwZZXvSX7aAfNUb4",
            "urn": "123456",
            "name": "Meadow Creek School",
            "address": "URN 123456, AB1 2CD",
            "postcode": "AB1 2CD",
            "created_at": "2024-01-18T08:02:42.672Z",
            "updated_at": "2024-01-18T08:02:42.672Z"
          }
        ],
        "degrees": []
      }
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "Degree(s) not found"
        }
      ]
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }

PUT|PATCH /trainees/{trainee_id}

Updates an existing trainee.

Request

PUT /api/v0.1/trainees/{trainee_id}

or

PATCH /api/v0.1/trainees/{trainee_id}

Parameters

Parameter In Type Required Description
trainee_id path string true The unique ID of the trainee

Request body

Trainee details

data

Trainee object

Example request body 
    {
      "data": {
        "first_names": "Ruby Joy"
      }
    }

Possible responses

HTTP 200 - A trainee 
    {
      "data": {
        "trainee_id": "vcGjpBCn987jJSqMQxjhdv9Y",
        "provider_trainee_id": "abc1234",
        "first_names": "Trainee",
        "last_name": "TraineeUser644065",
        "date_of_birth": "2000-01-01",
        "created_at": "2023-10-20T14:54:47.374Z",
        "updated_at": "2024-01-24T16:03:28.721Z",
        "email": "trainee_644065@example.com",
        "middle_names": null,
        "training_route": "11",
        "sex": "10",
        "diversity_disclosure": "diversity_disclosed",
        "ethnic_group": "black_ethnic_group",
        "ethnic_background": "African",
        "additional_ethnic_background": null,
        "disability_disclosure": "no_disability",
        "course_subject_one": "100425",
        "itt_start_date": "2023-09-04",
        "outcome_date": null,
        "itt_end_date": "2023-10-17",
        "trn": "6440650",
        "submitted_for_trn_at": "2024-01-18T08:02:41.420Z",
        "state": "deferred",
        "withdraw_date": null,
        "withdraw_reasons_details": null,
        "defer_date": "2023-10-17",
        "recommended_for_award_at": null,
        "trainee_start_date": "2023-09-04",
        "reinstate_date": null,
        "course_min_age": 5,
        "course_max_age": 11,
        "course_subject_two": null,
        "course_subject_three": null,
        "awarded_at": null,
        "training_initiative": "009",
        "applying_for_bursary": false,
        "bursary_tier": null,
        "study_mode": "01",
        "ebacc": false,
        "region": null,
        "applying_for_scholarship": false,
        "course_education_phase": "primary",
        "applying_for_grant": false,
        "course_uuid": null,
        "lead_partner_not_applicable": false,
        "employing_school_not_applicable": false,
        "submission_ready": true,
        "commencement_status": null,
        "discarded_at": null,
        "created_from_dttp": false,
        "hesa_id": "87960005710008762",
        "additional_dttp_data": null,
        "created_from_hesa": false,
        "hesa_updated_at": null
        "record_source": "api",
        "iqts_country": null,
        "hesa_editable": true,
        "withdraw_reasons_dfe_details": null,
        "placement_detail": null,
        "ukprn": "10000571",
        "ethnicity": "120",
        "course_qualification": "QTS",
        "course_title": null,
        "course_level": "undergrad",
        "course_itt_start_date": "2022-09-01",
        "course_age_range": null,
        "expected_end_date": "2023-07-01",
        "employing_school_urn": null,
        "lead_partner_ukprn": null,
        "lead_partner_urn": null,
        "fund_code": "7",
        "bursary_level": "4",
        "course_year": "2",
        "funding_method": "4",
        "itt_aim": "201",
        "itt_qualification_aim": "004",
        "ni_number": null,
        "previous_last_name": null,
        "hesa_disabilities": null,
        "additional_training_initiative": null,
        "placements": [
          {
            "placement_id": "AXsRAS4LfwZZXvSX7aAfNUb4",
            "urn": "123456",
            "name": "Meadow Creek School",
            "address": "URN 123456, AB1 2CD",
            "postcode": "AB1 2CD",
            "created_at": "2024-01-18T08:02:42.672Z",
            "updated_at": "2024-01-18T08:02:42.672Z"
          }
        ],
        "degrees": [
          {
            "degree_id": "E1phsAcP3hDFMhx19qVGhchR",
            "uk_degree": "083",
            "non_uk_degree": null,
            "created_at": "2024-01-18T08:02:41.955Z",
            "updated_at": "2024-01-18T08:02:41.955Z",
            "subject": "100425",
            "institution": "0116",
            "graduation_year": 2022,
            "grade": "02",
            "country": null,
            "other_grade": null,
            "institution_uuid": "0271f34a-2887-e711-80d8-005056ac45bb",
            "uk_degree_uuid": "db695652-c197-e711-80d8-005056ac45bb",
            "subject_uuid": "bf8170f0-5dce-e911-a985-000d3ab79618",
            "grade_uuid": "e2fe18d4-8655-47cf-ab1a-8c3e0b0f078f"
          }
        ]
      }
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "Trainee(s) not found"
        }
      ]
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }
HTTP 422 - Unprocessable Entity 
    {
      "errors": [
        {
          "error": "UnprocessableEntity",
          "message": "First names is too long (maximum is 60 characters)"
        }
      ]
    }

PUT|PATCH /trainees/{trainee_id}/placements/{placement_id}

Updates an existing placement for this trainee.

Request

PUT /api/v0.1/trainees/{trainee_id}/placements/{placement_id}

or

PATCH /api/v0.1/trainees/{trainee_id}/placements/{placement_id}

Parameters

Parameter In Type Required Description
trainee_id path string true The unique ID of the trainee
placement_id path string true The unique ID of the placement

Request body

Placement details

data

Placement object

Example request body 
    {
      "data": {
        "urn": "137523",
        "name": "Wellsway School"
      }
    }

Possible responses

HTTP 200 - A placement 
    {
      "data": {
        "urn": null,
        "name": "Wellsway School",
        "address": null,
        "postcode": null,
        "created_at": "2024-03-19T22:23:48.619Z",
        "updated_at": "2024-03-19T22:23:48.619Z"
      }
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "Placement(s) not found"
        }
      ]
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }
HTTP 422 - Unprocessable Entity 
    {
      "errors": [
        {
          "error": "UnprocessableEntity",
          "message": "Name can't be blank"
        }
      ]
    }

PUT|PATCH /trainees/{trainee_id}/degrees/{degree_id}

Updates an existing degree for this trainee.

Request

PUT /api/v0.1/trainees/{trainee_id}/degrees/{degree_id}

or

PATCH /api/v0.1/trainees/{trainee_id}/degrees/{degree_id}

Parameters

Parameter In Type Required Description
trainee_id path string true The unique ID of the trainee
degree_id path string true The unique ID of the degree

Request body

Degree details

data

Degree object

Example request body 
    {
      "data": {
        "grade": "Lower second-class honours (2:2)"
      }
    }

Possible responses

HTTP 200 - A degree 
    {
      "data": {
        "degree_id": "E1phsAcP3hDFMhx19qVGhchR",
        "uk_degree": "083",
        "non_uk_degree": null,
        "created_at": "2024-01-18T08:02:41.955Z",
        "updated_at": "2024-01-18T08:02:41.955Z",
        "subject": "100425",
        "institution": "0116",
        "graduation_year": 2022,
        "grade": "02",
        "country": null,
        "other_grade": null,
        "institution_uuid": "0271f34a-2887-e711-80d8-005056ac45bb",
        "uk_degree_uuid": "db695652-c197-e711-80d8-005056ac45bb",
        "subject_uuid": "bf8170f0-5dce-e911-a985-000d3ab79618",
        "grade_uuid": "e2fe18d4-8655-47cf-ab1a-8c3e0b0f078f"
      }
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "Degree(s) not found"
        }
      ]
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }
HTTP 409 - Conflict 
    {
      "errors": [
        {
          "error": "Conflict",
          "message": "This is a duplicate degree"
        }
      ]
    }
HTTP 422 - Unprocessable Entity 
    {
      "errors": [
        {
          "error": "UnprocessableEntity",
          "message": "Subject is not included in the list"
        }
      ]
    }

DELETE /trainees/{trainee_id}/placements/{placement_id}

Deletes an existing placement for this trainee.

Request

DELETE /api/v0.1/trainees/{trainee_id}/placements/{placement_id}

Parameters

Parameter In Type Required Description
trainee_id path string true The unique ID of the trainee
placement_id path string true The unique ID of the placement

Possible responses

HTTP 200 - A trainee 
    {
      "data": {
        "trainee_id": "vcGjpBCn987jJSqMQxjhdv9Y",
        "provider_trainee_id": "abc1234",
        "first_names": "Trainee",
        "last_name": "TraineeUser644065",
        "date_of_birth": "2000-01-01",
        "created_at": "2023-10-20T14:54:47.374Z",
        "updated_at": "2024-01-24T16:03:28.721Z",
        "email": "trainee_644065@example.com",
        "middle_names": null,
        "training_route": "11",
        "sex": "10",
        "diversity_disclosure": "diversity_disclosed",
        "ethnic_group": "black_ethnic_group",
        "ethnic_background": "African",
        "additional_ethnic_background": null,
        "disability_disclosure": "no_disability",
        "course_subject_one": "100425",
        "itt_start_date": "2023-09-04",
        "outcome_date": null,
        "itt_end_date": "2023-10-17",
        "trn": "6440650",
        "submitted_for_trn_at": "2024-01-18T08:02:41.420Z",
        "state": "deferred",
        "withdraw_date": null,
        "withdraw_reasons_details": null,
        "defer_date": "2023-10-17",
        "recommended_for_award_at": null,
        "trainee_start_date": "2023-09-04",
        "reinstate_date": null,
        "course_min_age": 5,
        "course_max_age": 11,
        "course_subject_two": null,
        "course_subject_three": null,
        "awarded_at": null,
        "training_initiative": "009",
        "applying_for_bursary": false,
        "bursary_tier": null,
        "study_mode": "01",
        "ebacc": false,
        "region": null,
        "applying_for_scholarship": false,
        "course_education_phase": "primary",
        "applying_for_grant": false,
        "course_uuid": null,
        "lead_partner_not_applicable": false,
        "employing_school_not_applicable": false,
        "submission_ready": true,
        "commencement_status": null,
        "discarded_at": null,
        "created_from_dttp": false,
        "hesa_id": "87960005710008762",
        "additional_dttp_data": null,
        "created_from_hesa": false,
        "hesa_updated_at": null
        "record_source": "api",
        "iqts_country": null,
        "hesa_editable": true,
        "withdraw_reasons_dfe_details": null,
        "placement_detail": null,
        "ukprn": "10000571",
        "ethnicity": "120",
        "course_qualification": "QTS",
        "course_title": null,
        "course_level": "undergrad",
        "course_itt_start_date": "2022-09-01",
        "course_age_range": null,
        "expected_end_date": "2023-07-01",
        "employing_school_urn": null,
        "lead_partner_ukprn": null,
        "lead_partner_urn": null,
        "fund_code": "7",
        "bursary_level": "4",
        "course_year": "2",
        "funding_method": "4",
        "itt_aim": "201",
        "itt_qualification_aim": "004",
        "ni_number": null,
        "previous_last_name": null,
        "hesa_disabilities": null,
        "additional_training_initiative": null,
        "placements": [
          {
            "placement_id": "AXsRAS4LfwZZXvSX7aAfNUb4",
            "urn": "123456",
            "name": "Meadow Creek School",
            "address": "URN 123456, AB1 2CD",
            "postcode": "AB1 2CD",
            "created_at": "2024-01-18T08:02:42.672Z",
            "updated_at": "2024-01-18T08:02:42.672Z"
          }
        ],
        "degrees": [
          {
            "degree_id": "E1phsAcP3hDFMhx19qVGhchR",
            "uk_degree": "083",
            "non_uk_degree": null,
            "created_at": "2024-01-18T08:02:41.955Z",
            "updated_at": "2024-01-18T08:02:41.955Z",
            "subject": "100425",
            "institution": "0116",
            "graduation_year": 2022,
            "grade": "02",
            "country": null,
            "other_grade": null,
            "institution_uuid": "0271f34a-2887-e711-80d8-005056ac45bb",
            "uk_degree_uuid": "db695652-c197-e711-80d8-005056ac45bb",
            "subject_uuid": "bf8170f0-5dce-e911-a985-000d3ab79618",
            "grade_uuid": "e2fe18d4-8655-47cf-ab1a-8c3e0b0f078f"
          }
        ]
      }
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "Placement(s) not found"
        }
      ]
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }

DELETE /trainees/{trainee_id}/degrees/{degree_id}

Deletes an existing degree for this trainee.

Request

DELETE /api/v0.1/trainees/{trainee_id}/degrees/{degree_id}

Parameters

Parameter In Type Required Description
trainee_id path string true The unique ID of the trainee
degree_id path string true The unique ID of the degree

Possible responses

HTTP 200 - A degree 
    {
      "data": [
        {
          "degree_id": "E1phsAcP3hDFMhx19qVGhchR",
          "uk_degree": "083",
          "non_uk_degree": null,
          "created_at": "2024-01-18T08:02:41.955Z",
          "updated_at": "2024-01-18T08:02:41.955Z",
          "subject": "100425",
          "institution": "0116",
          "graduation_year": 2022,
          "grade": "02",
          "country": null,
          "other_grade": null,
          "institution_uuid": "0271f34a-2887-e711-80d8-005056ac45bb",
          "uk_degree_uuid": "db695652-c197-e711-80d8-005056ac45bb",
          "subject_uuid": "bf8170f0-5dce-e911-a985-000d3ab79618",
          "grade_uuid": "e2fe18d4-8655-47cf-ab1a-8c3e0b0f078f"
        }
      ]
    }
HTTP 404 - Not found 
    {
      "errors": [
        {
          "error": "NotFound",
          "message": "Degree(s) not found"
        }
      ]
    }
HTTP 401 - Unauthorized 
    {
      "error": "Unauthorized"
    }

Objects

Trainee object

trainee_id

string (limited to 24 characters)

The unique ID of the trainee in the Register system. Used to identify the trainee when using endpoints which require a trainee_id.

Example: 37T2Vm9aipqSVokbhWUMjedu

provider_trainee_id

string (limited to 20 characters)

The unique ID of the trainee in the Provider's student record system (SRS). Coded according to the HESA provider's own identifier for student field

Example: 99157234

application_id

integer

The unique ID of the application choice in the Apply system.

Example: 123456

trn

string (limited to 7 characters)

The reference number allocated to each trainee prior to course completion.

Example: 2248531

first_names

string (limited to 60 characters), required

The first names of the trainee.

Example: Ruby Joy

last_name

string (limited to 60 characters), required

The last name of the trainee.

Example: Smith

previous_last_name

string (limited to 60 characters)

The last name of the trainee immediately before their current last name.

Example: Jones

date_of_birth

string, required

The date of birth of the trainee. Coded according to the HESA date of birth field

Example: 2000-01-01

sex

string (limited to 2 characters), required

The sex of the trainee. Coded according to the HESA sex identifier field

Example: 10

nationality

string (limited to 2 characters), required

The nationality of the trainee. Coded according to the HESA nationality field

Example: GB

email

string (limited to 80 characters), required

The email address of the trainee. Coded according to the HESA email addresses field

Example: trainee123@example.com

ethnicity

string (limited to 3 characters)

The ethnicity of the trainee. Coded according to the HESA ethnicity field. The values for ethnic_background and ethnic_group will be set based on the ethnicity value.

Example: 120

disability1 to disability9

string (limited to 2 characters)

The type of disabilities that the trainee has. Coded according to the HESA disability field

Example: 58

itt_aim

string (limited to 3 characters), required

The general qualification aim of the course in terms of qualifications and professional statuses. Coded according to the HESA ITT qualification aim field

Example: 201

training_route

string (limited to 2 characters), required

The training route that the trainee is on. Coded according to the HESA entry route field

Example: 11

itt_qualification_aim

string (limited to 3 characters), required

The qualification aim of the trainee's course. Coded according to the HESA qualification aim field

Example: 004

course_subject_one, course_subject_two, course_subject_three

string (limited to 6 characters), course_subject_one is required

The subjects included in the trainee's course. The first subject is the main one. It represents the bursary or scholarship available if applicable. Coded according to the HESA subject of ITT course field

Example: 100425

study_mode

string (limited to 2 characters), required

This indicates whether the trainee's course is full time or part time. Coded according to the HESA mode of study field

Example: 01

itt_start_date

string, required

The start date of the Initial Teacher Training part of their course. Dates should be in ISO 8601 format.

Example: 2024-03-11

itt_end_date

string, required

The end date of the Initial Teacher Training part of their course. Dates should be in ISO 8601 format.

Example: 2025-03-11

course_year

string (limited to 2 characters), required

The year number of the course that the trainee is currently studying. Coded according to the HESA year of course field

Example: 2

course_age_range

string (limited to 5 characters), required

The age range of the course. Coded according to the HESA ITT phase/scope field

Example: 13918

trainee_start_date

string

The start date of the trainee on their ITT course. Dates should be in ISO 8601 format.

Example: 2024-03-11

pg_apprenticeship_start_date

string

The start date of a trainee's postgraduate teaching apprenticeship. Dates should be in ISO 8601 format.

Example: 2024-03-11

employing_school_urn

string (limited to 6 characters)

The Unique Reference Number (URN) of the employing school for School Direct salaried trainees.

Example: 123456

lead_partner_urn

string (limited to 6 characters)

The Unique Reference Number (URN) of the lead partner for trainees.

Example: 123456

fund_code

string (limited to 1 characters), required

The funding eligibility of the trainee. Coded according to the HESA fundability code field

Example: 7

funding_method

string (limited to 1 characters), required

The bursary level awarded to the trainee. Coded according to the HESA bursary level award field

Example: 4

training_initiative

string (limited to 3 characters)

The main training initiative that the trainee is on. Coded according to the HESA initiatives field

Example: 009

additional_training_initiative

string (limited to 3 characters)

The secondary training initiative that the trainee is on. Coded according to the HESA initiatives field

Example: 025

hesa_id

string (limited to 17 characters), required

The HESA unique student identifier for the trainee. Coded according to the HESA unique student identifier field

Example: 1210007145123456

ni_number

string (limited to 9 characters)

The trainee's National Insurance Number.

Example: BX5867459C

Placement object

placement_id

string (limited to 24 characters)

The unique ID of the placement in the Register system. Used to identify the placement when updating or deleting.

Example: 4QWdpfb2UJM1gdhKnsyKiVkj

urn

string (limited to 6 characters)

The URN of the school. Coded according to HESA placement school field

Example: 123456

name

string, required if urn is not provided

The placement school or setting name.

Example: Hedgehogs Nursery

postcode

string (limited to 8 characters)

The postcode of the placement school or setting.

Example: AB1 2CD

Degree object

degree_id

string (limited to 24 characters)

The unique ID of the degree in the Register system. Used to identify the degree when updating or deleting.

Example: 37T2Vm9aipqSVokbhWUMjedu

country

string (limited to 2 characters), required if degree is not from the UK

The country where the degree was awarded. Coded according to the HESA degree country field

Example: US

grade

string (limited to 2 characters), required if degree is from the UK

The grade of the degree. Coded according to HESA degree class field

Example: 02

uk_degree

string (limited to 3 characters), required if degree is from the UK

The type of UK degree. Coded according to HESA degree type field

Example: 083

non_uk_degree

string, required if degree is not from the UK

The UK ENIC comparable degree type for non-UK degrees.

Example: Ordinary bachelor degree

subject

string (limited to 6 characters), required

The degree subject. Coded according to HESA degree subject field

Example: 100425

institution

string (limited to 4 characters), required if degree is from the UK

The awarding institution. Coded according to the HESA degree establishment field

Example: 0116

graduation_year

string, required

The year of graduation. Coded according to the HESA degree end date field

Example: 2012-07-31

Field lengths summary

Rule Limit
Trainee.properties.trainee_id.maxLength 24
Trainee.properties.provider_trainee_id.maxLength 20
Trainee.properties.trn.maxLength 7
Trainee.properties.first_names.maxLength 60
Trainee.properties.last_name.maxLength 60
Trainee.properties.previous_last_name.maxLength 60
Trainee.properties.sex.maxLength 2
Trainee.properties.nationality.maxLength 2
Trainee.properties.email.maxLength 80
Trainee.properties.ethnicity.maxLength 3
Trainee.properties.disability1.maxLength 2
Trainee.properties.disability2.maxLength 2
Trainee.properties.disability3.maxLength 2
Trainee.properties.disability4.maxLength 2
Trainee.properties.disability5.maxLength 2
Trainee.properties.disability6.maxLength 2
Trainee.properties.disability7.maxLength 2
Trainee.properties.disability8.maxLength 2
Trainee.properties.disability9.maxLength 2
Trainee.properties.itt_aim.maxLength 3
Trainee.properties.training_route.maxLength 2
Trainee.properties.itt_qualification_aim.maxLength 3
Trainee.properties.course_subject_one.maxLength 6
Trainee.properties.course_subject_two.maxLength 6
Trainee.properties.course_subject_three.maxLength 6
Trainee.properties.study_mode.maxLength 2
Trainee.properties.course_year.maxLength 2
Trainee.properties.course_age_range.maxLength 5
Trainee.properties.employing_school_urn.maxLength 6
Trainee.properties.lead_partner_urn.maxLength 6
Trainee.properties.fund_code.maxLength 1
Trainee.properties.funding_method.maxLength 1
Trainee.properties.training_initiative.maxLength 3
Trainee.properties.additional_training_initiative.maxLength 3
Trainee.properties.hesa_id.maxLength 17
Trainee.properties.ni_number.maxLength 9
Placement.properties.placement_id.maxLength 24
Placement.properties.urn.maxLength 6
Placement.properties.postcode.maxLength 8
Degree.properties.degree_id.maxLength 24
Degree.properties.country.maxLength 2
Degree.properties.grade.maxLength 2
Degree.properties.uk_degree.maxLength 3
Degree.properties.subject.maxLength 6
Degree.properties.institution.maxLength 4