Guidance

Apprenticeship service - Upload specification for training providers Version 6: Effective 1 August 2022 to February 2024

Updated 3 October 2023

Applies to England

Intended audience

This technical document is for people responsible for uploading data to the apprenticeship service and MI system design (including MI managers, commercial software suppliers and own software writers).

Introduction

File upload is an enhanced feature within the apprenticeship service (the Service) that allows training providers to add one or more apprentices for one or more employers at the same time.

You can only use file upload to add new apprentices, it cannot be used to update or amend apprentice details.

Employers will still need to approve all new apprentices that you add.

How to create a file

The file is a comma separated values (CSV) file. In most cases, your learner management system (LMS) should be able to create a CSV file that you can use for the upload process. If your system is not able do this, a file upload template is available to download.

If you are adding to an existing cohort, you need to make sure the CohortRef is completed with the cohort reference. If you leave the CohortRef empty a new cohort will be created automatically for each employer (if you have employer permissions to create cohorts on their behalf).

You need to include the AgreementID to identify each employer.

How and when to submit a file

File upload can be found in the ‘add apprentices’ section on the home page. You can add apprentices to cohorts that have already been created or start a new one (if you have employer permissions to do this on their behalf).

The apprentice record must be added and approved by both you and the employer before the Education and Skills Funding Agency will release any funds from the employer’s account.

Files can be submitted at any time of the month.

File validation and error correction

Validation rule checks are carried out on any file you upload. The rules check:

a. the format of your file is correct

b. the file is no larger than 100 lines

c. all mandatory fields have been entered

d. the field data types are valid

e. the field lengths are valid

f. data for consistency across related fields, for example there are no existing (“overlapping”) apprenticeships for the same learner on the dates you’ve provided

g. the cohort is editable

h. the date of birth is valid at the start date of the apprenticeship

If your file upload fails any validation checks, the entire file will be rejected, and no data will be uploaded to the Service. You will then need to review and correct any errors in your LMS or template and re-upload the file.

Updating records

When the apprentices have been added and approved by both the employer and training provider no further changes can be made through the file upload process, but amendments can be made to apprentice records in the ‘Manage apprentices’ section of the Service.

Transfer funds

For apprenticeships that are being paid for using transferred funds from another employer, the cohort must be created first by the employer. The cohort reference will then need to be added to CohortRef field in your LMS or on the template.

Funding reservations

For employers that do not pay the apprenticeship levy, the reservation will automatically be created when using the upload file function; it will not use any existing reservations. If the employer has reached their reservation limit for the financial year, you will not be able to add apprentices.

If a reservation has already been separately created, it will not be used for adding apprentices in file upload. It will need to be deleted from the Service manually.

Changes effective from 1 August 2022

We have added two new fields for apprenticeship starts on or after 1 August 2022.

If there is any recognised prior learning for an apprenticeship from this date we then capture:

  • the reduction in weeks

  • the reduction in price, in whole pounds

Table of fields and data definitions

Field Name Data Type Size Format/Valid entries Mandatory
CohortRef String 20 Valid cohort N

AgreementID String 6 Valid agreement ID Y

ULN Bigint 10 1000000000 – 9999999998 Y

FamilyName String 100   Y

GivenNames String 100   Y

DateOfBirth Date 10 YYYY-MM-DD Y

EmailAddress Email 200 Valid email address Y

StdCode Int 5 Valid entry from LARS Y

StartDate Date 10 YYYY-MM-DD Y

EndDate string 7 YYYY-MM Y

TotalPrice Int 6 1 - 100000 Y

EPAOrgID String 7   N

ProviderRef String 20   N

RecognisePriorLearning Boolean   True / False, Yes / No, 1 / 0 Y

DurationReducedBy Int 3 1 - 260 Y if RPL = True

PriceReducedBy Int 5 5 - 18000 Y if RPL = True

Cohort reference
Definition The reference from the apprenticeship service
Data definitions
   
Field name CohortRef Mandatory N
Field length 20 Data type string
Notes
• The cohort reference uniquely identifies a specific group of apprentices being uploaded to the apprenticeship service for one employer. There can be one or multiple apprentices in a cohort.
• The cohort must be in an editable status (‘Draft’ or ‘Ready for review’). Cohorts that are currently with the employer or with a transfer-sending employer cannot be added to a file.
• If the field is blank, a new cohort will be created for all apprentices in the upload file with the same employer. To do this, the employer must have given the training provider permission to add apprentices on their behalf.
Agreement ID
Definition The identifier for the employer organisation
Data definitions
   
