Overview

The display advert API displays the vacancies listed on our flagship Find an Apprenticeship (FAA) website. Using this API, you are able to return a full list of all live vacancies (or subsets thereof based on parameters like distance, employer, how recently (in days) they were posted, or whether they're linked to your UKPRN if you're a training provider), or drill down into individual vacancies to return more detail.

Documents

display-advert-api.json
Uploaded schema

Who can use this API

This is primarily aimed at training providers, but anybody that wants to return a list of apprenticeship vacancies can use this API.

If you are working with a specific employer or training provider, you can request an API key from them directly, which will return results specific to that organisation. Otherwise, you can request your own unfiltered subscription by visiting the project site.

Instructions for how to subscribe to this API are available here: https://developer.apprenticeships.education.gov.uk/

Technologies

C#; JSON; RESTful

Environments

Environment Base URL
live https://api.apprenticeships.education.gov.uk/vacancies

You need to sign in to subscribe to an API environment or view your existing subscriptions.

Sign in here using GOV.UK One Login

Current release

Release name Available from
2 08 April 2026

Operations

Show additional information

GET GET list of Account Legal Entities.

Description

Get a list of Account Legal Entities that are connected to your subscription. This can be used to further filter results in GET vacancy request. If you are a provider only Accounts that have given permission for you to act on there behalf will show in the list. If you are an employer then only legal entities that have a signed agreement will be in the list. If you are not an employer or provider a forbidden response will be returned.

URL template
/accountlegalentities
Show / Hide additional information

Parameters

Name Type Location Field Description
X-Version string Header Required -
X-Version string Header Required -

Response Codes

Status code Description
200 OK
403 Forbidden

Example Request

curl -X GET \
  "https://{{baseURL}}/accountlegalentities" \
  -H "X-Version: example" \
  -H "X-Version: example"

GET GET list of course routes. The routes can then be used to filter results in `GET Vacancy` endpoint.

Description

GET list of course routes. The routes can then be used to filter results in GET Vacancy endpoint.

URL template
/referencedata/courses/routes
Show / Hide additional information

Parameters

Name Type Location Field Description
X-Version string Header Required -
X-Version string Header Required -

Response Codes

Status code Description
200 OK

Example Request

curl -X GET \
  "https://{{baseURL}}/referencedata/courses/routes" \
  -H "X-Version: example" \
  -H "X-Version: example"

GET GET list of courses.

Description

GET list of courses.

URL template
/referencedata/courses
Show / Hide additional information

Parameters

Name Type Location Field Description
X-Version string Header Required -
X-Version string Header Required -

Response Codes

Status code Description
200 OK

Example Request

curl -X GET \
  "https://{{baseURL}}/referencedata/courses" \
  -H "X-Version: example" \
  -H "X-Version: example"

GET GET list of vacancies

Description

Returns list of Vacancies based on your subscription.

  • If FilterBySubscription is true then for employer subscriptions this will automatically filter by your account.
  • If FilterBySubscription is true then for providers it will automatically filter by UKPRN.
  • If you provide a AccountLegalEntityPublicHashedId it must come from GET accountslegalentities or a forbidden result will be returned.

Examples

Get all of a subscription's vacancies sorted by age descending (oldest first):

/vacancy?Sort=AgeDesc&FilterBySubscription=true

Get all vacancies within a 20 mile radius of Coventry (52.408056, -1.510556), sorted by distance (closest first) for standards 123 and 345:

/vacancy?Lat=52.408056&Lon=-1.510556&Sort=DistanceAsc&DistanceInMiles=20&StandardLarsCode=123&StandardLarsCode=345

Get all nationwide vacancies for route 'example' posted within the last 30 days, page 5, size 10:

/vacancy?PageNumber=5&PageSize=10&Routes=example&NationWideOnly=true&PostedInLastNumberOfDays=30
URL template
/vacancy
Show / Hide additional information

Parameters

Name Type Location Field Description
ExcludeRecruitingNationally boolean Query Optional If not set returns all If `true` returns non Nation Wide apprenticeship adverts only If `false` returns all apprenticeship adverts including Nation Wide
EmployerName string Query Optional -
PageNumber integer Query Optional Page number you wish to get - defaults to 1
PageSize integer Query Optional Page size you wish to get - defaults to 10
AccountLegalEntityPublicHashedId string Query Optional If `FilterBySubscription` is `true` then you can supply the `AccountLegalEntityPublicHashedId` you wish to filter by, obtained from `GET AccountLegalEntities`. You can only supply a value that is linked to your account, or as a Provider you have permission to act on behalf of.
Ukprn integer Query Optional The UKPRN which you wish to return adverts by. If `FilterBySubscription` is `true` and you have a Provider subscription, the value in your subscription will be used.
Routes array Query Optional You can supply a maximum of 2 routes to be filtered by, these can be obtained from `GET referencedata/courses/routes`. If there are `StandardLarsCode` values supplied the route filtering will be ignored.
Lat number Query Optional Latitude to search from, must be supplied with `Longitude` and `DistanceInMiles`
Lon number Query Optional Longitude to search from, must be supplied with `Latitude` and `DistanceInMiles`
Sort string Query Optional If not supplied, defaults to `VacancySort.AgeDesc` `AgeDesc` From newest to oldest apprenticeship adverts `AgeAsc` From oldest to newest apprenticeship adverts `DistanceDesc` From furthest to closest away apprenticeship adverts - can only be used if `Lat`, `Lon` and `DistanceInMiles` supplied `DistanceAsc` From closest to furthest away apprenticeship adverts - can only be used if `Lat`, `Lon` and `DistanceInMiles` supplied `ExpectedStartDateDesc` Ordering by apprenticeship adverts that are closest to starting `ExpectedStartDateAsc` Ordering by apprenticeship adverts that are further in the future to starting
DistanceInMiles integer Query Optional To be used with `Lat` and `Lon` to provide apprenticeship adverts that fall into that radius
PostedInLastNumberOfDays integer Query Optional -
StandardLarsCode array Query Optional The Id or Ids of the standard you are searching for - can be obtained from `GET referencedata/courses`. If supplied will cause any route filtering to be ignored
FilterBySubscription boolean Query Optional If set to `true` - then filters by the AccountId or UKPRN linked to your subscription.
X-Version string Header Required -
AdditionalDataSources array Header Optional -
X-Version string Header Required -

Response Codes

Status code Description
200 OK
403 Forbidden

Example Request

curl -X GET \
  "https://{{baseURL}}/vacancy" \
  -H "X-Version: example" \
  -H "X-Version: example"

GET GET vacancy by reference number

Description

Returns details of a specific vacancy. If no vacancy found then a 404 response is returned.

URL template
/vacancy/{vacancyReference}
Show / Hide additional information

Parameters

Name Type Location Field Description
vacancyReference string Path Required Vacancy reference in the following format 10001122
X-Version string Header Required -
X-Version string Header Required -

Response Codes

Status code Description
200 OK
404 Not Found

Example Request

curl -X GET \
  "https://{{baseURL}}/vacancy/{vacancyReference}" \
  -H "X-Version: example" \
  -H "X-Version: example"
Back to top