Using Apprenticeship service APIs

This page is for developers who want to use Apprenticeship service APIs.

Our APIs

Display advert API

Get and display adverts from Find an apprenticeship.

Recruitment API

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

Recruitment API Sandbox

Test your implementation of the Recruitment API.

Track Apprenticeship Progress API

Share data on the progress of your apprenticeships.

Track Apprenticeship Progress API Sandbox

Test your implementation of the Track apprenticeship progress API.

Using our APIs

If you're working with an employer

You can use the:

You’ll need to get an API key from the employer you’re working with before you can call our APIs.

The employer will find these API keys in the Adverts section of their apprenticeship service account. At the bottom of the page, there’s a link for Recruitment APIs.

If an employer deletes their API key, your application will stop working.

If you're working with a training provider

You can use the:

You’ll need to get an API key from the training provider you’re working with before you can call our APIs.

The training provider will find these API keys in the Developer APIs section on their apprenticeship service account homepage.

If the training provider deletes their API key, your application will stop working.

If you're working on your own

You can only use the Display advert API.

You will need an API key to call the Display advert API. You can create an account to get an API key.

If you already have an account, you can sign in to get an API key.

How our APIs work

Our APIs are RESTful and use JSON.

Authentication

You need an API key to call our APIs. Each API requires a different key. How to get keys is detailed in the Using our APIs section.

Every request to our API must contain your API key. Use your API key as the value for the HTTP request header Ocp-Apim-Subscription-Key.

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:

The API will return a 401 status code if you do not include this field or if the API key is invalid.

Keeping your API key secure

Do not:

embed API keys in your code - consider storing them inside environment variables or configuration.
store API keys in your application source tree - if all or part of the source is made public, the API key may be compromised.

Regenerate your API keys regularly, including with each application release. This will reduce the chance of an API key being discovered.

Versioning

Our APIs are versioned. This means the API will keep acting predictably even after we’ve released a new version.

After a new release version of the API, the old version will be maintained for 3 months only.

Every request to our API must include which API version you are calling. State which version you want for the HTTP request header X-version. This value must be a whole number.

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:

The API will return a 404 status code if you do not include this field or if the version number is invalid.

Rate limiting

We use rate limiting to protect the quality of our APIs.

You can make up to 150 requests within a 5 minute period.

The API will return a 429 status code if you exceed this request limit. After the end of the 5 minute period, your request limit will reset back to 150 requests for the next period.