Field name AgreementID Mandatory Y
Field length 6 Data type string
Notes
• The Agreement ID uniquely identifies the employer to the Service when adding apprentices through file upload
• If the ‘CohortRef’ field is populated, then the Agreement ID must match the employer on the cohort
• If the ‘CohortRef’ field is not populated, then the Agreement ID must match an employer who has given the training provider permission to add apprentices on their behalf
Unique learner number
Definition The apprentice’s unique learner number (ULN), as held on the Learner Register, obtained from the Learning Records Service (LRS)
Data definitions
   
Field name ULN Mandatory Y
Field length 10 Data type bigint
Valid entries 1000000000 – 9999999998    
Notes
• The ULN recorded here must be the same as the one recorded for the apprentice in the ILR in order for funding payments to be generated
• The ULN must be real; the value of 9999999999 cannot be used
• The ULN must be unique within the cohort and unique within the Service for the duration of the apprenticeship: that is, there cannot be other apprenticeship records with the same ULN that would overlap with the start and end date of this apprenticeship
Family name
Definition The surname (last name or family name) of the apprentice
Data definitions
   
Field name FamilyName Mandatory Y
Field length 100 Data type string
Notes
• The name recorded here should be the same as the one recorded for the apprentice in the ILR and the LRS
Given names
Definition The Forenames (first names or given names) of the apprentice
Data definitions
   
Field name GivenName Mandatory Y
Field length 100 Data type string
Notes
• The name(s) recorded here should be the same as the one recorded for the apprentice in the ILR and the LRS
Date of birth
Definition The date of birth of the apprentice
Data definitions
   
Field name DateOfBirth Mandatory Y
Field length 10 Data type date
Valid entries A valid date, using the date pattern YYYY-MM-DD    
Notes
• The date of birth recorded here should be the same as the one recorded for the apprentice in the ILR and the LRS.
• The date of birth is used to verify the learner’s age is between 15 and 114 at the start of the apprenticeship

• If you are using Microsoft Excel to edit or view a bulk upload file please note that it will apply the default format of dd/mm/yyyyy whenever you open the file and so this will need to be reformatted to the valid format of yyyy-mm-dd before you save and upload the file. If you want to check the file without affecting the date format, then you can open it using Notepad.
Email address
Definition The email address of the apprentice
Data definitions
   
Field name EmailAddress Mandatory Y
Field length 200 Data type string
Valid entries A valid email address, in the format of username@domain.top-domain    
Notes
• This field holds the email address of the apprentice
• The email address must be unique within the cohort and unique within the Service for the duration of the apprenticeship: that is, there cannot be other apprenticeship records with the same email address that would overlap with the start and end date of this apprenticeship
Apprenticeship standard code
Definition The apprenticeship standard code for the learning being undertaken
Data definitions
   
Field name StdCode Mandatory Y
Field length 5 Data type int
Valid entries A valid entry from the standard code list in the LARS database    
Notes
• The Standard code recorded here must be the same as the one recorded for the apprentice in the ILR in order for funding payments to be generated
•If there are multiple versions of the standard, the standard version is calculated based on the StartDate
• If the standard version has associated options, the option will be set to ‘not known’ by default. The user will need to set the option separately post-upload
Start date
Definition The day, month and year in which the apprenticeship funding is planned to start
Data definitions
   
Field name StartDate Mandatory Y
Field length 10 Data type date
Valid entries A valid date, using the date pattern YYYY-MM-DD    
Notes
 
• This field should record the day, month and year in which funding can start for this apprentice. This will be the same initially as the date on which training starts with this provider
• The learning start date recorded on the ILR must be on or after the start date recorded here in order for funding payments to be released
• The start date must be on or after 1 May 2017 and after 1 May 2018 for transfer-funded apprenticeships

If you are using Microsoft Excel to edit or view a bulk upload file, please note that it will apply the default format of dd/mm/yyyyy whenever you open the file and so this will need to be reformatted to the valid format of yyyy-mm-dd before you save and upload the file. If you want to check the file without affecting the date format, then you can open it using Notepad  
End date
Definition The month and year by which the provider and apprentice plan to complete the apprenticeship programme
Data definitions
   
Field name EndDate Mandatory Y
Field length 7 Data type string
Valid entries A valid date, using the date pattern YYYY-MM    
Notes
• This field should record the month and year in which the apprentice plans to complete their programme and the period over which funding will be released
• This date must include both the training and end-point assessment period
• This date must be later than the start date (StartDate)
Total price
Definition The negotiated price for the training and end-point assessment. Actual amount in pounds to the nearest whole pound (excluding VAT)
Data definitions
   
