Use the API to send data

The Vehicle Recalls API allows manufacturers to add and update recall data on DVSA’s MOT digital services in real-time.

1. Getting started
2. Authentication
3. Open a new recall for a single vehicle
4. Update a vehicle’s repair status
5. Get all recall information for a single vehicle
6. Delete a recall from a vehicle
7. Error codes
8. Testing the API
9. Rate limits
10. API reference

Getting started

DVSA will contact you to onboard to the service.

As part of onboarding, you need to provide a team email address. This email address is used to contact your organisation if there are technical issues with the API, so it should not belong to only one individual.

When you are onboarded, you will receive:

• a client ID
• a client secret
• a scope URL
• an access token URL
• an API key

Authentication

The API uses OAuth 2.0 with the client credentials flow for authentication and authorisation.

You need to use the credentials provided by DVSA to generate an access token, which is required in the header of each request to the API, alongside your API key.

Generating the token

Access tokens are issued by Microsoft Azure Active Directory.

Use this command to generate the token:

curl --request POST --url 'https://{yourDomain}/oauth/token' --header 'content-type: application/x-www-form-urlencoded' --data grant_type=client_credentials --data client_id=YOUR_CLIENT_ID_HERE --data client_secret=YOUR_CLIENT_SECRET_HERE --data scope=YOUR_API_SCOPE_HERE

The token URL will be sent in full with your credentials. Access tokens are valid for 35 minutes from issue.

Cache the access token. This will avoid errors caused by too many requests.

You can use the Microsoft Authentication Library (MSAL), which caches and refreshes tokens automatically.

Response body

{
  "token_type": "Bearer",
  "expires_in": 1199,
  "ext_expires_in": 1199,
  "access_token": "issued-access-token"
}

Each request to the Vehicle Recalls API must have the following request headers:

"Authorization": "Bearer { issued access token }"
"X-API-Key": "{ issued api key }"

Requesting a new client secret

Your client secret is valid for 2 years. You will be notified by email 30 days before it is due to expire.

You can obtain a new client secret by sending a request to the PUT /credentials endpoint.

Response body example

If the request is successful, you will receive a JSON object as a response. Here is an example of a successful response:

{
  "clientSecret": "your-new-client-secret-value"
}

See more about how to use the PUT /credentials endpoint in the OpenAPI Specification page.

Open a new recall for a single vehicle

To open a new recall for a single vehicle, use this endpoint:

POST /recalls/

What you need to provide

Request body

Field	Description	Example
vin	Vehicle identification number	12345678910
manufacturerCampaignReference	Your recall campaign reference	CAR/REF1
dvsaCampaignReference	DVSA campaign reference	R/123/20
recallCampaignStartDate	The start date for the recall in the format YYYY-MM-DD	2024-04-01

Constraints

Field	Constraint	Required
vin	Cannot be empty	Yes
manufacturerCampaignReference	Cannot be empty Maximum 50 characters long Allowed characters: a-z, A-Z, 0-9, -, _, \, /	Yes
dvsaCampaignReference	Maximum 50 characters long Allowed characters: a-z, A-Z, 0-9, -, _, \, /	No
recallCampaignStartDate	Cannot be empty	Yes

Example input

{
  "vin": "123456789AC",
  "manufacturerCampaignReference": "CAR/1",
  "dvsaCampaignReference": "DVSA/1",
  "recallCampaignStartDate": "2024-03-30"
}

What to expect from the response

{
  "manufacturer": "ABC",
  "recall": {
    "vin": "123456789",
    "manufacturerCampaignReference": "CAR/1",
    "dvsaCampaignReference": "R/123/001",
    "recallCampaignStartDate": "2024-03-30"
  }
}

Update a vehicle’s repair status

To mark a vehicle’s repair status as FIXED, use this endpoint:

PUT /recalls/vin/{vin}

This means the vehicle will no longer show as having an open recall on MOT digital services.

You can also use this endpoint to update the vehicle’s repair status back to NOT_FIXED, if it was previously marked as repaired in error.

