Get started

About the Recruitment and Display adverts APIs

Recruitment API
Create an advert on Find an apprenticeship using your existing systems.

Recruitment API Sandbox
Test creating an advert on Find an apprenticeship using your existing systems.

Display advert API
Display recruitment adverts from Find an apprenticeship.

Using our APIs if you are working with an employer or training provider

You need the employer or provider to give you an API key. They can do this for the Recruitment API and the Display adverts API using their Apprenticeship service account.

The API key the employer or training provider will send to you is linked to their account and provides additional functionality, so use that one.

You can view the API documentation now, using the links at the top of the page. You can read the documentation but will not be able to call the API until the employer or provider gives you an API key.

Using our display adverts API if you are working independently

If you are not working with an employer or training provider and don’t have an apprenticeship service account, you can use the Display adverts API to show adverts from Find apprenticeship training on any website.

If you are not a software developer, you'll need someone with technical knowledge to connect your system with the API.

You will need to create an account or sign in to get an API key to use the display advert API.

You can view the API, but you will need a key before you can call the API.

RESTful APIs

Apprenticeship service APIs are RESTful. In a RESTful style of API, data resources are given unique URLs and are manipulated through standard HTTP verbs such as:

  • GET to request a resource
  • POST to create a resource
  • PUT to replace a resource
  • DELETE to remove a resource

All Apprenticeship Service APIs use the JSON data standard as the content type. JSON, or JavaScript Object Notation, is an open, standard format for storing and exchanging data. It can be used as a data format by any programming language, which makes it ideal for HTTP-based API services.

API authentication

Apprenticeship Service APIs require authentication credentials to be sent with each request. Credentials are sent in the form of an API key which is contained within a custom HTTP request header.

The custom request header must be named Ocp-Apim-Subscription-Key and you must use your API key as the value for this custom request header in each API request.

For example:

GET https://api.apprenticeships.education.gov.uk/vacancies/{yourAction} HTTP/1.1
Host: api.apprenticeships.education.gov.uk
X-Version: 1
Ocp-Apim-Subscription-Key:

In the case of an authentication failure, the API request will return a HTTP 401 response with a message giving the reason for the authentication failure, either:

  • the Ocp-Apim-Subscription-Key header is missing
  • the subscription key given as the header value is invalid

If you are accessing different APIs, they will have their own API key.

The following sections provide information on how to obtain your API key(s).

API Versioning

All Apprenticeship Service APIs are versioned. This ensures API consumers receive a predictable response from an API, even when a newer version of an API is released.

The version of the API you require must be specified within a custom HTTP request header.

The custom request header must be named X-Version and you must specify the version (as a whole number) as the value for this custom request header in each API request.

For example:

GET https://api.apprenticeships.education.gov.uk/vacancies/{yourAction} HTTP/1.1
Host: api.apprenticeships.education.gov.uk
X-Version: 1
Ocp-Apim-Subscription-Key:

In case of a version check failure, you will receive a HTTP 404 response with a message giving the reason for the failure, either:

  • the X-Version header is missing
  • the version specified does not exist

The Apprenticeship service maintains the current version of an API, as well as the previous version for a limited period of time. 3 months after the release of a new version of an API, the previous version will be decommissioned, so you will need to update to the latest version within 3 months of the new one becoming available.

API Rate Limiting

Rate limiting is applied to the Apprenticeship Service APIs to ensure a high quality service is delivered for all users.

You can make up to 150 requests within a 5 minute period. If you exceed this limit, you will receive a 429 Too Many Requests HTTP status code for each request made within the rest of the 5 minute timeframe. At the end of the time period, your rate limit will reset back to 150 requests.

API Key Security

It is important to keep your API keys secure. This will prevent them from being discovered, your account from being compromised and your rate-limit quota from being exceeded.

Do not embed API keys in your code

Storing subscription keys in your application code increases the risk that they will be discovered, particularly if any of your source code is made public or it can be viewed by people who should not have access to the API key. Instead, you should consider storing them inside environment variables or configuration.

Do not store API keys in your source tree

If you store API keys in files, for example, configuration or environment files, do not store them inside the application source tree. If all or part of the source is made public, the API key may be compromised.

Regenerate your API keys

Regenerate your API keys regularly, including with each application release, to reduce the chance that an API key will be discovered.

Environments

Apprenticeship Service APIs are hosted in our live environment where production data is made available. A sandbox environment is also provided for some APIs, which run the same API versions as live to allow software developers to test their integration with Apprenticeship Service APIs in a safe place.