Field name TotalPrice Mandatory Y
Field length 6 Data type int
Valid entries 1-1000000    
Notes
• The total price recorded here is the total cost of the apprenticeship and includes both the training cost and the cost of end point assessment. For funding payments to be generated the data recorded must match the total price recorded in the ILR, which is the sum of the training price and assessment price fields held in the ILR.
• Only include the end point assessment cost if it is known at the start of the apprenticeship. Do not include an estimated value for the end point assessment cost. The total cost can be amended at a later point on the service once the end point assessment cost has been confirmed.
End-point assessment organisation
Definition The identifier for the organisation that will be carrying out the end point assessment for this apprenticeship
Data definitions
   
Field name EPAOrgID Mandatory N
Field length 7 Data type string
Valid entries A valid end point assessment organisation id from the register of end-point assessment organisations in the format EPAXXXX where X is an integer from 0-9    
Notes
The end point assessment organisation is not currently being recorded and so does not need to be completed in the bulk upload. You will be asked to add this information later during the apprentice’s programme.
Provider Reference
Definition This field collects data specified by the provider for their own use
Data definitions
   
Field name ProviderRef Mandatory N
Field length 20 Data type string
Valid entries      
Notes
• This field is optional for use by the provider to record their own reference. The employer will not be able to see this information
• You must not include personal data such as the apprentice’s name in this field
Recognise Prior Learning
Definition Identifies if price has been reduced due to recognised prior learning
Data definitions
   
Field name RecognisePriorLearning Mandatory Y
Field length   Data type boolean
Valid entries True / False, Yes / No, 1 / 0    
Notes
• This field should record if prior learning has resulted in a reduction in price and duration of this apprenticeship
• This field is mandatory if the apprenticeship start date is on or after 1 August 2022
Duration reduced due to prior learning
Definition The number of weeks the apprenticeship has been reduced by in recognition of prior learning
Data definitions
   
Field name DurationReducedBy Mandatory N
Field length 3 Data type int
Valid entries 0-999    
Notes
• This field should record the number of weeks the apprenticeship has been reduced by because of prior learning
• This field is mandatory if RecognisePriorLearning is true
• Data entered for apprenticeships that start prior to 1 August 2022 is ignored
Price reduced due to prior learning
Definition The price the apprenticeship has been reduced by in recognition of prior learning
Data definitions
   
Field name PriceReducedBy Mandatory N
Field length 6 Data type int
Valid entries 0-100000    
Notes
• This field should record the price the apprenticeship has been reduced by because of prior learning
• This field is mandatory if RecognisePriorLearning is true
• Data entered for apprenticeships that start prior to 1st August 2022 is ignored

Validation Rules

Version 7 – The validation rules have been revised in this version of the specification.

