`GET /trainees`

Warning The v2026.0 version is currently available for testing in the sandbox environment only. It is not yet available in production.

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/v2026.0/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_1": "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,
          "defer_date": "2023-10-17",
          "defer_reason": null,
          "recommended_for_award_at": null,
          "trainee_start_date": "2023-09-04",
          "reinstate_date": null,
          "course_min_age": 5,
          "course_max_age": 11,
          "course_subject_2": null,
          "course_subject_3": 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,
          "training_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,
          "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": "13914",
          "employing_school_urn": null,
          "training_partner_ukprn": null,
          "training_partner_urn": null,
          "fund_code": "7",
          "course_year": "2",
          "funding_method": "4",
          "itt_aim": "201",
          "itt_qualification_aim": "004",
          "ni_number": null,
          "previous_last_name": null,
          "additional_training_initiative": null,
          "withdrawal_future_interest": null,
          "withdrawal_trigger": null,
          "withdrawal_reasons": null,
          "withdrawal_another_reason": null,
          "withdrawal_safeguarding_concern_reasons": null,
        }
      ]
    }

HTTP 401 - Unauthorized

    {
      "error": "Unauthorized"
    }

HTTP 404 - Not found

    {
      "errors": [
        {
          "error": "NotFound",
          "message": "No trainees found"
        }
      ]
    }

HTTP 422 - Unprocessable Entity

    {
      "message": "Validation failed: 1 error prohibited this request being run",
      "errors": {
        "status": [
          "busy is not a valid status"
        ]
      }
    }