Get started

About the Apprenticeship Service APIs

Track Apprenticeship Progress API
Share data on the progress of your apprenticeships

Track Apprenticeship Progress API Sandbox
Share data on the progress of your apprenticeships

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

If you’re working with an employer or training provider, they can get you an API key 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.

The training provider or employer can delete the API keys from within their account. Deleting the key will stop applications using the key from working.

Using our APIs if you’re working independently

If you’re not working with a training provider or employer, you can access the following APIs:

Display adverts API

You will need to create an account to access the API keys.

If you already have an account, you can sign in to access the API keys.

Apprenticeship Service APIs you can use if working independently

Display advert API
Display recruitment adverts from Find an apprenticeship.

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.