What you need to provide

Path parameters

Parameter	Description	Required	Example
vin	Vehicle identification number	Yes	12345678910

Query string parameters

Field	Description	Required	Example
manufacturerCampaignReference	Your recall campaign reference	Yes	CAR/REF1
dvsaCampaignReference	DVSA campaign reference	No	R/123/20

Request body

Field	Description	Required	Example
repairStatus	Whether the recall should be marked as FIXED or NOT_FIXED	Yes	FIXED
rectificationDate	Date the recall was fixed	If repairStatus is FIXED	2024-04-01

Example input

To mark a vehicle’s repair status as fixed:

{
  "repairStatus": "FIXED",
  "rectificationDate": "2024-03-30"
}

To revert a vehicle’s repair status to NOT_FIXED:

{
  "repairStatus": "NOT_FIXED"
}

Get all recall information for a single vehicle

To find out all the recall information DVSA holds for a specified VIN, use this endpoint:

GET /recalls/vin/{vin}

What you need to provide

Path parameters

Parameter	Description	Required	Example
vin	Vehicle identification number	Yes	12345678910

Query String Parameters

Field	Description	Required	Example
manufacturerCampaignReference	Your recall campaign reference	No	CAR/REF1
dvsaCampaignReference	DVSA campaign reference	No	R/123/20

What to expect from the response

{
  "vin": "123456789",
  "manufacturer": "ABC",
  "recalls": [
    {
      "manufacturerCampaignReference": "CAR/1",
      "dvsaCampaignReference": "R/123/20",
      "recallCampaignStartDate": "2024-03-30",
      "repairStatus": "NOT_FIXED"
    },
    {
      "manufacturerCampaignReference": "CAR/2",
      "dvsaCampaignReference": "R/456/20",
      "recallCampaignStartDate": "2024-03-30",
      "repairStatus": "FIXED"
    }
  ],
  "lastUpdatedDate": "2024-04-30T14:02:39.155Z"
}

Delete a recall from a vehicle

To delete a recall added in error for a single vehicle, use this endpoint:

DELETE /recalls/vin/{vin}

You cannot use this endpoint to delete a recall from a vehicle if its repair status is FIXED.

What you need to provide

Path parameters

Parameter	Description	Required	Example
vin	Vehicle identification number	Yes	12345678910

Query string parameters

You will need to provide at least one of the following:

Field	Description	Required	Example
manufacturerCampaignReference	Your recall campaign reference	No	AUDI/REF1
dvsaCampaignReference	DVSA campaign reference	No	DVSA/REF1

Error codes

In case of an error, the API will provide a predefined error code, an error message, and a status code to explain the specific issue.

Error code	Error description
RECALLS-BR-01	Something is wrong with the request
RECALLS-UA-01	Your authorisation failed
RECALLS-FB-01	You do not have permission to access this endpoint
RECALLS-FB-02	Your access token has expired
RECALLS-FB-03	Your API key is invalid
RECALLS-FB-04	Your access token is missing
RECALLS-RL-01	You have exceeded your daily usage allowance
RECALLS-RL-02	You have sent too many requests in a short amount of time
RECALLS-NF-01	Not found
RECALLS-NF-02	URL not found
RECALLS-PC-01	You have reached the limit of active client secrets
RECALLS-UN-01	Unknown error encountered

Testing the API

We have developed an application to help you test the API. See the GitHub repository.

You can run the application locally to simulate responses from the live service.
Instructions on how to use the application are found in the README document.

Rate limits

We strongly recommend caching the access token after it’s acquired to avoid errors caused by too many requests.

Per second, you can make up to:

Request Type	Description	Limit
POST	requests to create a new recall for a vehicle	25
PUT	requests to update a vehicle’s recall status	25
DELETE	requests to delete a recall added in error	25
GET	requests to get all recall information for a vehicle	25

If you exceed the rate limit, this will return an error caused by too many requests.

API reference

Visit the OpenAPI Specification page. You can also view the OpenAPI specification in YML format.