Every Auto Trader Connect API integration will need to meet our integration fundamentals for authentication and error handling.
This is to make sure that it follows best practice and will grant the access to services that can provide core information about the dealers on your integration.
This document will cover the following, which should be accounted for in all integrations:
- Authentication
- Advertisers API
- List all dealers on your integration
- Check an advertiser ID
- Advertiser update notifications
- Changes to the API
- General error handling
Authentication
To access Auto Trader’s API services, you will need to use your API credentials to obtain an access token from the Authentication endpoint.
This access token will then be required to access all other API endpoints.
Please note: This access token will last for 15 minutes. You should re-use it for all API calls your integration will make during that time period.
When you receive an access token from the Authentication endpoint, it will also give you an expiry time, which you can use to check the exact time of expiry.
When you do an API call after the expiry time, you should request a new access token the same way and use the new token.
Check out an example of authentication
Advertisers API
With the Advertisers API, you can see core details about dealers that are on your integration.
List all advertisers on your integration
To get all the dealers on your integration you need to make a GET request to the Advertisers API. You should include the relevant page and pageSize parameters to make sure you get all stock split into pages.
This will return an array of dealers on your integration with the following details:
- Advertiser name
- Advertiser ID
- Website URL
- Phone number
- Advertiser location
- Advertiser strapline
Check an advertiser ID
You can also check whether a specific advertiser ID is on your integration. You’ll need to make a GET request to the Advertiser API with the advertiser ID you want to check in the query string.
If the advertiser ID is on your integration, you will receive a 200 response code with details about the advertiser.
If the advertiser ID is not on your integration, you will receive a 403 response code meaning you do not have access to that advertiser ID.
Check out examples of Advertisers API calls
Advertiser update notifications
As part of the Advertiser API, you can have real-time advertiser update notifications whenever an dealer on your integration is updated on Auto Trader.
A webhook will send the updated advertiser data to you.
A webhook will be sent for updates to any of the data for dealers displayed on the Advertisers API.
Check out an example of an advertiser update notification
Changes to the API
We regularly change our API services to fix issues and introduce new features. Some of these changes may be considered 'breaking changes'. This means you may need a change to your integration to avoid any disruption, so will need some investigation.
We'll always let you know about these changes via email at least 30 days before the change.
You should keep this in mind when developing your integration to make sure you will not be affected by non-breaking changes to the API that will be released without prior notice.
Our Breaking Change policy covers what we consider breaking changes and non-breaking changes.
Check out our Breaking Change policy
General error handling
Across all capabilities and the APIs you will use, there are some common errors and response status codes that you need to handle gracefully within your system.
The main error response codes that we would expect your integration to handle are:
- 400 (Bad Request) - One of the parameters provided to the API is incorrect or invalid
- 401 (Unauthorised) - Your API request has an invalid access access token
- 403 (Forbidden) - You are either trying to perform a request for an advertiser ID you do not have access to, or are trying to access a resource that the provided advertiser ID does not have access to
- 429 (Too Many Requests) - You have reached your API application’s rate limit
- 503 (Service Unavailable) - The service you are trying to access is temporarily unavailable
Check out more info on general integration error handling
Each capability that you integrate will have errors specific to the API endpoints used that you will need to handle. These will be detailed within those capabilities and accompanying Postman collections.