Rule Name Error Condition Error message
CohortRef_01 Field length > 20 Enter a valid Cohort Ref
CohortRef_02 CohortRef is not valid Enter a valid Cohort Ref
CohortRef_03 Cohort is not valid for this training provider Enter a valid Cohort Ref
CohortRef_04 Cohort is not valid for this employer Enter a valid Cohort Ref
CohortRef_05 Cohort status = With employer You cannot add apprentices to this cohort, as it is with the employer. You need to add this learner to a different or new cohort
CohortRef_06 Cohort status = With transfer sending employer You cannot add apprentices to this cohort, as it is with the transfer-sending employer. You need to add this learner to a different or new cohort
CohortRef_07 Cohort is a change of employer / training provider request You cannot add apprentices to this cohort. You need to add this learner to a different or new cohort
CohortRef_08 The cohort cannot be approved You cannot add apprentices to [cohort ref], as the cohort contains incomplete records. You need to complete all records before you can add into this cohort
CohortRef_09 The cohort cannot be approved You cannot add apprentices to [cohort ref], as this cohort contains an overlapping training date. You need to resolve any overlapping training date errors before you can add to this cohort
CohortRef_10 The cohort cannot be approved You cannot add apprentices to [cohort ref], as this cohort contains an overlapping email address. You need to enter a unique email address before you can add to this cohort
AgreementID_01 AgreementID is Null / Empty Agreement ID must be entered
AgreementID_02 Field length > 6 Enter a valid Agreement ID
AgreementID_03 AgreementID is not a valid Agreement ID Enter a valid Agreement ID
AgreementID_04 The AgreementID matches an employer that has not given provider permission to add apprentices The employer must give you permission to add apprentices on their behalf
AgreementID_05 AgreementID matches an employer with no remaining reservation allowance The employer has reached their reservations limit. Contact the employer
AgreementID_06 AgreementID matches an employer with insufficient remaining reservation allowance for all apprentices being added The employer has reached their reservations limit. Contact the employer
AgreementID_07 AgreementID matches an employer which has not given the provider permission to add apprentices (including the permission to reserve funds) You do not have permission to add apprentice records for this employer, so you cannot reserve funds on their behalf
AgreementID_08 AgreementID matches an employer which has not accepted a valid version of the legal agreement You cannot add apprentices for this employer as they need to accept the agreement with the DfE
ULN-01 ULN is Null/Empty Enter a 10-digit unique learner number
ULN_02 ULN fails the Regular Expression: ^[1-9]{1}[0-9]{9}$ Enter a 10-digit unique learner number
ULN_03 ULN = 9999999999 The unique learner number of 9999999999 is not valid
ULN_04 ULN is not unique within the file The unique learner number has already been used for an apprentice in this file
ULN_05 ULN is not unique within the cohort The unique learner number has already been used for an apprentice in this cohort
FamilyName_01 FamilyName is Null / Empty Last name must be entered
FamilyName_02 Field length > 100 Enter a last name that is not longer than 100 characters
GivenNames_01 GivenNames is Null / Empty First name must be entered
GivenNames_02 Field length > 100 Enter a first name that is not longer than 100 characters
DateOfBirth_01 DateOfBirth is Null / empty Enter the apprentice’s date of birth using the format yyyy-mm-dd, for example 2001-04-23
DateOfBirth_02 DateOfBirth is an invalid date value Enter the apprentice’s date of birth using the format yyyy-mm-dd, for example 2001-04-23
DateOfBirth_03 DateOfBirth is not in format yyyy-mm-dd Enter the apprentice’s date of birth using the format yyyy-mm-dd, for example 2001-04-23
DateOfBirth_04 StartDate - DateOfBirth < 15 years The apprentice’s date of birth must show that they are at least 15 years old at the start of their training
DateOfBirth_05 StartDate - DateOfBirth < 115 years The apprentice’s date of birth must show that they are not older than 115 years old at the start of their training
EmailAddress_01 EmailAddress is Null/ Empty Email address must be entered
EmailAddress_02 Field length > 200 Enter an email address that’s not longer than 200 characters
EmailAddress_03 Email address is not in valid format for example (username@domain.top-domain) Enter a valid email address
EmailAddress_04 EmailAddress is not unique within the file The email address has already been used for an apprentice in this file
EmailAddress_05 EmailAddress is not unique within the cohort The email address has already been used for an apprentice in this cohort
StdCode_01 StdCode is null / empty Standard code must be entered
StdCode_02 Field length > 5 Enter a valid Standard code
StdCode_03 StdCode is not found in LARS Lookup Enter a valid Standard code
StartDate_01 StartDate is Null/Empty Enter the start date using the format yyyy-mm-dd, for example 2021-09-01
StartDate_02 StartDate an invalid date value Enter the start date using the format yyyy-mm-dd, for example 2021-09-01
StartDate_03 StartDate is not in format yyyy-mm-dd Enter the start date using the format yyyy-mm-dd, for example 2021-09-01
StartDate_04 StartDate is < 2017-05-01 The start date must not be earlier that May 2017
StartDate_05 StartDate is > end of Current AY + 1 year The start date must be no later than one year after the end of the current teaching year
StartDate_06 Cohort is for a funds-transfer AND StartDate < 01-05-2018 The start date for apprenticeships funded through a transfer must not be earlier than May 2018
StartDate_07 StartDate - The course is no longer valid on StartDate This training course is only available to apprentices with a start date effective from [month] [year]
StartDate_08 StartDate - The course is not yet valid on the StartDate This training course is only available to apprentices with a start date effective from [month] [year]
StartDate_09 StartDate - an existing record with the same ULN The start date overlaps with existing training dates for the same apprentice
StartDate_10 StartDate - an existing record with the same email address The start date overlaps with existing training dates for an apprentice with the same email address
StartDate_11 Employer is non-levy paying AND StartDate < the start of funding reservation window The start date for this learner cannot be before [dd/mm/yyyy]. You cannot backdate reserve funding
StartDate_12 Employer is non-levy paying AND StartDate > the start of funding reservation window The start date for this learner cannot be after [dd/mm/yyyy]. You cannot reserve funding more than [X] months in advance
EndDate_01 EndDate is Null/empty Enter the end date using the format yyyy-mm, for example 2019-02
EndDate_02 EndDate is an invalid date value Enter the end date using the format yyyy-mm, for example 2019-02
EndDate_03 EndDate is not in format yyyy-mm Enter the end date using the format yyyy-mm, for example 2019-02
EndDate_04 EndDate < StartDate Enter an end date that is after the start date
EndDate_05 EndDate < an existing record with the same ULN The end date overlaps with existing training dates for the same apprentice
EndDate_06 EndDate < an existing record with the same email address The end date overlaps with existing training dates for an apprentice with the same email address
TotalPrice_01 TotalPrice = Null / Empty Enter the total cost of training in whole pounds using numbers only
TotalPrice_02 TotalPrice is non-numeric Enter the total cost of training in whole pounds using numbers only
TotalPrice_03 TotalPrice = 0 The total cost must be more than £0
TotalPrice_04 TotalPrice > 100,000 The total cost must be £100,000 or less
EPAOrgID Field length > 7 The EPAO ID must not be longer than 7 characters
ProviderRef_01 Field length > 20 The Provider reference must not be longer than 20 characters
RecognisePriorLearning_01 Field is null / empty AND StartDate >= 01.08.2022 Enter whether prior learning is recognised
RecognisePriorLearning_02 Field is NOT null / empty AND StartDate < 01.08.2022 RPL data should not be entered when the start date is before 1 August 2022
RecognisePriorLearning_03 Value is NOT True, False, 0, 1, Yes, No Enter whether prior learning is recognised as ‘true’ or ‘false’
DurationReducedBy_01 Field is null / empty AND RecognisePriorLearning is True AND IsDurationReducedByRPL is True/1/Yes You must enter the duration this apprenticeship has been reduced by due to prior learning
DurationReducedBy_02 Field is NOT null / empty AND RecognisePriorLearning is True AND IsDurationReducedByRPL is False/0/No The duration this apprenticeship has been reduced by due to prior learning should not be entered when reduction of duration by RPL is false
DurationReducedBy_03 Field is NOT null / empty AND RecognisePriorLearning is False/0/No The duration this apprenticeship has been reduced by due to prior learning should not be entered when recognise prior learning is false
DurationReducedBy_04 Value is greater > 260 AND RecognisePriorLearning is True AND IsDurationReducedByRPL is True/1/Yes Reduction in duration must be 260 weeks or less
DurationReducedBy_05 Value is BELOW 1, or a NEGATIVE number AND RecognisePriorLearning is True/1/Yes Reduction in duration must be 1 week or more
DurationReducedBy_06 Value entered are NOT a single value (eg: User have entered “1000 1000”) AND RecognisePriorLearning is True/1/Yes Reduction in duration must be a number between 1 and 260
DurationReducedBy_07 Value entered is an alpha-numeric number AND RecognisePriorLearning is True/1/Yes Reduction in duration must be a number between 1 and 260
DurationReducedBy_08 Value entered is a special character AND RecognisePriorLearning is True/1/Yes Reduction in duration must be a number between 1 and 260
DurationReducedBy_09 Value entered is a has Spaces before or after the number AND RecognisePriorLearning is True/1/Yes Reduction in duration must be a number between 1 and 260
PriceReducedBy _01 Field is null / empty AND RecognisePriorLearning is True Enter the total price reduction due to RPL
PriceReducedBy_02 Field is NOT null / empty AND RecognisePriorLearning is False The price this apprenticeship has been reduced by due to prior learning should not be entered when recognise prior learning is false
PriceReducedBy_03 Value contains non-numeric characters The price this apprenticeship has been reduced by in whole pounds due to prior learning using numbers only
PriceReducedBy_04 Value > 18000 AND RecognisePriorLearning is True Total price reduction due to RPL must be 18,000 or less
PriceReducedBy_05 PriceReducedBy < 100, or a NEGATIVE number AND RecognisePriorLearning is True Total price reduction due to RPL must be £5 or more
PriceReducedBy_06 Value is NOT a single value (eg: User has entered “1000 2000”) AND RecognisePriorLearning is True Total price reduction due to RPL must be a number between 5 and 18,000
PriceReducedBy_07 User has entered an ALPHA-NUMERIC number AND RecognisePriorLearning is True Total price reduction due to RPL must be a number between 5 and 18,000
PriceReducedBy_08 User has entered a SPECIAL CHARACTER AND RecognisePriorLearning is True Total price reduction due to RPL must be a number between 100 and 18,000
PriceReducedBy_09 User has SPACES BEFORE or AFTER the number AND RecognisePriorLearning is True Total price reduction due to RPL must be a number between 100 and 18,000