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 [email protected]

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 ([email protected])	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