NAV
shell

Introduction - Listing Creation API (Upload)

AutoScout24 is one of the biggest online car markets in Europe. On 4 market places are 2 million vehicles including new and used cars, motorbikes and trucks. AutoScout24 serves 20 million users (ACTA 2013) and over 40.000 dealers in seven countries.

The AutoScout24 API allows developers to manage the life cycle of classified listings on the AutoScout24 platform. Users of the API are able to read and write vehicle data, access make/model information or create classified ads. The API offers a RESTful interface to interact with the resources. The format to resolve or submit data is JSON. To access most of the endpoints, you need to be authenticated, using the OAuth process.

These pages are the main source of documentation for developers working with our API. If this is your first time getting in touch with AutoScout24 API, we recommend to carefully read through these pages.

Should this comprehensive online documentation not answer your questions please feel free to contact us using the following E-Mail address: daten@autoscout24.de

API Endpoint:

https://api.autoscout24.com

The following resources are exposed by the AutoScout24 API:

/vehicles
/vehicles/{vehicledId}
/vehicles/{vehicledId}/images
/vehicles/{vehicledId}/images/{imageId}
/vehicles/{vehicledId}/imageorder
/vehicles/{vehicledId}/videos
/vehicles/{vehicledId}/videos/{videoId}
/vehicles/{vehicledId}/publications
/vehicles/{vehicledId}/publications/{channelId}
/vehicles/{vehicledId}/products
/vehicles/{vehicledId}/products/{poroductId}
/vehicles/{vehicledId}/financingoffers
/vehicles/{vehicledId}/financingoffers/{financingofferId}
/statistics
/statistics/statisticId
/customerdetails
/makes
/makes/{makeId}
/makes/{makeId}/models
/seals
/seals/{sealId}
/references

The following image shows the graph of resources and sub-resources of the AutoScout24 RESTful API:

Resources Image

Getting Started - Listing Creation API (Upload)

The AutoScout24 API provides a RESTful API to write and extract the AutoScout24 content. All API requests use the standard HTTP methods (GET, POST, PUT, DELETE) to perform operations on resource URLs. JSON is used to represent the responses of the sent HTTP requests. In addition, the JSON responses contain additional hypermedia information of related resources.

The AutoScout24 Vehicle API can be reached via the following base URL: https://api.autoscout24.com

Before you can start using the API with your application, you’ll need to register at AutoScout24 and define what type of application you’re about to create. Register your application by contacting AutoScout24 via E-Mail daten@autoscout24.de. While registering your application you need to provide your redirect URL and your scope. After successful registration AutoScout24 provides you with a unique Client ID and Client Secret. Store these credentials, as you will need them to authenticate your application against the API.

API Evolution

Why Change is important

AutoScout24 has always been working towards empowering its users, and the API is no exception. The current design of the API has been developed to conform to industry’s standards and best practices. However, many factors could affect the underlying design of the API. These factors are driven by new regulations, technology and/or product changes. While change might be considered difficult to handle, it often has a great value for your application, and hence your business.

How to deal with change

Change might come in many different forms. However, API changes can be classified into two main categories: compatible and incompatible changes. When AutoScout24 releases new changes that are considered compatible, then client applications that integrate with the AutoScout24 API should not be affected. On the other hand, introducing incompatible changes will go through a defined process so that client application developers can handle the introduced changes. AutoScout24 will identify whether the released changes are compatible or incompatible. In addition, AutoScout24 will be communicating changes to its API consumers. This helps the consumers of the API keep track of the latest changes and handle any incompatibility.

API Evolution Strategy

AutoScout24 has set a philosophy when introduce new changes to its API consumers. This philosophy helps both the API consumers as well as AutoScout24 benefit from the introduced changes on both technical and business aspects. When there is a need to introduce changes to the AutoScout24 API, then these changes will be classified into compatible or incompatible changes. If compatible changes are introduced, then they will be released and the consumers of the API will be informed about the change. Client applications should continue working without problems when introducing such changes. On the other hand, when incompatible changes are introduced, a new version number is attached to the API to reflect the status and changes of the API; this also includes communicating the changes to the consumers of the API so that they can take proper actions to adapt their applications. In addition, when introducing such incompatible changes, developers will have a six-month period to migrate to the new released version.

The following timeline example demonstrates how API changes could be introduced:

Image1

  1. Version 1.0 is released. Consumers of the API use this version number to send requests and receive responses.
  2. Compatible changes are introduced. Consumers of the API will be informed about the changes. Version number doesn’t change.
  3. Incompatible changes are released, and hence a new version number “1.1” is introduced. Consumers of the API will be informed about the changes, and they will be given a period of six months to migrate to the new API version.
  4. After six months of releasing API version 1.1, version 1.0 is shutdown. All API requests with version 1.0 will be rejected.

Authorization & Security

Applications gain access to the API using OAuth 2, the standard used by most APIs for authenticating and authorizing users. The following walkthrough will show you how to authenticate a user to use the AutoScout24 API with OAuth 2. There are also client libraries available in a number of languages that you might find useful.

Initial Setup

Before you can start using OAuth 2 with your application, you’ll need to register at AutoScout24 and define what type of application you’re about to create.

  1. Register your application by contacting AutoScout24 via E-Mail (daten@autoscout24.de).
  2. While registering your application you need to provide the following information
    1. Your redirect URL.
  3. After successful registration AutoScout24 provides an unique Client ID and Client Secret to you.
  4. Store this ID and Secret, as you will need it to authenticate your application against the API.
Value Description
Client ID client_id as specified in the OAuth 2 spec
Client Secret client_secret as specified in the OAuth 2 spec
Redirect URI redirect_uri as specified in the OAuth 2 spec. The redirect URI is the URL within your application that will receive the OAuth2 credentials.

Authorize (“The first leg”)

Authorization Server Endpoint

https://api.autoscout24.com/auth/oauth/v2/authorize

Sample Get request to the Authorization Server

GET https://api.autoscout24.com/auth/oauth/v2/authorize?response_type=code&client_id={your_client_id}&redirect_uri={your_redirect_uri}

First, direct the user of your application to https://api.autoscout24.com/auth/oauth/v2/authorize through either a POST or a GET request with the following parameters:

Parameter Required Description
response_type yes Specifies whether the endpoint returns an authorization code. For web applications the value “code” should be used.
client_id yes The Client ID you obtained during the initial setup.
redirect_uri yes An HTTP(S) URI where the response will be redirected. You can register more than one redirect URI at AutoScout24. Attention: Please note that dynamic URIs are not supported. You have to provide static URIs.

For POST, include the parameters in the POST body. For GET, include them as query parameters. In both cases, URL encode the parameters.

The User Experience

At this point, you’ve forwarded the user to the AutoScout24 authorization page. After successfully entering their credentials the user authorizes your application to access their account.

Image1

Your application doesn’t need to do anything here; AutoScout24 handles authenticating the user and giving them feedback on any errors

Image2

After they have clicked either Grant or Deny, you’ll be sent a response from AutoScout24, as outlined in the next section.

Handling the Response from AutoScout24

If the user clicked Grant in the previous screen, AutoScout24 will redirect to the URI you specified earlier with a code parameter and will provide you an authorization code. For example, if your redirect URI was https://www.yourredirecturi.com, AutoScout24 would redirect to: GET https://www.yourredirecturi.com?code=123456abcdef

The authorization code is valid for 10 minutes and can be used only once.

However, if the user clicked Deny, you will receive a request with an error and error_description parameter, such as: GET https://www.yourredirecturi.com?error=access_denied

The following errors may occur:

Error Description
invalid_request The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unsupported_response_type The authorization server does not support obtaining an authorization code using this method. Check the value of the code param in your request.
access_denied The resource owner or authorization server denied the request.
server_error The device the user is trying to log in from is not authorized to access the user’s account.

The error parameter will always be present in case an error occurs.

Getting the Access Token (“The second leg”)

An example of a request in cURL looks like:

curl https://api.autoscout24.com/auth/oauth/v2/token
-d 'grant_type=authorization_code&code={your_code}&client_id={your_client_id}&client_secret={your_client_secret}&redirect_uri={your_redirect_uri}'
-X POST

Successful Response

If everything goes right and the request is successful, you’ll receive a 200 response containing a JSON body similar to this:

{
 "access_token": "T9cE5asGnuyYCCqIZFoWjFHvNbvVqHjl",
 "expires_in":3600,
 "token_type":"bearer",
 "refresh_token":"J7rxTiWOHMoSC1isKZKBZWizoRXjkQzig5C6jFgCVJ9bUnsUfGMinKBDLZWP9BgR"
}

Error Response

However, if the response is not successful, you’ll receive an error response, such as this:

{
 "error": "invalid_grant",
 "error_description": "Invalid user credentials"
}

You’re almost done! Once your application has completed the above section and gotten an authorization code, it will now need to exchange the authorization code for an access token from AutoScout24. The access token is what’s needed to sign your API requests to AutoScout24.

To get the access_token, you’ll need to make a POST request to https://api.autoscout24.com/auth/oauth/v2/token with the following parameters:

Parameter Required Description
grant_type yes Must be authorization_code
code yes The authorization code you retrieved previously
client_id yes Client ID obtained from AutoScout24 during the initial setup
client_secret yes Client Secret obtained from AutoScout24 during the initial setup
redirect_uri yes One of the redirect URI’s registered at AutoScout24

If you’re using a http client library please make sure send the data as a submitted form and to set the content type header by using the application/x-www-form-urlencoded type. e.g. Content-Type: application/x-www-form-urlencoded

Please not when using curl: curl with the ’-d’ parameter sends the specified data in a POST request to the HTTP server, in the same way that a browser does when a user has filled in an HTML form and presses the submit button. This will cause curl to pass the data to the server using the content-type application/x-www-form-urlencoded.

Supported Error Codes

AutoScout24 supports the full set of error codes as specified in the OAuth 2.0 spec:

Error Error Description What Happened
invalid_request Invalid grant_type parameter or parameter missing Your request did not contain a grant type
invalid_request Missing parameter. “code” is required The code parameter is missing for the authorization code grant type
invalid_request Invalid refresh token The refresh token has expired or is malformed
unauthorized_client The grant type is unauthorized for this client_id Your application is not authorized to use this grant type
invalid_grant Auth code doesn’t exist or is invalid for the client There was something wrong with the submitted authorization code. Verify that the authorization code is set correctly in your request
invalid_grant The authorization code has expired Your application likely needs to get a new authorization code
invalid_client The client credentials are invalid
redirect_uri_mismatch The redirect URI is missing or do not match Either a redirect uri is not configured for your application or the uri in the request does not match the configured URI
insecure_redirect_uri The URI is either not a custom protocol or not HTTPS Your application sent a bad redirect URI i.e. HTTP instead of HTTPS
invalid_redirect_uri The redirect_uri scheme is invalid per the RFC Your application sent an invalid URI. A common problem is the first character being something besides a letter.

Using the Access and Refresh Tokens (“The third leg”)

A sample cURL request would look like:

curl https://api.autoscout24.com/auth/oauth/v2/token
-d 'grant_type=refresh_token&refresh_token={valid_refresh_token}&client_id={your_client_id}&client_secret={your_client_secret}'
-X POST

Successful response

If the request is successful, you’ll see a response like this:

{
  "access_token" :"0ce4270c-1557-41cf-b857-ae1f5f4ac9f9",
  "token_type":"Bearer",
  "expires_in":3600,
  "refresh_token":"1d405b9a-146c-4381-b982-9f7447c4748f",
  "scope":"development"
}

The access_token is the actual string needed to make API requests. Each access_token is valid for 1 hour. In order to get a new, valid token, you can use the accompanying refresh_token. Each refresh token is valid for 14 days. To use the refresh_token to get a new access_token, make a POST request to https://api.autoscout24.com/auth/oauth/v2/token with the following, URL encoded parameters:

Parameter Required Description
refresh_token yes A valid refresh token
client_id yes Client ID obtained from AutoScout24 during the initial setup
client_secret yes Client Secret obtained from AutoScout24 during the initial setup
grant_type yes Must be refresh_token

In this response, you’ll receive both a new access_token and refresh_token. The refresh_token you used to make this request is no longer valid. If an error occurs, you’ll receive a 400 Bad Request, along with one of the errors listed in the Getting the Access Token section.

Using Your Access Token

If you were, for example, trying to get a list of a user’s vehicles, a full cURL request would look like this:

curl https://api.autoscout24.com/vehicles
-H "Authorization: Bearer 0ce4270c-1557-41cf-b857-ae1f5f4ac9f9"
-X GET

Once you have a valid access_token, you can use it to make requests to AutoScout24 API. All you need to do is set it in the authorization header like this:

Authorization: Bearer {valid_access_token}

If the protected resource request does not include authentication credentials or does not contain an access_token that enabled access to the protected resource, AutoScout24 sets the WWW-Authenticate response header field. If the protected resource request included an access_token and failed authentication, AutoScout24 sets the “error” attribute to provide the client with the reason why the access request was declined. AutoScout24 also includes the error-description attribute to provide developers a human-readable explanation that is not meant to be displayed to end users. The following codes can be returned as a value for the WWW-Authenticate header.

HTTP Status Error Code What Happened
400 invalid_request The request is missing a required parameter, includes an unsupported parameter or parameter value, repeats the same parameter, uses more than one method for including an access token, or is otherwise malformed
401 invalid_token The access token provided is expired, revoked, malformed or invalid for other reasons. The client may request a new access token and retry the protected resource request
403 insufficient_scope The request requires higher privileges than provided by the access token

API Responses

The AutoScout24 API communicates through standard HTTP status codes paired with response objects (JSON). These response objects contain codes that can be evaluated by the business logic of the API client.

HTTP Status Codes

Generally the following pattern will apply for HTTP status codes:

Status Code Pattern Response classification
2xx The request was successfully received, understood, and accepted
4xx An error in the request (usually a bad parameter has been set)

In detail the following HTTP Status codes are defined:

Status Code Description
200 request has been processed successfully
201 resource creation has been done successfully
400 bad request
401 unauthorized
403 forbidden

Response object (JSON)

Response Envelope Objects:

{
  "_links": {
    "self": {
      "href": ""
    }
  },
  "_request": {
    "url": "",
    "body": "",
    "method": ""
  },
  "_response": {
    "type": "",
    "objectId": "",
    "messages": [
      {
        "code": 00000,
        "messageType": "",
        "text": ""
      }
    ]
  },
  "_data": {

  }
}

The accompanying response objects are as detailed as possible without being unwieldy. The objects contain the following information:

Field Name Type Description
_links Object The hypermedia links object that contains information about the related resources to the current resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Object The object that contains the actual information about the specific resource that was requested in the HTTP message. This object is mainly used when sending GET requests to retrieve information.

Request Object

The following table contains the fields that could appear in the _request object of the API responses:

Field Name Type Description
url String The URL that was used by the client application to send the HTTP request.
method String The HTTP method that was used by the client application to send the HTTP request.
body String The content of the body that was sent in the HTTP request.

Response Object

The following table contains the fields that could appear in the _response object of the API responses:

Field Name Type Description
type Enum An enumeration that identifies what happened to the request that was sent. Tha possible values are: (Success, Error)
objectId String The ID of the object that was affected by the sent HTTP request.
messages Message Array An array of the messages that give information about processed object.

Message Object

The following table contains the fields that could appear in the Message object of the _response object:

Field Name Type Description
code Integer A unique code that identifies what has happened while processing the HTTP request. For list of codes please click here..
messageType Enum An enumeration value that identifies the type of the message. Possible values are: (Error, Info, Warning)
text String A text description of the message. This text can be utilized by showing it to the end user of client application.

Resource - Vehicles

This resource manages the complete lifecycle of a vehicle on the AutoScout24 marketplace. This includes inserting, updating, retrieving, and deleting the information of a vehicle.

Create Vehicle

Endpoint

POST /vehicles

Request Example

Creating a vehicle using cURL:

curl https://api.autoscout24.com/vehicles \
     -X POST \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer 4d774163-fedf-4454-83f0-1eb134872294" \
     -d '{ \
            "accident": false, \
            "alloyWheelSize": 18
            "availability": \
            {\
              "availabilityType": 3, \
              "deliveryDays": 7 \
            }, \
            "bodyColor": 2, \
            "bodyColorName": "metallic blue", \
            "cabOrRental": false, \
            "countryVersion": "AT", \
            "cylinderCapacity": 1400, \
            "cylinders": 4, \
            "description": "This is the description field for 4000 characters!", \
            "doors": 5, \
            "driveType": "R", \
            "emission": \
            { \
              "co2": 23, \
              "efficiencyClass": 2, \
              "emissionsSticker": 1, \
              "particleFilter": true, \
              "pollutionClass": 1, \
              "fuel": \
              { \
                "primaryFuelType": 1, \
                "additionalSupportedFuelTypes": [2, 3], \
                "consumption": \
                { \
                    "electricConsumptionCombined": 6.6, \
                    "fuelConsumptionUrban": 4.7, \
                    "fuelConsumptionHighway": 5.2, \
                    "fuelConsumptionCombined": 6.1 \
                } \
              } \
            }, \
            "emptyWeight": 1200, \
            "equipment": [1, 2, 4, 15], \
            "firstRegistration": "2011-11", \
            "fuelCategory": "B", \
            "gears": 6, \
            "hsn": "1240", \
            "identifier": \
            { \
              "crossReference": "DATX_002", \
              "offerReference": "A12453" \
            }, \
            "interiorColor": 1, \
            "includedServices": [1, 2], \
            "licencePlateNumber": "D13-MM45", \
            "maintenance": \
            { \
               "fullServiceHistory": true, \
               "lastCamBeltService": "2013-12", \
               "lastTechnicalService": "2013-02", \
               "nextInspection": "2020-11" \
            }, \
            "make": 13, \
            "metallic": true, \
            "mileage": 20000, \
            "carpassMileageUrl": "https://example.url", \
            "model": 20223, \
            "modelVersion": "Avant", \
            "nonSmoking": true, \
            "powerKw": 65, \
            "previousOwners": 1, \
            "prices": [ \
            { \
              "priceType": "Public", \
              "negotiable": true, \
              "price": 9000, \
              "taxDeductible": true, \
              "currency": "EUR" \
            }, \
            { \
               "priceType": "Dealer", \
               "price": 8500, \
               "currency": "EUR" \
            }], \
            "seals": [102], \
            "seats": 5, \
            "transmission": "M", \
            "tsn": "936", \
            "upholstery": "AL", \
            "vehicleBody": 1, \
            "vehicleOfferType": "U", \
            "vehicleType": "C", \
            "vin": "AB023475861123745", \
            "warrantyMonths": 30 \
          }'

Create a new vehicle.

Please note that after successful creation of a new vehicle this must still be published in order to be visible on the AutoScout24 platform.

Semantic Rules

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Content-Type String Yes The mediatype used for the body of the request. It should be: application/json
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Request Payload Parameters

Here you can find syntax requirements for all attributes used for the vehicle object which is used in the body of the POST HTTP request message.

Note: string length is counted as total of UFT-8 characters.

Field Name Vehicle Type Type Mandatory Format Description
accident C/B boolean Yes Needs to be set to TRUE if vehicle got damaged in the past irrespective of whether the damage has been fixed or not. Damages by accident, water, hailstorm, fire or alike must be indicated by this flag.
alloyWheelSize C integer No between 10 and 26 Size of alloy wheels of the vehicle (in inches). Only the following values are allowed: 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26. Equipment Alloy Wheels (id=15) must be also set when specifying the size.
availability C/B Availability Yes Provides information about when the vehicle is available from or can be delivered. Consists of availabilityType, deliveryDate, deliveryDays.
bodyColor C/B integer Yes enumerated Basic body color of the vehicle. Used to enable search by basic exterior color. Allowed values can be retrieved via resource /references.
bodyColorName C/B string maxLength=30 Manufacturers name of body color (Examples: British Racing Green, Black Oak Metallic).
cabOrRental C boolean Yes Needs to be set to TRUE if the vehicle has been used as cab or rental car.
countryVersion C string enumerated Indicates the original market/country the vehicle was built for. Allowed values can be retrieved via resource /references (countries).
cylinderCapacity C/B integer between 1 and 99999 Volume of the engine’s cylinders in ccm = cubic centimeters.
cylinders C/B integer between 1 and 99 number of cylinders of the engine.
description C/B string maxLength=4000 Free text description of the vehicle. Text may be formatted by tags. Supported formatting elements and syntax rules can be retrieved below.
doors C integer between 1 and 9 number of doors of the vehicle.
driveType C string enumerated Drive type of the vehicle (e.g. front, rear, 4WD). Allowed values can be retrieved via resource /references.
emission C/B Emission Yes Provides emission information about the vehicle. Consists of co2, efficiencyClass, emissionsSticker, fuel, particleFilter, pollutionClass.
emptyWeight C/B integer between 1 and 99999 Vehicle’s weight without driver, passengers or liquids (like fuel) in kg.
equipment C/B array, integer enumerated List of vehicle’s equipment. Allowed values can be retrieved via resource /references.
firstRegistration C/B string Yes YYYY-MM Month and year of first registration of the vehicle.
fuelCategory C/B string Yes (non-caravan vehicles) enumerated Category of fuel/energy source for the vehicle. Allowed values can be retrieved via resource /references.
gears C/B integer between 1 and 9 number of gears of the vehicle.
hsn C/B string exactLength=4, content must be an integer value HSN = Herstellerschluesselnummer: Unique identifier of vehicle manufacturer in Germany. In combination with TSN this key is used to uniquely identify a vehicle type. The make of a vehicle can be fully derived from this identifier.
identifier C/B Identifier Provides identification information for the vehicle. Consists of crossReference, offerReference, vehicleId.
includedService C/B array, integer enumerated Included services as part of the vehicle offer. Allowed values can be retrieved via resource /references. Example: Id 1 (= HU/AU neu) indicates that a vehicle’s last technical inspection as required by German regulations has been done recently. Should only be set if last technical inspection was done not more than 3 months ago.
interiorColor C integer enumerated, greater 0 Basic color of vehicle’s interior. Used to enable search by basic interior color. Allowed values can be retrieved via resource /references.
licencePlateNumber C/B string maxLength=10 Licence plate number of the vehicle.
maintenance C/B Maintenance Yes Provides maintenance information for the vehicle. Consists of fullServiceHistory, lastCamBeltService, lastTechnicalService, nextInspection.
make C/B integer Yes enumerated, greater 0 Make of the vehicle.
metallic C/B boolean Yes Needs to be set to TRUE if vehicle’s body color has a metallic effect.
mileage C/B integer between 0 and 9999999 number of kilometers km the vehicle has run.
carpassMileageUrl C/B string maxLength=1000 URL of mileage at CarPass.
model C/B integer Yes enumerated, greater 0 Model of the vehicle.
modelVersion C/B string maxLength=50 Additional non-generic vehicle model description (e.g. Cross, Ambition, Elegance, 2.0).
nonSmoking C boolean Yes Needs to set to TRUE if the vehicle has been used by non-smokers only.
powerKw C/B integer Yes (non-caravan vehicles) between 0 and 9999 Engine power in kW. Power in (German) PS does not need to be specified. It will automatically be derived from this value.
previousOwners C/B integer between 0 and 99 number of previous vehicle owners.
prices C/B array, Price Yes Provides price information for the vehicle. Consists of currency, negotiable, price, priceType, taxDeductible.
seals C/B array, integer enumerated List of used car seals granted for the vehicle. Allowed values can be retrieved via resource /seals.
seats C integer between 1 and 99 number of seats of the vehicle.
transmission C/B string enumerated Specifies the transmission type of the vehicle (e.g. manual, automatic). Allowed values can be retrieved via resource /references.
tsn C/B string exactLength=3 TSN = Typschluesselnummer: Identifier used by vehicle manufacturers in Germany to specify a vehicle type. From TSN the following parameters can be derived: Model, body, engine type, fuel type etc. Combined with HSN a make/model combination can be fully specified.
upholstery C string enumerated Upholstery of the vehicle (e.g. full leather, part leather, cloth). Allowed values can be retrieved via resource /references.
vehicleBody C/B integer Yes enumerated, greater 0 Shape of vehicle’s body (e.g. Compact, Convertible, Van, Off-Road). Allowed values can be retrieved via resource /references.
vehicleOfferType C/B string Yes enumerated Specifies the offer type of the vehicle (e.g. used, new, demonstration vehicle). Allowed values can be retrieved via resource /references.
vehicleType C/B string Yes enumerated Type of vehicle (e.g. car, bike, truck). Currently 'C’ (= Car) and 'B’ (= Bike) are supported. Allowed values can be retrieved via resource /references.
vin C/B string exactLength=17 VIN = Vehicle Identification Number. A unique international code including a serial number used to identify individual motor vehicles, towed vehicles and motorcycles.
warrantyMonths C/B integer between 1 and 99 Specifies the length in months of an additional goodwill warranty that is granted by the seller/dealer for the vehicle. This warranty must be included in the final vehicle price. If this attribute is not transmitted then no additional warranty is being granted.

Availability Object

Field Name Vehicle Type Type Mandatory Format Description
availabilityType C/B integer Yes enumerated Availability status of the vehicle. Allowed values can be retrieved via resource /references.
deliveryDate C/B string YYYY-MM-DD Indicates from which date in the future the vehicle can be delivered.
deliveryDays C/B integer enumerated Delivery time in days if the vehicle can be ordered. Only the following values are allowed: 1, 2, 3, 4, 5, 6, 7, 14, 21, 28, 42, 60, 90, 120, 150, 180, 270, 360.

Emission Object

Field Name Vehicle Type Type Mandatory Format Description
co2 C integer Yes (vehicleOfferType N, D, S) between 0 and 9999999 Vehicle’s carbon dioxide emission in g/km.
efficiencyClass C integer Yes (vehicleOfferType N, D, S) enumerated, greater 0 Vehicle’s energy efficiency class. Allowed values can be retrieved via resource /references.
emissionsSticker C integer enumerated, greater 0 Emissions sticker type as assigned by German technical inspection authorities (German wording: Umweltplakette/Feinstaubplakette). Allowed values can be retrieved via resource /references.
fuel C Fuel greater 0 Provides detailed fuel information as part of the emission information for the vehicle. Consists of additionalSupportedFuelTypes, consumption, primaryFuelType.
particleFilter C/B boolean Yes Indicates whether a diesel vehicle is equipped with a particle filter. Needs to be set to TRUE in this case.
pollutionClass C/B integer enumerated, greater 0 The pollution class indicates the amount of harmful substances the vehicle emits. The classification is in accordance with the European Standard Euronorm. Allowed values can be retrieved via resource /references.

Fuel Object

Field Name Vehicle Type Type Mandatory Format Description
additionalSupportedFuelTypes C array, integer enumerated Additional supported fuel types that might accompany the primary fuel type. These fuel types can also be consumed by the vehicle but have higher emissions than the primary fuel type. This is derived from German emission/consumption regulations for vehicles (EnVKV). Allowed values can be retrieved via resource /references.
consumption C Consumption Provides consumption information as part of emission information for the vehicle. Consists of electricConsumptionCombined, fuelConsumptionCombined, fuelConsumptionHighway, fuelConsumptionUrban.
primaryFuelType C integer Yes (vehicleOfferType N, D, S) enumerated, greater 0 Fuel type with the lowest emission for the vehicle. This is derived from German emission/consumption regulations for vehicles (EnVKV). Allowed values can be retrieved via resource /references.

Consumption Object

Field Name Vehicle Type Type Mandatory Format Description
electricConsumptionCombined C number between 0 and 99.9 Vehicle’s power consumption in kWh/100 km as measured in specific tests executed in city and highway traffic situations.
fuelConsumptionCombined C number between 0 and 99.9 Vehicle’s fuel consumption in l/100 km (for compressed natural gas and hydrogen in kg/100 km) as measured in specific tests executed in city and highway traffic situations.
fuelConsumptionHighway C number between 0 and 99.9 Vehicle’s fuel consumption in l/100 km (for compressed natural gas and hydrogen in kg/100 km) as measured in specific tests executed in highway traffic situations.
fuelConsumptionUrban C number between 0 and 99.9 Vehicle’s fuel consumption in l/100 km (for compressed natural gas and hydrogen in kg/100 km) as measured in specific tests executed in city traffic situations.

Identifier Object

Field Name Vehicle Type Type Mandatory Format Description
crossReference C/B string maxLength=50 Any technical vehicle reference that can be used by the API client. This information will not be shown on the AutoScout24 platform.
offerReference C/B string maxLength=50 (Internal) offer ID of the vehicle’s dealer/seller. Can be used by potential buyers as a reference when contacting the seller. Will be shown on the AutoScout24 platform.
vehicleId C/B string GUID VehicleId is a unique identifier supplied by the AutoScout24 system after successfull vehicle import.

Maintenance Object

Field Name Vehicle Type Type Mandatory Format Description
fullServiceHistory C/B boolean Yes Indicates whether vehicle has passed all periodic maintenance as recommended by the vehicle manufacturer. Needs to be set to TRUE in this case.
lastCamBeltService C string YYYY-MM Date of last cam belt exchange.
lastTechnicalService C/B string YYYY-MM Date of last periodic maintenance.
nextInspection C/B string YYYY-MM Date of next technical inspection as required by regulations.

Price Object

Field Name Vehicle Type Type Mandatory Format Description
currency C/B string Yes enumerated Currency for given price. Currently only Euro (EUR) is supported.
negotiable C/B boolean Indicates whether a given public price (priceType = Public) is negotiable. Needs to be set to TRUE in this case.
price C/B integer Yes greater 0 Price for the vehicle.
priceType C/B string Yes enumerated Specifies the type of a given price (e.g. public price or price valid for dealers only). Allowed values can be retrieved via resource /references.
taxDeductible C/B boolean Indicates whether value added tax amount can be shown in invoice. This applies to a given public price (priceType = Public). Needs to be set to TRUE in this case.

Formatting Options: Vehicle description Field

The free text describing a vehicle (field description) can be formatted using certain formatting elements. Please find the list of formatting elements that are supported by AutoScout24 in accordance to wikicreole.org (http://www.wikicreole.org/wiki/Elements).

Supported Formatting Elements

Supported Creole Formatting Element Supported Creole Formatting Syntax Result HTML Equivalent Comments
Line break \ <br> Line breaks are only supported using this Creole formatting element.
Horizontal line —- ______________ <hr> A horizontal line is always accompanied by an automatic line break.
Bold **lorem ipsum** lorem ipsum <b>lorem ipsum</b> Bold text items must start and end with two asterisks.
List * List item 1\
* List item 2\
  • List item 1
  • List item 2
<ul>
<li> List item 1</li>
<li> List item 2</li>
</ul>
Inserting one asterisk leads to a bullet point. After each bullet point a line break needs to be inserted.

Example: Formatting Elements & Corresponding Result

This example illustrates the formatting result when using all of these formatting elements.

Image1

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7"
    }
  },
  "_request": {
    "url": "/vehicles",
    "body": "{\"accident\":false,\"availability\":{\"availabilityType\":3,\"deliveryDate\":null,\"deliveryDays\":7},\"bodyColor\":2,\"bodyColorName\":\"metallic blue\",\"cabOrRental\":false,\"countryVersion\":\"AT\",\"cylinderCapacity\":1400,\"cylinders\":4,\"description\":\"This is the description field for 4000 characters!\",\"doors\":5,\"driveType\":\"R\",\"emission\":{\"co2\":23,\"efficiencyClass\":2,\"emissionsSticker\":1,\"fuel\":{\"additionalSupportedFuelTypes\":[2,3],\"consumption\":{\"electricConsumptionCombined\":6.6,\"fuelConsumptionCombined\":6.1,\"fuelConsumptionHighway\":5.2,\"fuelConsumptionUrban\":4.7},\"primaryFuelType\":1},\"particleFilter\":true,\"pollutionClass\":1},\"emptyWeight\":1200,\"equipment\":[1,2,4],\"firstRegistration\":\"2011-11\",\"fuelCategory\":\"B\",\"gears\":6,\"hsn\":\"1240\",\"identifier\":{\"crossReference\":\"DATX_002\",\"offerReference\":\"A12453\",\"vehicleId\":\"6c48bb1f-d14b-4ed3-ae1d-508cb71e19ba\"},\"includedServices\":[1,2],\"interiorColor\":1,\"maintenance\":{\"fullServiceHistory\":true,\"lastCamBeltService\":\"2013-12\",\"lastTechnicalService\":\"2013-02\",\"nextInspection\":\"2020-11\"},\"make\":13,\"metallic\":true,\"mileage\":20000,\"carpassMileageUrl\":"https://example.com",\"model\":20223,\"modelVersion\":\"Avant\",\"nonSmoking\":true,\"licencePlateNumber\":\"D13-MM45\",\"powerKw\":65,\"previousOwners\":1,\"prices\":[{\"currency\":\"EUR\",\"negotiable\":true,\"price\":9000,\"priceType\":\"Public\",\"taxDeductible\":true},{\"currency\":\"EUR\",\"negotiable\":null,\"price\":8500,\"priceType\":\"Dealer\",\"taxDeductible\":null}],\"seals\":[102],\"seats\":5,\"transmission\":\"M\",\"tsn\":\"936\",\"upholstery\":\"AL\",\"vehicleBody\":1,\"vehicleOfferType\":\"U\",\"vehicleType\":\"C\",\"vin\":\"AB023475861123745\",\"warrantyMonths\":30}",
    "method": "POST"
  },
  "_response": {
    "type": "Success",
    "objectId": "b78d27e2-671a-47w6-80ab-d3726d7782c7",
    "messages": [
      {
        "code": 20001,
        "messageType": "Warning",
        "text": "Field emission.particleFilter does not correspond with selected field fuelCategory. A particle filter is only available for diesel vehicles."
      }
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Retrieve Vehicles List

Endpoint

GET /vehicles

Request Example

Retrieve all the vehicles of a dealer.

curl https://api.autoscout24.com/vehicles \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer 73a06d83-6e13-4444-a288-6aa8c4098c2f"

Retrieve all existing vehicles and vehicle details of a dealer.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles"
    },
    "vehicles": [
      {
        "href": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee"
      },
      {
        "href": "/vehicles/935e596f-d525-a948-e851-2951040a6575"
      }
    ]
  },
  "_request": {
    "url": "/vehicles",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success"
  },
  "_data": {
    "vehicles": [
      {
        "accident": false,
        "availability": {
          "availabilityType": 1,
          "deliveryDate": null,
          "deliveryDays": null
        },
        "bodyColor": 3,
        "bodyColorName": null,
        "cabOrRental": false,
        "countryVersion": null,
        "cylinderCapacity": 2893,
        "cylinders": 6,
        "description": null,
        "doors": 2,
        "driveType": null,
        "emission": {
          "co2": 221,
          "efficiencyClass": null,
          "emissionsSticker": null,
          "fuel": {
            "additionalSupportedFuelTypes": null,
            "consumption": {
              "electricConsumptionCombined": null,
              "fuelConsumptionCombined": 9.4,
              "fuelConsumptionHighway": 6.9,
              "fuelConsumptionUrban": 13.8
            },
            "primaryFuelType": null
          },
          "particleFilter": false,
          "pollutionClass": 5
        },
        "emptyWeight": 1335,
        "equipment": [
          1,
          2,
          3,
          5,
          10,
          12,
          13,
          15,
          16,
          17,
          19,
          26,
          31,
          32,
          41,
          42,
          50,
          114
        ],
        "firstRegistration": "2011-02",
        "fuelCategory": "B",
        "gears": 6,
        "hsn": "0583",
        "identifier": {
          "crossReference": null,
          "offerReference": null,
          "vehicleId": "7e59590f-c5a3-974e-e053-2951040ae4cc"
        },
        "includedServices": null,
        "interiorColor": null,
        "maintenance": {
          "fullServiceHistory": false,
          "lastCamBeltService": null,
          "lastTechnicalService": null,
          "nextInspection": null
        },
        "make": 57,
        "metallic": false,
        "mileage": 999999,
        "carpassMileageUrl": "https://example.url",
        "model": 1955,
        "modelVersion": null,
        "nonSmoking": false,
        "licencePlateNumber": null,
        "powerKw": 188,
        "previousOwners": null,
        "prices": [
          {
            "currency": "EUR",
            "negotiable": false,
            "price": 111,
            "priceType": "Public",
            "taxDeductible": false
          }
        ],
        "seals": [
          162
        ],
        "seats": 2,
        "transmission": "M",
        "tsn": "ACH",
        "upholstery": null,
        "vehicleBody": 2,
        "vehicleOfferType": "U",
        "vehicleType": "C",
        "vin": null,
        "warrantyMonths": null
      },
      {
        "accident": false,
        "availability": {
          "availabilityType": 1,
          "deliveryDate": "2015-11-27",
          "deliveryDays": null
        },
        "bodyColor": 2,
        "bodyColorName": null,
        "cabOrRental": false,
        "countryVersion": null,
        "cylinderCapacity": 1560,
        "cylinders": 4,
        "description": null,
        "doors": 5,
        "driveType": null,
        "emission": {
          "co2": 119,
          "efficiencyClass": null,
          "emissionsSticker": null,
          "fuel": {
            "additionalSupportedFuelTypes": null,
            "consumption": {
              "electricConsumptionCombined": null,
              "fuelConsumptionCombined": 4.5,
              "fuelConsumptionHighway": 3.7,
              "fuelConsumptionUrban": 5.8
            },
            "primaryFuelType": null
          },
          "particleFilter": false,
          "pollutionClass": 4
        },
        "emptyWeight": 1392,
        "equipment": [
          1,
          2,
          3,
          5,
          12,
          13,
          17,
          26,
          30,
          31,
          32,
          41,
          42
        ],
        "firstRegistration": "2011-02",
        "fuelCategory": "L",
        "gears": 5,
        "hsn": "8566",
        "identifier": {
          "crossReference": null,
          "offerReference": null,
          "vehicleId": "935e590f-d525-a948-e053-2951040a6584"
        },
        "includedServices": null,
        "interiorColor": null,
        "maintenance": {
          "fullServiceHistory": false,
          "lastCamBeltService": null,
          "lastTechnicalService": null,
          "nextInspection": null
        },
        "make": 29,
        "metallic": false,
        "mileage": 58823,
        "carpassMileageUrl": "https://example.url",
        "model": 19089,
        "modelVersion": "C-MAX 1.6 TDCi DPF Style ",
        "nonSmoking": false,
        "licencePlateNumber": null,
        "powerKw": 80,
        "previousOwners": null,
        "prices": [
          {
            "currency": "EUR",
            "negotiable": false,
            "price": 852662,
            "priceType": "Public",
            "taxDeductible": false
          }
        ],
        "seals": [
          162
        ],
        "seats": 5,
        "transmission": "M",
        "tsn": "AAJ",
        "upholstery": null,
        "vehicleBody": 5,
        "vehicleOfferType": "U",
        "vehicleType": "C",
        "vin": null,
        "warrantyMonths": null
      },

    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Vehicles Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
vehicles array, Vehicle An array that holds the vehicle objects.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Retrieve a Vehicle

Endpoint

GET /vehicles/{vehicleID}

Request Example

Retrieve a vehicle that has an ID = b78d27e2-671a-47w6-80ab-d3726d7782c7

curl https://api.autoscout24.com/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7 \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer 73a06d83-6e13-4444-a288-6aa8c4098c2f"

Retrieve details of an existing vehicle via its ID.

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7"
    }
  },
  "_request": {
    "url": "/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success",
    "objectId": "b78d27e2-671a-47w6-80ab-d3726d7782c7"
  },
  "_data": {
    "vehicle": {
      "accident": false,
      "availability": {
        "availabilityType": 1,
        "deliveryDate": null,
        "deliveryDays": null
      },
      "bodyColor": 3,
      "bodyColorName": null,
      "cabOrRental": false,
      "countryVersion": null,
      "cylinderCapacity": 2893,
      "cylinders": 6,
      "description": null,
      "doors": 2,
      "driveType": null,
      "emission": {
        "co2": 221,
        "efficiencyClass": null,
        "emissionsSticker": null,
        "fuel": {
          "additionalSupportedFuelTypes": null,
          "consumption": {
            "electricConsumptionCombined": null,
            "fuelConsumptionCombined": 9.4,
            "fuelConsumptionHighway": 6.9,
            "fuelConsumptionUrban": 13.8
          },
          "primaryFuelType": null
        },
        "particleFilter": false,
        "pollutionClass": 5
      },
      "emptyWeight": 1335,
      "equipment": [
        1,
        2,
        3,
        5,
        10,
        12,
        13,
        15,
        16,
        17,
        19,
        26,
        31,
        32,
        41,
        42,
        50,
        114
      ],
      "firstRegistration": "2011-02",
      "fuelCategory": "B",
      "gears": 6,
      "hsn": "0583",
      "identifier": {
        "crossReference": null,
        "offerReference": null,
        "vehicleId": "7e59590f-c5a3-974e-e053-2951040ae4cc"
      },
      "includedServices": null,
      "interiorColor": null,
      "maintenance": {
        "fullServiceHistory": false,
        "lastCamBeltService": null,
        "lastTechnicalService": null,
        "nextInspection": null
      },
      "make": 57,
      "metallic": false,
      "mileage": 999999,
      "carpassMileageUrl": "https://example.com",
      "model": 1955,
      "modelVersion": null,
      "nonSmoking": false,
      "licencePlateNumber": null,
      "powerKw": 188,
      "previousOwners": null,
      "prices": [
        {
          "currency": "EUR",
          "negotiable": false,
          "price": 111,
          "priceType": "Public",
          "taxDeductible": false
        }
      ],
      "seals": [
        162
      ],
      "seats": 2,
      "transmission": "M",
      "tsn": "ACH",
      "upholstery": null,
      "vehicleBody": 2,
      "vehicleOfferType": "U",
      "vehicleType": "C",
      "vin": null,
      "warrantyMonths": null
    }
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Vehicle Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
vehicle Vehicle The object that holds the information about the requested vehicle.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Update a Vehicle

Endpoint

PUT /vehicles/{vehicleID}

Request Example

Update a vehicle that has an ID = b78d27e2-671a-47q6-80ac-d3726d7774c7

curl https://api.autoscout24.com/vehicles/b78d27e2-671a-47q6-80ac-d3726d7774c7 \
     -X PUT \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer 4d774163-fedf-4454-83f0-1eb134872294" \
     -d '{ \
            "accident": false, \
            "availability": \
            {\
              "availabilityType": 3, \
              "deliveryDays": 7 \
            }, \
            "bodyColor": 2, \
            "bodyColorName": "metallic blue", \
            "cabOrRental": false, \
            "countryVersion": "AT", \
            "cylinderCapacity": 1400, \
            "cylinders": 4, \
            "description": "This is the description field for 4000 characters!", \
            "doors": 5, \
            "driveType": "R", \
            "emission": \
            { \
              "co2": 23, \
              "efficiencyClass": 2, \
              "emissionsSticker": 1, \
              "particleFilter": true, \
              "pollutionClass": 1, \
              "fuel": \
              { \
                "primaryFuelType": 1, \
                "additionalSupportedFuelTypes": [2, 3], \
                "consumption": \
                { \
                    "electricConsumptionCombined": 6.6, \
                    "fuelConsumptionUrban": 4.7, \
                    "fuelConsumptionHighway": 5.2, \
                    "fuelConsumptionCombined": 6.1 \
                } \
              } \
            }, \
            "emptyWeight": 1200, \
            "equipment": [1, 2, 4], \
            "firstRegistration": "2011-11", \
            "fuelCategory": "B", \
            "gears": 6, \
            "hsn": "1240", \
            "identifier": \
            { \
              "crossReference": "DATX_002", \
              "offerReference": "A12453" \
            }, \
            "interiorColor": 1, \
            "includedServices": [1, 2], \
            "licencePlateNumber": "D13-MM45", \
            "maintenance": \
            { \
               "fullServiceHistory": true, \
               "lastCamBeltService": "2013-12", \
               "lastTechnicalService": "2013-02", \
               "nextInspection": "2020-11" \
            }, \
            "make": 13, \
            "metallic": true, \
            "mileage": 20000, \
            "carpassMileageUrl": "https://example.url", \
            "model": 20223, \
            "modelVersion": "Avant", \
            "nonSmoking": true, \
            "powerKw": 65, \
            "previousOwners": 1, \
            "prices": [ \
            { \
              "priceType": "Public", \
              "negotiable": true, \
              "price": 9000, \
              "taxDeductible": true, \
              "currency": "EUR" \
            }, \
            { \
               "priceType": "Dealer", \
               "price": 8500, \
               "currency": "EUR" \
            }], \
            "seals": [102], \
            "seats": 5, \
            "transmission": "M", \
            "tsn": "936", \
            "upholstery": "AL", \
            "vehicleBody": 1, \
            "vehicleOfferType": "U", \
            "vehicleType": "C", \
            "vin": "AB023475861123745", \
            "warrantyMonths": 30 \
          }'

Update details of an existing vehicle.

Semantic Rules

See semantic rules description on POST method

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Content-Type String Yes The mediatype used for the body of the request. It should be: application/json
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Request Payload Parameters

Please follow this link to check the structure of the object to be sent in the HTTP request body.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/b78d27e2-671a-47q6-80ac-d3726d7774c7"
    }
  },
  "_request": {
    "url": "/vehicles/b78d27e2-671a-47q6-80ac-d3726d7774c7",
    "body": "{\"accident\":false,\"availability\":{\"availabilityType\":3,\"deliveryDate\":null,\"deliveryDays\":7},\"bodyColor\":2,\"bodyColorName\":\"metallic blue\",\"cabOrRental\":false,\"countryVersion\":\"AT\",\"cylinderCapacity\":1400,\"cylinders\":4,\"description\":\"This is the description field for 4000 characters!\",\"doors\":5,\"driveType\":\"R\",\"emission\":{\"co2\":23,\"efficiencyClass\":2,\"emissionsSticker\":1,\"fuel\":{\"additionalSupportedFuelTypes\":[2,3],\"consumption\":{\"electricConsumptionCombined\":6.6,\"fuelConsumptionCombined\":6.1,\"fuelConsumptionHighway\":5.2,\"fuelConsumptionUrban\":4.7},\"primaryFuelType\":1},\"particleFilter\":true,\"pollutionClass\":1},\"emptyWeight\":1200,\"equipment\":[1,2,4],\"firstRegistration\":\"2011-11\",\"fuelCategory\":\"B\",\"gears\":6,\"hsn\":\"1240\",\"identifier\":{\"crossReference\":\"DATX_002\",\"offerReference\":\"A12453\",\"vehicleId\":null},\"includedServices\":[1,2],\"interiorColor\":1,\"maintenance\":{\"fullServiceHistory\":true,\"lastCamBeltService\":\"2013-12\",\"lastTechnicalService\":\"2013-02\",\"nextInspection\":\"2020-11\"},\"make\":13,\"metallic\":true,\"mileage\":20000,\"carpassMileageUrl\":"https://example.url",\"model\":20223,\"modelVersion\":\"Avant\",\"nonSmoking\":true,\"licencePlateNumber\":\"D13-MM45\",\"powerKw\":65,\"previousOwners\":1,\"prices\":[{\"currency\":\"EUR\",\"negotiable\":true,\"price\":9000,\"priceType\":\"Public\",\"taxDeductible\":true},{\"currency\":\"EUR\",\"negotiable\":null,\"price\":8500,\"priceType\":\"Dealer\",\"taxDeductible\":null}],\"seals\":[102],\"seats\":5,\"transmission\":\"M\",\"tsn\":\"936\",\"upholstery\":\"AL\",\"vehicleBody\":1,\"vehicleOfferType\":\"U\",\"vehicleType\":\"C\",\"vin\":\"AB023475861123745\",\"warrantyMonths\":30}",
    "method": "PUT"
  },
  "_response": {
    "type": "Success",
    "objectId": "b78d27e2-671a-47q6-80ac-d3726d7774c7",
    "messages": [
      {
        "code": 20001,
        "messageType": "Warning",
        "text": "Field particleFilter does not correspond with selected field fuelCategory. A particle filter is only available for diesel vehicles."
      }
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Delete a Vehicle

Endpoint

Delete /vehicles/{vehicleID}

Request Example

Delete a vehicle that has an ID = b78d27e2-671a-47w6-80ab-d3726d7782c7

curl https://api.autoscout24.com/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7 \
     -X DELETE \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer 73a06d83-6e13-4444-a288-6aa8c4098c2f"

Delete an existing vehicle.

Please note that deleting a vehicle will automatically unpublish the vehicle from any channel. All vehicle images and ad products will also be automatically removed.

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": null
    }
  },
  "_request": {
    "url": "/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7",
    "body": null,
    "method": "DELETE"
  },
  "_response": {
    "type": "Success",
    "messages": [
      {
        "code": 10000,
        "messageType": "Info",
        "text": "Vehicle with id b78d27e2-671a-47w6-80ab-d3726d7782c7 was succesfully deleted."
      }
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Resource - Images

The Images resource is a sub-resource of the Vehicle resource. It manages the complete lifecycle of the images of a specific vehicle on the AutoScout24 marketplace. This includes inserting, updating, retrieving, and deleting images of a vehicle.

Upload an Image

Endpoint

POST /vehicles/{vehicleId}/images

Request Example

Uploading an image and attaching it to a vehicle with id = 7e59591f-c5a3-974e-e452-2951040ae4ee:


curl https://api.autoscout24.com/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/images \
     -X POST \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" \
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf" \
     -F "file=@carFoto.jpg"

Upload a new vehicle image.

The following overview shows how many images can be uploaded/shown per vehicle.

Max. 30 images can be uploaded.

Images will be shown according to selected ad product:

Premium Ad Product (T30): max. 30 images

Plus Ad Product (T20): max. first 20 images

Basic Ad Product (T10): max. first 15 images

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Content-Type String Yes The mediatype used for the body of the request. It should be: multipart/form-data
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example


{
  "_links": {
    "self": {
      "href": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/images/1321961722"
    }
  },
  "_request": {
    "url": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/images",
    "body": null,
    "method": "POST"
  },
  "_response": {
    "type": "Success",
    "objectId": "1321961722"
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Retrieve Vehicle’s Images

Endpoint

GET /vehicles/{vehicleId}/images

Request Example

Retrieve all the images of a vehicle with id = 7e59591f-c5a3-974e-e452-2951040ae4ee:

curl https://api.autoscout24.com/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/images \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf"

Retrieve all existing images of a vehicle.

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/images"
    },
    "images": [
      {
        "href": "http://pic.autoscout24.net/images-big/014/470/0266470014001.jpg?35d21ba78abe"
      }
    ]
  },
  "_request": {
    "url": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/images",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success"
  },
  "_data": {
    "images": [
      {
        "id": "1321961722",
        "href": "http://pic.autoscout24.net/images-big/014/470/0266470014001.jpg?35d21ba78abe",
        "type": "image/jpeg"
      }
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Images Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
images array, Image An array that holds the images objects.

Image Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
id String The unique ID of the image object.
href String The URI of the image object.
type String The type of the image objects. Possible values are: image/jpeg , image/png

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Retrieve an Image

Endpoint

GET /vehicles/{vehicleId}/images/{imageId}

Request Example

Retrieve the image of id = 1321961722 for the vehicle with id = b78d27e2-671a-47w6-80ab-d3726d7782c7:

curl https://api.autoscout24.com/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/images/1321961722 \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer 73a06d83-6e13-4444-a288-6aa8c4098c2f"

Retrieve details of an existing vehicle image.

Parameters

Parameter Name Type Mandatory Description
vehicleId URI Parameter Yes Unique identifier for a given vehicle.
imageId URI Parameter Yes Unique identifier for a given image.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/images/1321961722"
    }
  },
  "_request": {
    "url": "/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/images/1321961722",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success",
    "objectId": "1321961722"
  },
  "_data": {
    "image": {
      "id": "1321961722",
      "href": "http://pic.autoscout24.net/images-big/014/470/0266470014001.jpg?35d21ba78abe",
      "type": "image/jpeg"
    }
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Image Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
image Image An object that contains information about the requested image object.

Image Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
id String The unique ID of the image object.
href String The URI of the image object.
type String The type of the image objects. Possible values are: image/jpeg , image/png

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Delete an Image

Endpoint

DELETE /vehicles/{vehicleId}/images/{imageId}

Request Example

Delete the image with id = 1321961722 of the vehicle with ID = b78d27e2-671a-47w6-80ab-d3726d7782c7:


curl https://api.autoscout24.com/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/images/1321961722 \
     -X DELETE \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf"

Delete an existing vehicle image.

Parameters

Parameter Name Type Mandatory Description
vehicleId URI Parameter Yes Unique identifier for a given vehicle.
imageId URI Parameter Yes Unique identifier for a given image.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": null
    }
  },
  "_request": {
    "url": "/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/images/1321961722",
    "body": null,
    "method": "DELETE"
  },
  "_response": {
    "type": "Success",
    "messages": [
      {
        "code": 10001,
        "messageType": "Info",
        "text": "Image with id 1321961722 was succesfully deleted."
      }
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Resource - Image Order

Get Image Order

Endpoint

GET /vehicles/{vehicleId}/imageorder

Request Example

Retrieve the image order of the vehicle with id = b78d27e2-671a-47w6-80ab-d3726d7782c7:


curl https://api.autoscout24.com/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/imageorder \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf"

Retrieve sorting order and details of existing vehicle images.

The first image in the sequence identifies the vehicle’s main image.

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/imageorder"
    }
  },
  "_request": {
    "url": "/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/imageorder",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success"
  },
  "_data": {
    "imageOrder": [
      "1322014787",
      "1322014969"
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Image Order Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
imageOrder array, String An array that has the IDs of the images. The index of each String value in the array represents the the order of the image.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Update Image Order

Endpoint

PUT /vehicles/{vehicleId}/imageorder

Request Example

Update the image order of the vehicle with id = b78d27e2-671a-47w6-80ab-d3726d7782c7:


curl https://api.autoscout24.com/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/imageorder \
     -X PUT \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf" \
     -d '[ \
       "1322014969", \
       "1322014787" \
     ]'

Update sorting order and details of existing vehicle images.

The first image in the sequence identifies the vehicle’s main image.

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Content-Type String Yes The mediatype used for the body of the request. It should be: application/json
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Request Payload Parameters

The HTTP request body is an array that contains the IDs of the images. The index of each String value in the array represents the the order of the image, e.g.:

["1322014969","1322014787"]

The above array would would set the image with ID = 1322014969 as the primary image of the clasiffied listing.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/imageorder"
    }
  },
  "_request": {
    "url": "/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/imageorder",
    "body": "[\n      \"1322014969\",\n      \"1322014787\"\n    ]",
    "method": "PUT"
  },
  "_response": {
    "type": "Success"
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Resource - Videos

The Videos resource is a sub-resource of the Vehicle resource. Using this resource, youtube videos can be attached to a vehicle to be displayed on its detail page on the AutoScout24 marketplace. This resource manages the lifecycle of a vehicle’s youtube video including creation, deletion, and retrieval of video URL.

Attach a Youtube Video

Endpoint

POST /vehicles/{vehicleId}/videos

Request Example

Attach a video to a vehicle with id = 7e59591f-c5a3-974e-e452-2951040ae4ee

curl https://api.autoscout24.com/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/videos \
    -X POST \
    -H "X-AS24-Version: 1.1"  \
    -H "Accept-Language: en-GB" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf" \
    -d '{ \
      "videoUrl": "https://www.youtube.com/watch?v=wnKJnWRa_Ks" \
    }'

Attach a new vehicle youtube video.

Anforderungen an Videos von AutoScout24: Die eingestellten Videos dürfen nur das von Ihnen angebotene Fahrzeug wiedergeben. Sie verpflichten sich, nur solche Videos einzustellen, die nicht gegen Rechte Dritter verstoßen. Die verwendeten Videos dürfen nicht irreführend sein und müssen den tatsächlichen Zustand des angebotenen Fahrzeugs widerspiegeln. AutoScout24 weist Sie darauf hin, dass bei der Erstellung der Videos die geltenden gesetzlichen Vorschriften, für gewerbliche Anbieter insbesondere die „Preisangabenverordnung“ (PAngV) oder die „Verordnung über Verbraucherinformationen zu Kraftstoffverbrauch und CO2-Emissionen neuer Personenkraftwagen“ (PKW-EnVKV) zu beachten sind.

AutoScout24 hat das Recht, Videos, die die oben stehenden Anforderungen nicht erfüllen oder gegen die Nutzungsbedingungen von YouTube verstoßen, zu löschen.

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Content-Type String Yes The mediatype used for the body of the request. It should be: application/json
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Payload Parameters

Note: string length is counted as total of UFT-8 characters.

Field Name Type Mandatory Format Description
videoUrl string yes youtube video URL The URL of the vehicle video to be attached.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/videos/e1f3ac50-c184-42cc-b9e0-a82c141929b1"
    }
  },
  "_request": {
    "url": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee//videos",
    "body": "\"https://www.youtube.com/watch?v=XwhHYuP8Lfk\"",
    "method": "POST"
  },
  "_response": {
    "type": "Success",
    "objectId": "e1f3ac50-c184-42cc-b9e0-a82c141929b1"
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Endpoint

GET /vehicles/{vehicleId}/videos

Request Example

Retrieve the videos of a vehicle with id = 7e59591f-c5a3-974e-e452-2951040ae4ee:

curl https://api.autoscout24.com/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/videos \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer 73a06d83-6e13-4444-a288-6aa8c4098c2f"

Parameters

Parameter Name Type Mandatory Description
vehicleId URI Parameter Yes Unique identifier for a given vehicle.
imageId URI Parameter Yes Unique identifier for a given image.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Accept String Yes
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/videos"
    },
    "videos": [{
      "href": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/videos/e1f3ac50-c184-42cc-b9e0-a82c141929b1"
      }]
  },
  "_request": {
    "url": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/videos",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success"
  },
  "_data": {
    "videos": [{
      "id": "e1f3ac50-c184-42cc-b9e0-a82c141929b1",
      "url": "https://www.youtube.com/watch?v=XwhHYuP8Lfk"
      }]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Videos Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
videos array, Video An array that holds the video objects.

Video Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
id String The unique ID of the vehicles’ youtube video.
url String The URL of the youtube video that’s attached to the vehicle.

Retrieve a video

Endpoint

GET /vehicles/{vehicleId}/videos/{videoId}

Request Example

Retrieve the video of id = e1f3ac50-c184-42cc-b9e0-a82c141929b1 for the vehicle with id = b78d27e2-671a-47w6-80ab-d3726d7782c7:

curl https://api.autoscout24.com/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/videos/e1f3ac50-c184-42cc-b9e0-a82c141929b1 \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer 73a06d83-6e13-4444-a288-6aa8c4098c2f"

Retrieve details of an existing vehicle’s youtube video.

Parameters

Parameter Name Type Mandatory Description
vehicleId URI Parameter Yes Unique identifier for a given vehicle.
videoId URI Parameter Yes Unique identifier for a given video.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Accept String Yes The mediatype to be received e.g. application/json.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/videos/e1f3ac50-c184-42cc-b9e0-a82c141929b1"
    },
  },
  "_request": {
    "url": "/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/videos/e1f3ac50-c184-42cc-b9e0-a82c141929b1",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success",
    "objectId": "e1f3ac50-c184-42cc-b9e0-a82c141929b1"
  },
  "_data": {
    "video": {
      "id": "e1f3ac50-c184-42cc-b9e0-a82c141929b1",
      "url": "https://www.youtube.com/watch?v=XwhHYuP8Lfk"
    }
  }
}

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Video Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
video Video An object that contains information about the requested video object.

Video Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
videoUrl String The URL of the youtube video that’s attached to the vehicle.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Delete a Video

Endpoint

DELETE /vehicles/{vehicleId}/videos/{videoId}

Response Example

Delete the video with id = e1f3ac50-c184-42cc-b9e0-a82c141929b1 of the vehicle with ID = b78d27e2-671a-47w6-80ab-d3726d7782c7:

curl https://api.autoscout24.com/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/videos/e1f3ac50-c184-42cc-b9e0-a82c141929b1 \
     -X DELETE \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf"

Delete an existing vehicle’s video.

Parameters

Parameter Name Type Mandatory Description
vehicleId URI Parameter Yes Unique identifier for a given vehicle.
videoId URI Parameter Yes Unique identifier for a given video.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": null
    }
  },
  "_request": {
    "url": "/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/videos/e1f3ac50-c184-42cc-b9e0-a82c141929b1",
    "body": null,
    "method": "DELETE"
  },
  "_response": {
    "type": "Success",
    "messages": [
      {
    "code": 10004,
    "messageType": "Info",
    "text": "Video with id e1f3ac50-c184-42cc-b9e0-a82c141929b1 was successfully deleted."
      }
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Resource - Publications

The Publications resource is a sub-resource of the Vehicle resource. It manages the complete lifecycle of the vehicle on AutoScout24 channels. Using this resource, a vehicle can be made available or inavailable on AutoScout24’s marketplaces.

Retrieve Channels

Endpoint

GET /vehicles/{vehicleId}/publications

Request Example

Retrieve the publication channels of a vehicle with id = 7e59591f-c5a3-974e-e452-2951040ae4ee:


curl https://api.autoscout24.com/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/publications \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf" 

Retrieve publication status of an existing vehicle.

Response shows whether at all and where a given vehicle has been published. Vehicles can be published to different publication channels (e.g. Publication channel ‘AS24’ means that the vehicle is visible on the AutoScout24 platform. Similarly, publication channel ‘AS24Dealer’ means that the vehicle is visible on AutoScout24’s dealer platform). In addition, the response message holds information about the URI of the vehicle on each published channel. Please note that the URI might take some minutes before it becomes available.

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB. Please note that this header is also used to identify the marketplace URL of the vehicle’s listing e.g. de-DE would return the URL of the vehicle on the German marketplace. Possible values are: de-DE , de-AT , fr-BE , fr-LU , fr-FR , nl-NL , nl-BE , es-ES , it-IT , en-GB. If the value of this header is not specified, then the default culture en-GB is used.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/publications"
    }
  },
  "_request": {
    "url": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/publications",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success"
  },
  "_data": {
    "publicationchannels": [
      {
        "channelId": "AS24",
        "url": "http://ww3.autoscout24.de/classified/979814201"
      },
      {
        "channelId": "AS24Dealers",
        "url": "http://ww3.autoscout24.de/classified/979814201"
      }
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Publication Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
publicationChannels array, Enum The array that has information of which channel the vehicle is published on. Possible values are: “AS24Dealers” and/or “AS24”

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Publish a Vehicle

Endpoint

POST /vehicles/{vehicleId}/publications/{channelId}

Request Example

Publish the vehicle with id = 7e59591f-c5a3-974e-e452-2951040ae4ee on AutoScout24’s platform :

curl https://api.autoscout24.com/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/publications/AS24 \
     -X POST 
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf" 

Publish an existing vehicle on a specific channel defined by its ID.

Vehicles can be published to different publication channels (e.g. Publication channel ‘AS24’ means that the vehicle is visible on the AutoScout24 platform. Similarly, publication channel 'AS24Dealer’ means that the vehicle is visible on AutoScout24’s dealer platform). In addition, the response message holds information about the URI of the vehicle on each published channel. Please note that the URI might take some minutes before it becomes available.

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.
channelId URI Parameter Yes Unique identifier for the channel to publish the vehicle on. Possible values are: “AS24Dealers” or “AS24”.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB. Please note that this header is also used to identify the marketplace URI of the vehicle’s listing e.g. de-DE would return the URI of the vehicle on the German marketplace. Possible values are: de-DE , de-AT , fr-BE , fr-LU , fr-FR , nl-NL , nl-BE , es-ES , it-IT , en-GB. If the value of this header is not specified, then the default culture en-GB is used.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/publications"
    }
  },
  "_request": {
    "url": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/publications/AS24",
    "body": null,
    "method": "POST"
  },
  "_response": {
    "type": "Success",
    "messages": [
      {
        "code": 10500,
        "messageType": "Info",
        "text": "Vehicle URL on PublicationChannel AS24 is: { http://ww3.autoscout24.de/classified/979814201 }. Please note that it might take a couple of minutes before the URI becomes available."
      }
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Unpublish a Vehicle

Endpoint

DELETE /vehicles/{vehicleId}/publications/{chanelId}

Request Example

Unpublish the vehicle with id = 7e59591f-c5a3-974e-e452-2951040ae4ee from AutoScout24’s platform :

curl https://api.autoscout24.com/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/publications/AS24 \
     -X DELETE 
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf" 

Unpublish existing vehicle from a specific publication channel.

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.
channelId URI Parameter Yes Unique identifier for the channel to publish the vehicle on. Possible values are: “AS24Dealers” or “AS24”.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": null
    }
  },
  "_request": {
    "url": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/publications/AS24",
    "body": null,
    "method": "DELETE"
  },
  "_response": {
    "type": "Success"
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Resource - Products

The Products resource is a sub-resource of the Vehicle resource. It manages the lifecycle of advertising products that can be atached to an existing vehicle.

Book an Ad Product

Endpoint

POST /vehicles/{vehicleId}/products

Request Example

Book a premium ad product for a vehicle with id = 7e59591f-c5a3-974e-e452-2951040ae4ee:


curl https://api.autoscout24.com/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/products \
     -X POST \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf" \
     -d '{ \
            "productId": "T30", \
            "subtitle": "Amazing Car" \
         }'

Attach an ad product to an existing vehicle.

Please note that product bookings will be charged to the dealer in question on a daily basis.

For product bookings an optional subtitle can be posted (Type=string, maxLength=55). Subtitles will be shown as part of the vehicle information on a search result list page. The additional subtitle can be used to further highlight specific features of a vehicle.

Semantic Rules

The following semantic rules are applied when booking an ad product to a vehicle.

Allowed products ( Only for dealers in Germany, France, Belgium, Luxemburg):

T30 = PremiumInserat (max. 30 images will be shown as part of the vehicle ad)

T20 = PlusInserat (max. first 20 images will be shown as part of the vehicle ad)

Important information:

Attention: Product bookings for „PremiumInserat“ (T30) or „PlusInserat“ (T20) via API are being rejected if the dealer has activated automatic booking rules for his stock on AutoScout24.de. Either T30 or T20 can be attached to a vehicle – not both at the same time. Should you wish to switch from T30 to T20 or vice versa you must delete the existing product booking first.

Detailed information on these ad products in Germany can be found by clicking here.

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Content-Type String No The mediatype used for the body of the request. It should be: application/json
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Payload Parameters

Note: string length is counted as total of UFT-8 characters.

Field Name Type Mandatory Format Description
productId string yes The ID of the ad product to be booked. Allowed values: T30, T20
subtitle string No maxLength=55 Subtitles will be shown as part of the vehicle information on a search result list page. The additional subtitle can be used to further highlight specific features of a vehicle.

Response Example


{
  "_links": {
    "self": {
      "href": null
    }
  },
  "_request": {
    "url": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/products",
    "body": "{\"productId\":\"T30\",\"subtitle\":\"Amazing Car\"}",
    "method": "POST"
  },
  "_response": {
    "type": "Success"
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Retrieve Booked Ad Product

Endpoint

GET /vehicles/{vehicleId}/products

Request Example

Retrieve the booked ad product of a vehicle with id = 7e59591f-c5a3-974e-e452-2951040ae4ee:

curl https://api.autoscout24.com/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/products \
     -X GET
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf"

Retrieve ad product information for an existing vehicle.

Response shows whether at all and which ad product(s) are currently assigned to a given vehicle. Accompanying, optional subtitle will also be returned.

Attention: A response showing product = T10 means that no paid ad product has been booked for this vehicle (T10 is the standard ad product “BasicInserat”).

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/products"
    },
    "products": [
      {
        "href": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/products/T30"
      }
    ]
  },
  "_request": {
    "url": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/products",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success"
  },
  "_data": {
    "products": [
      {
        "productId": "T30",
        "subtitle": "Amazing Car"
      }
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Products Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
products array,Product An array that contains information about the booked products.

Product Object

Field Name Type Description
name String Name of the booked product.
productId String A unique identifier of the booked product.
subtitle String The additional subtitle can be used to further highlight specific features of a vehicle.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Terminate Ad Booking

Endpoint

DELETE /vehicles/{vehicleId}/products/{productId}

Request Example

Terminate the T30 booking of the vehicle with id = b78d27e2-671a-47w6-80ab-d3726d7782c7:


curl https://api.autoscout24.com/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/product/T30 \
     -X DELETE \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf"

Terminate an existing product booking for a given vehicle.

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.
productId URI Parameter Yes Unique identifier for a given product.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": null
    }
  },
  "_request": {
    "url": "/vehicles/b78d27e2-671a-47w6-80ab-d3726d7782c7/products/T30",
    "body": null,
    "method": "DELETE"
  },
  "_response": {
    "type": "Success",
    "messages": [
      {
        "code": 10003,
        "messageType": "Info",
        "text": "Product with id T30 was succesfully deleted."
      }
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Resource - Financing Offers

The Financing Offers resource is a sub-resource of the Vehicle resource. It manages the complete lifecycle of the financing offer of a specific vehicle on the AutoScout24 marketplace. This includes creating, updating, retrieving, and deleting a financing offer of a vehicle.

Create a Financing Offer

Endpoint

POST /vehicles/{vehicleId}/financingoffers

Request Example

Create a financing offer and attaching it to a vehicle with id = 7e59591f-c5a3-974e-e452-2951040ae4ee:


curl https://api.autoscout24.com/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/financingoffers \
     -X POST \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Content-Type: application/json"
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf" \
     -d '{ \
      "annualPercentageRate": 4.99, \
      "bank": "Mercedes-Benz Bank AG, Siemensstraße 7, 70469 Stuttgart", \
      "currency": "EUR", \
      "debitInterestType": 1, \
      "debitInterestRate": 4.25, \
      "duration": 12, \
      "endingRate": 350.12, \
      "financingType": "C", \
      "grossCreditAmount": 6789.88, \
      "initialPayment": 20.15, \
      "monthlyRate": 300.63, \
      "netCreditAmount": 4900.21, \
      "paymentProtectionInsurance": 13.22 \
    }'

Add a new financing offer to the vehicle. (This is only available to dealers in Germany, Italy, Netherlands and Belgium.)

Please note that AutoScout24 can only add one financing offer per vehicle at the moment.

Semantic Rules

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Content-Type String Yes The mediatype used for the body of the request. It should be: application/json
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Payload Parameters

Note: string length is counted as total of UFT-8 characters.

Field Name Type Mandatory Format Description
annualPercentageRate Number yes Only between 0.00 and 99.99 Annual percentage rate in %.
bank string yes 600 character allowed Name, legal form, address, postal code and city of bank partner need to be transmitted here (e.g. Mercedes-Benz Bank AG, Siemensstraße 7, 70469 Stuttgart) as well as other financing offer conditions: Please indicate here whether your financing offer requires the conclusion of an insurance contract or a contract for other supplementary benefits. If the cost of this contract cannot be determined in advance, please indicate the obligation to conclude this contract (e.g. compulsory conclusion of a comprehensive insurance contract).
debitInterestType Enum yes Values: 1=bound , 2=changeable , 3=combined Debit interest type (bound, changeable, combined) needs to be specified.
debitInterestRate Number yes Only between 0.00 and 99.99 Debit interest rate in %
duration Integer yes Only between 1 - 999 Indicates the duration of the loan contract in months.
endingRate Number no Only between 0.00 and 999999999.99 Ending Rate in EUR.
financingType Enum yes Values: C=Credit Financing type needs to be specified. Currently only Credit type can be selected.
grossCreditAmount Number yes Only between 0.01 and 999999999.99 Gross credit amount in EUR.
initialPayment Number no Only between 0.00 and 999999.99 Initial payment if applicable for the loan in EUR.
monthlyRate Number yes Only between 0.00 and 999999999.99 Monthly rate in EUR.
netCreditAmount Number yes Only between 0.00 and 999999999.99 Net credit amount in EUR.
paymentProtectionInsurance Number no Only between 0.00 and 999999999.99 Payment protection insurance in EUR.

Response Example


{
  "_links": {
    "self": {
      "href": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/financingoffers/7e59591f-c5a3-974e-e452-2951040ae4ee"
    }
  },
  "_request": {
    "url": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/financingoffers",
    "body": "{\"bank\":\"Mercedes-Benz Bank AG, Siemensstraße 7, 70469 Stuttgart\",\"debitInterestType\":1,\"financingType\":\"C\",\"currency\":\"EUR\",\"endingRate\":350.12,\"duration\":12,\"initialPayment\":20.15,\"debitInterestRate\":4.25,\"annualPercentageRate\":4.99,\"monthlyRate\":300.63,\"grossCreditAmount\":6789.88,\"netCreditAmount\":4900.21,\"paymentProtectionInsurance\":13.22}",
    "method": "POST"
  },
  "_response": {
    "type": "Success",
    "objectId": "7e59591f-c5a3-974e-e452-2951040ae4ee"
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Retrieve Financing Offers

Endpoint

GET /vehicles/{vehicleId}/financingoffers

Request Example

Retrieve all the financing offers of a vehicle with id = 7e59591f-c5a3-974e-e452-2951040ae4ee:

curl https://api.autoscout24.com/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/financingoffers \
     -X GET
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf"

Retrieve a collection of all available financing offers for a specific vehicle. (This is only available to the dealers in Germany, Italy, Netherland and Belgium.)

At the moment, only one offer can be added and retrieved for a specific vehicle.

Semantic Rules

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/financingoffers"
    },
    "financingoffers": [
      {
        "href": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/financingoffers/7e59591f-c5a3-974e-e452-2951040ae4ee"
      }
    ]
  },
  "_request": {
    "url": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/financingoffers",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success"
  },
  "_data": {
    "financingoffers": [
      {
        "bank": "Mercedes-Benz Bank AG, Siemensstraße 7, 70469 Stuttgart",
        "debitInterestType": 1,
        "financingType": "C",
        "currency": "EUR",
        "endingRate": 350.12,
        "duration": 12,
        "initialPayment": 20.15,
        "debitInterestRate": 4.25,
        "annualPercentageRate": 4.99,
        "monthlyRate": 300.63,
        "grossCreditAmount": 6789.88,
        "netCreditAmount": 4900.21,
        "paymentProtectionInsurance": 13.22
      }
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Financing Offers Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
financingoffers array, FinancingOffer An array that holds the vehicle objects.

Financing Offer Object

Field Name Type Format Description
annualPercentageRate Number Only between 0.00 and 99.99 Annual percentage rate in %.
bank string yes 150 character allowed
debitInterestType Enum Values: 1=bound , 2=changeable , 3=combined Debit interest type (bound, changeable, combined) needs to be specified.
debitInterestRate Number Only between 0.00 and 99.99 Debit interest rate in %
duration Integer Only between 1 - 999 Indicates the duration of the loan contract in months.
endingRate Number no Only between 0.00 and 999999999.99
financingType Enum Values: C=Credit Financing type needs to be specified. Currently only Credit type can be selected.
grossCreditAmount Number Only between 0.01 and 999999999.99 Gross credit amount in EUR.
initialPayment Number Only between 0.00 and 999999.99 Initial payment if applicable for the loan in EUR.
monthlyRate Number Only between 0.00 and 999999999.99 Monthly rate in EUR.
netCreditAmount Number Only between 0.00 and 999999999.99 Net credit amount in EUR.
paymentProtectionInsurance Number Only between 0.00 and 999999999.99 Payment protection insurance in EUR.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Retrieve a Financing Offer

Endpoint

GET /vehicles/{vehicleId}/financingoffers/{financingOfferId}

Request Example

Retrieve the financing offer of id = 7e59591f-c5a3-974e-e452-2951040ae4ee for the vehicle with id = 7e59591f-c5a3-974e-e452-2951040ae4ee:

curl https://api.autoscout24.com/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/financingoffers/7e59591f-c5a3-974e-e452-2951040ae4ee \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer 73a06d83-6e13-4444-a288-6aa8c4098c2f"

Retrieve the given financing offer information of a specific vehicle. (This is only avaialble to the dealers in Germany, Italy, Netherland and Belgium).

Currently, only one offer can be added and retrieved for a specific vehicle.

Semantic Rules

Parameters

Parameter Name Type Mandatory Description
vehicleId URI Parameter Yes Unique identifier for a given vehicle.
financingOfferId URI Parameter Yes Unique identifier for a given financing offer.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/financingoffers/7e59591f-c5a3-974e-e452-2951040ae4ee"
    }
  },
  "_request": {
    "url": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/financingoffers/7e59591f-c5a3-974e-e452-2951040ae4ee",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success",
    "objectId": "7e59591f-c5a3-974e-e452-2951040ae4ee"
  },
  "_data": {
    "financingoffer": {
      "bank": "Mercedes-Benz Bank AG, Siemensstraße 7, 70469 Stuttgart",
      "debitInterestType": 1,
      "financingType": "C",
      "currency": "EUR",
      "endingRate": 350.12,
      "duration": 12,
      "initialPayment": 20.15,
      "debitInterestRate": 4.25,
      "annualPercentageRate": 4.99,
      "monthlyRate": 300.63,
      "grossCreditAmount": 6789.88,
      "netCreditAmount": 4900.21,
      "paymentProtectionInsurance": 13.22
    }
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Financing Offer Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
financingoffer FinancingOffer An array that holds the vehicle objects.

Financing Offer Object

Field Name Type Format Description
annualPercentageRate Number Only between 0.00 and 99.99 Annual percentage rate in %.
bank string yes 150 character allowed
debitInterestType Enum Values: 1=bound , 2=changeable , 3=combined Debit interest type (bound, changeable, combined) needs to be specified.
debitInterestRate Number Only between 0.00 and 99.99 Debit interest rate in %
duration Integer Only between 1 - 999 Indicates the duration of the loan contract in months.
endingRate Number no Only between 0.00 and 999999999.99
financingType Enum Values: C=Credit Financing type needs to be specified. Currently only Credit type can be selected.
grossCreditAmount Number Only between 0.01 and 999999999.99 Gross credit amount in EUR.
initialPayment Number Only between 0.00 and 999999.99 Initial payment if applicable for the loan in EUR.
monthlyRate Number Only between 0.00 and 999999999.99 Monthly rate in EUR.
netCreditAmount Number Only between 0.00 and 999999999.99 Net credit amount in EUR.
paymentProtectionInsurance Number Only between 0.00 and 999999999.99 Payment protection insurance in EUR.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Update a Financing Offer

Endpoint

PUT /vehicles/{vehicleId}/financingoffers/{financingOfferId}

Request Example

Update the financing offer with id = 7e59591f-c5a3-974e-e452-2951040ae4ee of the vehicle with id = 7e59591f-c5a3-974e-e452-2951040ae4ee:


curl https://api.autoscout24.com/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/financingoffers/7e59591f-c5a3-974e-e452-2951040ae4ee \
     -X PUT \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Content-Type: application/json"
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf" \
     -d '{ \
      "annualPercentageRate": 4.99, \
      "bank": "Santander Consumer Bank AG, Neue Brücke 1, 70173 Stuttgart", \
      "currency": "EUR", \
      "debitInterestType": 1, \
      "debitInterestRate": 4.25, \
      "duration": 12, \
      "endingRate": 350.12, \
      "financingType": "C", \
      "grossCreditAmount": 6789.88, \
      "initialPayment": 20.15, \
      "monthlyRate": 300.63, \
      "netCreditAmount": 4900.21, \
      "paymentProtectionInsurance": 13.22 \
    }'

Update the information of the given financing offer. (This is only available to the dealers in Germany, Italy, Netherlands and Belgium.)

Semantic Rules

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.
financingOfferId URI Parameter Yes Unique identifier for a given financing offer.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Content-Type String Yes The mediatype used for the body of the request. It should be: application/json
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Payload Parameters

Note: string length is counted as total of UFT-8 characters.

Field Name Type Mandatory Format Description
annualPercentageRate Number yes Only between 0.00 and 99.99 Annual percentage rate in %.
bank string yes 150 character allowed Name, legal form, address, postal code and city of bank partner need to be transmitted. e.g. Mercedes-Benz Bank AG, Siemensstraße 7, 70469 Stuttgart
debitInterestType Enum yes Values: 1=bound , 2=changeable , 3=combined Debit interest type (bound, changeable, combined) needs to be specified.
debitInterestRate Number yes Only between 0.00 and 99.99 Debit interest rate in %
duration Integer yes Only between 1 - 999 Indicates the duration of the loan contract in months.
endingRate Number no Only between 0.00 and 999999999.99 Ending Rate in EUR.
financingType Enum yes Values: C=Credit Financing type needs to be specified. Currently only Credit type can be selected.
grossCreditAmount Number yes Only between 0.01 and 999999999.99 Gross credit amount in EUR.
initialPayment Number no Only between 0.00 and 999999.99 Initial payment if applicable for the loan in EUR.
monthlyRate Number yes Only between 0.00 and 999999999.99 Monthly rate in EUR.
netCreditAmount Number yes Only between 0.00 and 999999999.99 Net credit amount in EUR.
paymentProtectionInsurance Number no Only between 0.00 and 999999999.99 Payment protection insurance in EUR.

Response Example

{
  "_links": {
    "self": {
      "href": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/financingoffers/7e59591f-c5a3-974e-e452-2951040ae4ee"
    }
  },
  "_request": {
    "url": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/financingoffers/7e59591f-c5a3-974e-e452-2951040ae4ee",
    "body": "{\"bank\":\"Santander Consumer Bank AG, Neue Brücke 1, 70173 Stuttgart\",\"debitInterestType\":1,\"financingType\":\"C\",\"currency\":\"EUR\",\"endingRate\":350.12,\"duration\":12,\"initialPayment\":20.15,\"debitInterestRate\":4.25,\"annualPercentageRate\":4.99,\"monthlyRate\":300.63,\"grossCreditAmount\":6789.88,\"netCreditAmount\":4900.21,\"paymentProtectionInsurance\":13.22}",
    "method": "PUT"
  },
  "_response": {
    "type": "Success",
    "objectId": "7e59591f-c5a3-974e-e452-2951040ae4ee"
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Delete a Financing Offer

Endpoint

DELETE /vehicles/{vehicleId}/images/{imageId}

Request Example

Delete the financing offer with id = 7e59591f-c5a3-974e-e452-2951040ae4ee of the vehicle with ID = 7e59591f-c5a3-974e-e452-2951040ae4ee:


curl https://api.autoscout24.com/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/financingoffers/7e59591f-c5a3-974e-e452-2951040ae4ee \
     -X DELETE \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer e7c00b24-9f5f-4909-88de-38f8d7ca08bf"

Delete an existing vehicle’s financing offer.

Parameters

Parameter Name Type Mandatory Description
vehicleID URI Parameter Yes Unique identifier for a given vehicle.
financingOfferId URI Parameter Yes Unique identifier for a given financing offer.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": null
    }
  },
  "_request": {
    "url": "/vehicles/7e59591f-c5a3-974e-e452-2951040ae4ee/financingoffers/7e59591f-c5a3-974e-e452-2951040ae4ee",
    "body": null,
    "method": "DELETE"
  },
  "_response": {
    "type": "Success"
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Resource - Statistics

The Statistics resource offers information about the performance of vehicle listings. Using this resource, performance metrics about the entire stock of the dealer as well as individual vehicles are offered. Performance metrics could be used to measure the success of dealer’s offers which could lead to better learning and understanding of how these offers could also be further improved.

Retrieve Dealer’s Stock Statistics

Endpoint

GET /statistics?start={startDate}&end={endDate}

Request Example

Get the aggregated dealer’s stock statistics between 2015-11-15 and 2015-12-15:

curl https://api.autoscout24.com/statistics?start=2015-11-15&end=2015-12-15 \
    -X GET \
    -H "X-AS24-Version: 1.1"  \
    -H "Accept-Language: en-GB"

Retrieve performance metrics of the dealers stock. Using this endpoint, aggregated performance metrics of all the vehicles that are available (published and unpublished) on the AutoScout24 marketplace are offered.

Semantic Rules

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Query Parameters

Query parameter Name Data Type Mandatory Description
start date Yes The start date of when to fetch statistics. This value should be represented based on the ISO 8601 format: YYYY-MM-dd
end date Yes The end date for the date period to fetch statistics. This value should be represented based on the ISO 8601 format: YYYY-MM-dd

Response Example

{
  "_links": {
    "self": {
      "href": "/statistics"
    }
  },
  "_request": {
    "url": "/statistics",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success"
  },
  "_data": {
    "stockstatistics": {
      "vehiclesCount": 49,
      "standingDays": {
        "average": 21,
        "competition": {
          "radius25Average": 23,
          "radius50Average": 26,
          "radius100Average": 28
        }
      },
      "performanceStats": {
        "start": "2015-11-15",
        "end": "2015-12-15",
        "searches": {
          "totalCount": 640,
          "averagePerDay": 21.33
        },
        "views": {
          "totalCount": 161,
          "averagePerDay": 5.36
        },
        "bookmarks": {
          "totalCount": 45,
          "averagePerDay": 1.5
        },
        "leads": {
          "calls": {
            "totalCount": 35,
            "averagePerDay": 1.16
          },
          "emails": {
            "totalCount": 56,
            "averagePerDay": 1.86
          },
          "printOuts": {
            "totalCount": 15,
            "averagePerDay": 0.5
          },
          "totalCount": 106,
          "averagePerDay": 3.53
        }
      }
    }
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Dealer’s stock statistics Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
stockStatistics StockStatistics The object that has statistics information.

StockStatistics Object

Field Name Type Description
standingDays StandingDays The object that holds standing days statistics of the dealer’s stock.
performanceStats PerformanceStats The object that has the performance statistics of the dealer’s stock within the specified period of time.

StandingDays Object

Field Name Type Description
average number The average standing days of the entire dealer’s stock.
competition Competition The object that has the statistics of the performance statistics of the specified period of time.

Competition Object

Field Name Type Description
radius25Average number The average standing days of dealer’s competitors within a radius of 25 KM.
radius50Average number The average standing days of dealer’s competitors within a radius of 50 KM.
radius100Average number The average standing days of dealer’s competitors within a radius of 100 KM.

PerformanceStats Object

Field Name Type Description
start date The start date of the period to which the performance statistics have been returned.
end date The end date of the period to which the performance statistics have been returned.
searches Searches The object that has the search KPIs of the entire stock of the dealer within the specified date period.
views Views The object that has the vehicle classifieds’ detail page views KPIs of the entire stock of the dealer within the specified date period.
bookmarks Bookmarks The object that has the bookmark KPIs of the entire stock of the dealer within the specified date period.
leads Leads The object that has the leads KPIs of the entire stock of the dealer within the specified date period.

Searches Object

Field Name Type Description
totalCount integer The total number of appearances of the vehicles of the dealer in the list page of any search criteria within the specified date period
averagePerDay number The average value per day of the appearance of the dealer’s vehicle listings in the list page of any search criteria within the specified date period.

Views Object

Field Name Type Description
totalCount integer The total number of detail page views of the dealer’s vehicle listings within the specified date period.
averagePerDay number The average value per day of the detail page views of the dealer’s vehicle listings within the specified date period.

BookMarks Object

Field Name Type Description
totalCount integer The total number of bookmarks of the dealer’s vehicle listings within the specified date period.
averagePerDay number The average value per day of bookmarks of the dealer’s vehicle listings within the specified date period.

Leads Object

Field Name Type Description
totalCount integer The total number of leads of the dealer’s vehicle listings within the specified date period.
averagePerDay number The average value per day of leads of the dealer’s vehicle listings within the specified date period.
emails Emails The object that has the emails KPIs of the entire stock of the dealer within the specified date period.
printOuts Printouts The object that has the printouts KPIs of the entire stock of the dealer within the specified date period.
calls Calls The object that has the calls KPIs of the entire stock of the dealer within the specified date period.

Emails Object

Field Name Type Description
totalCount integer The total number of emails sent to the dealer within the specified date period.
averagePerDay number The average value per day of the emails sent to the dealer within the specified date period.

Printouts Object

Field Name Type Description
totalCount integer The total number of printouts of the dealer’s vehicle listings within the specified date period.
averagePerDay number The average value per day of printouts of the dealer’s vehicle listings within the specified date period.

Calls Object

Field Name Type Description
totalCount integer The total number of calls the dealer has received within the specified date period.
averagePerDay number The average value per day of calls the dealer has received within the specified date period.

Retrieve Vehicles’ Statistics

Endpoint

GET /statistics/{id}?start={startDate}&end={endDate}

Request Example

Get the statistics of the vehicle with ID = b78d27e2-671a-47w6-80ab-d3726d7782c7 between 2015-11-15 and 2015-12-15:

curl https://api.autoscout24.com/statistics/b78d27e2-671a-47w6-80ab-d3726d7782c7?start=2015-11-15&end=2015-12-15 \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Authorization: Bearer 73a06d83-6e13-4444-a288-6aa8c4098c2f"

Retrieve performance metrics of a specific vehicle. Using this endpoint, performance metrics of a vehicle that is available (published and unpublished) on the AutoScout24 marketplace are offered.

Semantic Rules

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.

Query parameters

Query parameter Name Data Type Mandatory Description
start date yes The start date of when to fetch statistics. This value should be represented based on the ISO 8601 format: YYYY-MM-dd
end date yes The end date for the date period to fetch statistics. This value should be represented based on the ISO 8601 format: YYYY-MM-dd

Response Example

{
  "_links": {
    "self": {
      "href": "/statistics/b78d27e2-671a-47w6-80ab-d3726d7782c7"
    }
  },
  "_request": {
    "url": "/statistics/b78d27e2-671a-47w6-80ab-d3726d7782c7",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success"
  },
  "_data": {
    "vehiclestatistics": {
      "creationDate": "2015-11-10",
      "standingDays": {
        "total": 35
      },
      "currentBookmarks": 3,
      "imageCount": 15,
      "videoCount": 0,
      "performanceStats": {
        "start": "2015-11-15",
        "end": "2016-12-15",
        "searches": {
          "totalCount": 42,
          "averagePerDay": 1.2
        },
        "views": {
          "totalCount": 19,
          "averagePerDay": 0.63
        },
        "bookmarks": {
          "totalCount": 9,
          "averagePerDay": 0.3
        },
        "leads": {
          "calls": {
            "totalCount": 5,
            "averagePerDay": 0.16
          },
          "emails": {
            "totalCount": 6,
            "averagePerDay": 0.2
          },
          "printOuts": {
            "totalCount": 1,
            "averagePerDay": 0.03
          },
          "totalCount": 12,
                    "averagePerDay": 0.4
        }
      }
    }
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Vehicle’s statistics Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
vehicleStatistics VehicleStatistics The object that has statistics information.

VehicleStatistics Object

Field Name Type Description
creationDate Date The creation date of the vehicle on the AutoScout24 marketplace.
standingDays StandingDays The object that holds standing days statistics of the vehicle.
currentBookmarks integer The number of bookmarks the vehicle has. This value is calculated once a day.
imageCount integer The number of images the vehicle has.
video integer The number of videos the vehicle has. Please note that AutoScout24 supports only one video upload currently.
performanceStats PerformanceStats The object that has the performance statistics of the vehicle within specified period of time.

StandingDays Object

Field Name Type Description
total integer The total number of standing days of the vehicle.

PerformanceStats Object

Field Name Type Description
start date The start date of the period to which the performance statistics have been returned.
end date The end date of the period to which the performance statistics have been returned.
searches Searches The object that has the search KPIs of the vehicle within the specified date period.
views Views The object that has the vehicle classified’s detail page views KPIs within the specified date period.
bookmarks Bookmarks The object that has the bookmark KPIs of the vehicle within the specified date period.
leads Leads The object that has the leads KPIs of the vehicle within the specified date period.

Searches Object

Field Name Type Description
totalCount integer The total number of appearances of the vehicle in the list page of any search criteria within the specified date period.
averagePerDay number The average value per day of the appearance of vehicle listing in the list page of any search criteria within the specified date period.

Views Object

Field Name Type Description
totalCount integer The total number of detail page views of the vehicle listing within the specified date period.
averagePerDay number The average value per day of the detail page views of the vehicle listing within the specified date period.

BookMarks Object

Field Name Type Description
totalCount integer The total number of bookmarks of the vehicle listing within the specified date period.
averagePerDay number The average value per day of bookmarks of the vehicle listing within the specified date period.

Leads Object

Field Name Type Description
totalCount integer The total number of leads of the vehicle listing within the specified date period.
averagePerDay number The average value per day of leads of the vehicle listing within the specified date period.
emails Emails The object that has the emails KPIs of the vehicle within the specified date period.
printOuts Printouts The object that has the printouts KPIs of the vehicle within the specified date period.
calls Calls The object that has the calls KPIs of the vehicle within the specified date period.

Emails Object

Field Name Type Description
totalCount integer The total number of emails sent to the dealer for the vehicle within the specified date period.
averagePerDay number The average value per day of the emails sent to the dealer for the vehicle within the specified date period.

Printouts Object

Field Name Type Description
totalCount integer The total number of printouts of the vehicle listing within the specified date period.
averagePerDay number The average value per day of printouts of the vehicle listing within the specified date period.

Calls Object

Field Name Type Description
totalCount integer The total number of calls the dealer has received for the vehicle within the specified date period.
averagePerDay number The average value per day of calls the dealer has received for the vehicle within the specified date period.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Resource - CustomerDetails

The CustomerDetails resource is used to display customer details based on the authentication token. The information retrieved includes the customer identification number (Sell-ID) this token is linked to.

Retrieve customer details

Endpoint

GET /customerdetails

Request Example

Retrieve the customer details for access token = 73a06d83-6e13-4444-a288-6aa8c4098c2f

curl https://api.autoscout24.com/customerdetails \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer 73a06d83-6e13-4444-a288-6aa8c4098c2f"

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.
Accept String Yes The mediatype to be received e.g. application/json.
Authorization String Yes The Bearer authentication token that was received via the OAuth authentication process.

Response Example

{
  "_links": {
    "self": {
      "href": "/customerdetails"
    }
  },
  "_request": {
    "url": "/customerdetails",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success"
  },
  "_data": {
    "customerdetails": {
      "sellId": "2142082683",
      "companyName": "VM TEST ACCOUNT",
      "address": {
        "street": "Am Falm 313",
        "zipCode": "27498",
        "city": "Helgoland",
        "country": "DE"
      }
    }
  }
}

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Customer Details Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
customerdetails Customer Details An object that contains information about the requested customer details.

Customer Details Object

The following table shows the fields that are contained in the customerdetails object of the Response Payload:

Field Name Type Description
sellId String Customer identification number (Sell-ID) from the AutoScout24 CRM system
companyName String The name of the customer company
address Object Object containing details of the address of the customer

Customer Details Address Object

The following table shows the fields that are contained in the address object of the Response Payload:

Field Name Type Description
street String Main street of the customer
zipCode String The ZIP code of the customer
city String The city of the customer
country String The country of the customer

Resource - Makes

The Makes resource offers the needed endpoints to retrieve information about the available makes that are supported by the AutoScout24 marketplace.

Retrieve Makes List

Endpoint

GET /makes

Request Example

Get the list of makes that AutoScout24 supports.


curl https://api.autoscout24.com/makes \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" 

Retrieve a list of supported vehicle makes.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.

Response Example

{
  "_links": {
    "self": {
      "href": "/makes"
    },
    "makes": [
      {
        "href": "/makes/50001"
      },
      {
        "href": "/makes/51637"
      },
    ...
      {
        "href": "/makes/16394"
      }
    ]
  },
  "_request": {
    "url": "/makes",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success"
  },
  "_data": {
    "makes": [
      {
        "id": 50001,
        "name": "A.T.U",
        "vehicleType": [
          "B"
        ]
      },
      {
        "id": 51637,
        "name": "Access",
        "vehicleType": [
          "B"
        ]
      },
    ...
      {
        "id": 16394,
        "name": "ZAZ",
        "vehicleType": [
          "C"
        ]
      }
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Makes Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
makes array, Make An array that holds the make objects.

Make Object

Field Name Type Description
id Integer The unique identifier of the make object.
name String The name of the vehicle’s make.
vehicleType array, Enum An array of enumeration values to identify whether the make manufactures Cars (“C”), Bikes (“B”), or both.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Retrieve Make’s Information

Endpoint

GET /makes/{makeId}

Request Example

Retrieve the information of the BMW make that has the id = 13 :

curl https://api.autoscout24.com/makes/13 \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" 

Retrieve details of a given make.

Response shows whether a given make is of vehicleType ‘C’ (= Car) and/or vehicleType ‘B’ (= Bike).

Parameters

Parameter Name Type Mandatory Description
makeId URI Parameter Yes Unique identifier for a given make.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.

Response Example

{
  "_links": {
    "self": {
      "href": "/makes/13"
    }
  },
  "_request": {
    "url": "/makes/13",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success",
    "objectId": "13"
  },
  "_data": {
    "make": {
      "id": 13,
      "name": "BMW",
      "vehicleType": [
        "B",
        "C"
      ]
    }
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Make Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
make Make The object that holds information about the requested make.

Make Object

Field Name Type Description
id Integer The unique identifier of the make object.
name String The name of the vehicle’s make.
vehicleType array, Enum An array of enumeration values to identify whether the make manufactures Cars (“C”), Bikes (“B”), or both.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Resource - Models

The Models resource is a sub-resource of the Makes resource. It offers the needed endpoints to retrieve information about the available models of each make that are supported by the AutoScout24 marketplace.

Retrieve Makes List

Endpoint

GET /makes/{makeId}/models

Request Example

Get the list of models of BMW which has the ID = 13:


curl https://api.autoscout24.com/makes/13/models \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" 

Retrieve a list of supported vehicle models for a given vehicle make.

Parameters

Parameter Name Type Mandatory Description
makeId URI Parameter Yes Unique identifier for a given make.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.

Response Example


{
  "_links": {
    "self": {
      "href": "/makes/13/models"
    },
    "models": [
      {
        "href": "/makes/13/models/71021"
      },
      {
        "href": "/makes/13/models/50161"
      },
      ...
      {
        "href": "/makes/13/models/21073"
      }
    ]
  },
  "_request": {
    "url": "/makes/13/models",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success"
  },
  "_data": {
    "models": [
      {
        "id": 71021,
        "make": 13,
        "name": "100 CS",
        "vehicleType": "B"
      },
      {
        "id": 50161,
        "make": 13,
        "name": "C1",
        "vehicleType": "B"
      },
      ...
      {
        "id": 21073,
        "make": 13,
        "name": "Others",
        "vehicleType": "C"
      }
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Models Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
models array, Model An array that holds the model objects.

Model Object

Field Name Type Description
id Integer The unique identifier of the model object.
make Integer The unique identifier of the make.
name String The name of the vehicle’s model.
vehicleType Enum Enumeration to identify whether the model is a Car (“C”) or a Bike (“B”).

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Retrieve Model’s Information

Endpoint

GET /makes/{makeId}/models/{modelId}

Request Example

Retrieve the information of the BMW model 730 that has the ID = 1659 :

curl https://api.autoscout24.com/makes/13/models/1659 \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" 

Retrieve details of a given model.

Parameters

Parameter Name Type Mandatory Description
makeId URI Parameter Yes Unique identifier for a given make.
modelId URI Parameter Yes Unique identifier for a given model.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.

Response Example

{
  "_links": {
    "self": {
      "href": "/makes/13/models/1659"
    }
  },
  "_request": {
    "url": "/makes/13/models/1659",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success",
    "objectId": "1659"
  },
  "_data": {
    "model": {
      "id": 1659,
      "make": 13,
      "name": "730",
      "vehicleType": "C"
    }
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Model Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
models Model The object that holds information about the requested model.

Model Object

Field Name Type Description
id Integer The unique identifier of the model object.
make Integer The unique identifier of the make.
name String The name of the vehicle’s model.
vehicleType Enum Enumeration to identify whether the model is a Car (“C”) or a Bike (“B”).

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Resource - Seals

The Seals resource offers the needed endpoints to retrieve information about the available vehicle seals that are supported by the AutoScout24 marketplace.

Retrieve Seals List

Endpoint

GET /seals

Request Example

Get the list of seals that are supported by AutoScout24:


curl https://api.autoscout24.com/seals \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB"

Retrieve a list of supported car seals.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.

Response Example


{
  "_links": {
    "self": {
      "href": "/seals"
    },
    "seals": [
      {
        "href": "/seals/166"
      },
      {
        "href": "/seals/167"
      },
      ...
      {
        "href": "/seals/-1"
      }
    ]
  },
  "_request": {
    "url": "/seals",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success"
  },
  "_data": {
    "seals": [
      {
        "id": 166,
        "name": "VOLVO SELEKT",
        "country": "AT"
      },
      {
        "id": 167,
        "name": "A1 FORD GEBRAUCHTWAGEN PLUS",
        "country": "AT"
      },
      ...
      {
        "id": -1,
        "name": "NAP-Check",
        "country": "NL"
      }
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Seals Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
seals array, Seal An array that holds the seal objects.

Seal Object

Field Name Type Description
id Integer The unique identifier of the seal object.
name String The name of the seal.
country Enum The country where this seal is offered.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Retrieve Seal’s Information

Endpoint

GET /seals/{sealId}

Request Example

Retrieve the information of the Volvo Selekt seal that has the ID = 166 :

curl https://api.autoscout24.com/seals/166 \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB"

Retrieve details of a given car seal.

Parameters

Parameter Name Type Mandatory Description
sealId URI Parameter Yes Unique identifier for the requested seal.

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.

Response Example

{
  "_links": {
    "self": {
      "href": "/seals/166"
    }
  },
  "_request": {
    "url": "/seals/166",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success",
    "objectId": "166"
  },
  "_data": {
    "seal": {
      "id": 166,
      "name": "VOLVO SELEKT",
      "country": "AT"
    }
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

Seal Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
seals Seal The object that holds information about the requested seal.

Seal Object

Field Name Type Description
id Integer The unique identifier of the seal object.
name String The name of the seal.
country Enum The country where this seal is offered.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Resource - References

The References resource offers the needed endpoints to retrieve information about the enumerated fields needed to communicate with the AutoScout24 RESTful API.

Retrieve References List

Endpoint

GET /references

Request Example

Get the list of reference types and fields that are supported by AutoScout24:


curl https://api.autoscout24.com/references \
     -X GET \
     -H "X-AS24-Version: 1.1" \
     -H "Accept-Language: en-GB" 

Retrieve reference information for enumerated fields like vehicle BodyColor, DriveType, VehicleBody, available ad products or supported cultures for returning results.

Information for the following reference types can be obtained:

Headers

Header Name Data Type Mandatory Description
X-AS24-Version String Yes Defines the API version used to serve the request. Current version number is 1.1
Accept-Language String No Language used for returning results, e.g. en-GB.

Response Example


{
  "_links": {
    "self": {
      "href": "/references"
    }
  },
  "_request": {
    "url": "/references",
    "body": null,
    "method": "GET"
  },
  "_response": {
    "type": "Success"
  },
  "_data": {
    "references": [
      {
        "id": "1",
        "name": "Immediately",
        "vehicleType": null,
        "referenceType": "Availability",
        "country": null
      },
      {
        "id": "2",
        "name": "Available from",
        "vehicleType": null,
        "referenceType": "Availability",
        "country": null
      },
    ...
    ,
      {
        "id": "1",
        "name": "HU/AU neu",
        "vehicleType": [
          "B",
          "C"
        ],
        "referenceType": "IncludedService",
        "country": [
          "DE"
        ]
      },
      {
        "id": "2",
        "name": "APK tot",
        "vehicleType": [
          "B",
          "C"
        ],
        "referenceType": "IncludedService",
        "country": [
          "NL"
        ]
      },
    ...
      {
        "Id": "B",
        "ReferenceType": "VehicleType",
        "Name": "Bike",
        "CountryId": null,
        "VehicleType": null
      },
      {
        "Id": "C",
        "ReferenceType": "VehicleType",
        "Name": "Car",
        "CountryId": null,
        "VehicleType": null
      }
    ]
  }
}

Response Payload Parameters

The HTTP response message that’s received has the following body attributes:

Field Name Type Description
_links Object The links object that has all the hypermedia links of the requested resource.
_request Request An object that contains information about the sent HTTP request message. This object is mostly needed for debugging, logging, and monitoring purposes.
_response Response An object that contains information about what happened on the server e.g. it gives information if the request was processed successfully.
_data Data The data object which contains the actual information that was asked for in the sent HTTP request. Below you can find the attributes that this object has.

References Data Object

The following table shows the fields that are contained in the _data object of the Response Payload:

Field Name Type Description
references array,Reference An array that holds the reference objects.

Reference Object

Field Name Type Description
id Integer The unique identifier of the reference object.
ReferenceType Enum Enumeration value of what Reference Type this object is. Values of the enumeration are: (Availability, BodyColor, Country, Culture, DriveType, EfficiencyClass, EmissionsSticker, Equipment, FuelCategory, FuelType, IncludedService, InteriorColor, PollutionClass, PriceType, Product, PublicationChannel, Transmission, Upholstery, VehicleBody, VehicleOfferType, VehicleType)
name String The name of the reference object.
vehicleType array, Enum An array of enumeration values to identify whether the value is for Cars (“C”), Bikes (“B”), or both. If the value is null, it means that vehicleType is not applicable to the Reference Type.
country array, Enum An array of the countries to which this reference instance can exist. A null value indicates that the country is not applicable for the refernce type.

Error Codes

For the list of possible error codes in the _response object of the Response payload, please click here.

Errors

Responses

Responses as well as messages are classified by their type:

Type MessageType Description Response Code Range
Success None A request has been processed exactly as requested None
Success Info A request has been processed exactly as requested, however the response contains information for the client 10000 - 19999
Success Warning A request has been processed, but not excatly as requested (e.g. some inconsistencies were found and removed) 20000 - 49999
Error Error A request was not processed 50000 - 99999

Error Codes

Code Text
10000 Vehicle with id {0} was succesfully deleted.
10001 Image with id {0} was succesfully deleted.
10003 Product with id {0} was succesfully deleted.
10004 Video with id {videoId} was successfully deleted.
10005 Financing offer with id {financingId} successfully deleted.
10006 Publishing channel {publishingId} successfully deleted.
10500 Vehicle URI on PublicationChannel {channelId} is: { URI }. Please note that it might take a couple of minutes before the URI becomes available.
20001 Field particleFilter does not correspond with selected field fuelCategory. A particle filter is only available for diesel vehicles.
20500 ‘Accept-Language’ is empty or not supported. Default Culture 'en-GB’ is used.
50000 An error occurred while processing your request. Please try again later.
50001 Mandatory object {field} is missing. Please provide missing object.
50002 Field countryVersion has an unknown value. Please provide correct value from /references.
50003 Field deliveryDate doesn’t match expected date format (YYYY-MM-DD). Please provide expected date format.
50004 Field {field} is mandatory. Please provide missing field.
50005 Field seals has an unknown value. Please provide correct value from /seals.
50006 Field {field} doesn’t match expected date format (YYYY-MM). Please provide expected date format.
50007 Object price is missing. Please provide missing object.
50008 Field currency is missing. Please provide missing field.
50009 Field price must be greater than zero.
50010 Field vehicleType is missing. Please provide missing field.
50012 Field negotiable is missing. Please provide missing field.
50013 Field taxDeductible is missing. Please provide missing field.
50014 Field availabilityType must have a value from the following list: {allowedValues}.
50015 Please don’t provide neither deliverydate nor deliverdays for availabilityType 1 ( = Immediately).
50016 Field deliveryDays must have a value from the following list: {allowedvalues}.
50017 Field currency has an invalid value. Please use EUR.
50018 Field priceTypes must have a value from the following list: {allowedValues}.
50019 Field hsn has an invalid value. Please use numeric values only.
50022 Wrong image format: ’{filename}’. Please upload JPG or PNG images only.
50023 Please provide deliveryDate for availabilityType 2.
50024 Please provide deliveryDays for availabilityType 3.
50025 Please just provide deliveryDate for availabilityType 2.
50026 Please just provide deliveryDays for availabilityType 3.
50027 Field {field} doesn’t match expected format (between 0 and 99.9). Please provide expected format.
50028 Invalid json - {json}. Please provide a valid json.
50029 Field vehicleType has an invalid value. Please use C or B.
50030 Field model does not correspond to field make.
50031 Field firstRegistration is mandatory. Please provide missing field.
50032 Field firstRegistration must not be older than 24 months.
50033 Field firstRegistration must not be older than 12 months.
50034 Field firstRegistration must be older than 360 months.
50035 Field tsn is missing. Please provide a complete combination of hsn/tsn or none.
50036 Field hsn is missing. Please provide a complete combination of hsn/tsn or none.
50037 Field mileage must be lower or equal to 1000.
50038 Field previousOwners is not allowed for vehicleOfferType = N.
50040 Field make has an invalid value. Please provide supported make.
50041 Field model has an invalid value. Please provide supported model.
50043 Field lastCamBeltService must be in the past.
50044 Field lastTechnicalService must be in the past.
50045 Field nextInspection must be between {from} and {to}.
50046 Field previousOwner must not have more than 1 previous owner for vehicleOfferType = S.
50047 Field previousOwner must have at least 1 previous owner for vehicleOfferType = D.
50048 Field deliveryDate must be in the future.
50049 Please provide deliveryDays for availabilityType 3.
50050 Field {fieldname} must not contain email addresses.
50051 Field {fieldname} must not contain URLs.
50052 Field {fieldname} must not contain prohibited characters < or >.
50053 Field equipment has an unknown value. Please provide correct value from /references.
50054 It’s not allowed to have two price objects with the same priceType.
50055 Please provide price object with priceType = Public.
50058 Field co2 is mandatory for vehicleOfferType N, D, S. Please provide missing field.
50059 Field electricConsumptionCombined is mandatory for primaryFuelType = Electricity and vehicleOfferType N, D, S. Please provide missing field.
50060 Field fuelConsumption combined is mandatory for vehicleOfferType 'N’, ’D’, ’S’ and primaryFuelType other than Electricity. Please provide missing field.
50061 Field efficiencyClass is mandatory for vehicleOfferType N, D, S. Please provide missing field.
50062 Field primaryFuelType is mandatory for vehicleOfferType N, D, S. Please provide missing field.
50063 Public price must be higher than dealer price.
50064 Availability delivery date cannot be provided along with delivery days.
50066 Field {field} must be in range {from}-{to}.
50067 Field {field} must not be longer than {to} characters.
50068 Field {field} must be greater than {from}.
50069 Field fullServiceHistory is missing. Please provide missing field.
50071 List of values in the field {field} has duplicates. Please remove the duplicate values.
50072 Field {field} must have exact length of {length} characters.
50073 Field {field} must have a value from the following list: {allowedValues}.
50074 The vehicle is not published on this channel and cannot be deleted.
50075 Publication channel name must have a value from the following list: AS24, AS24Dealers.
50076 A channel for this vehicle already exists. Please remove existing channel first.
50077 This account is not allowed to use this channel.
50080 Image does not exist.
50081 List of image ids should contain the same ids returned by the GET method.
50082 The body of the POST request contains no image data.
50083 Image size exceeds limit.
50084 Image number limit exceeded.
50085 Multiple image upload is not allowed. Please post one picture per request.
50086 You’re not allowed to perform actions on this image.
50087 Header contains wrong customerId value. Please provide correct customerId.
50088 You’re not allowed to book products.
50089 You’re not allowed to book products for this vehicle.
50090 Wrong booking rule for this customer - Product booking via interface is not possible as customer profile is set to automatic booking rule.
50091 Provided product is not assigned to this vehicle. Therefore, it can not be deleted.
50092 A product booking for this vehicle already exists. Please remove existing booking first.
50093 Not all header values are set. Please provide necessary header values.
50094 You’re not allowed to perform this action.
50095 Field Subtitle must not contain < , >, urls or emails.
50096 You don’t have the subscriptions to book products.
50097 Product booking has an unknown value. Please provide correct value from /references.
50099 Provided product has an unknown value. Please provide correct value from /references.
50100 A contact for this vehicle already exists. Per vehicle only one set of contact details is allowed.
50101 A contact for this vehicle does not exist.
50102 It’s not allowed to have two phone number objects with the same phoneNumberType.
50103 Request body is empty. Please provide a valid json body object.
50104 A contact for this vehicle does not exist. This vehicle cannot be published without contact.
50105 You are not allowed to publish/unpublish this vehicle on this channel.
50106 Field seals have an invalid value. Please provide supported seals.
50107 Only dealers from Germany, Italy, Netherlands and Belgium are allowed to add financing offers.
50108 A financing offer for this vehicle already exists. Only one financing offer per vehicle is allowed.
50109 Provided decimal has an invalid number of decimal places. Please specify at most {precision} digits after decimal point.
50110 Field {field} is not available for vehicle type {vehicleType}.
50200 The given uri is not a valid youtube video url.
50201 ContentType header value is missing or not suitable for provided content.
50202 Vehicle has already a video. Only one video per vehicle is allowed.
50600 Start and/or end dates have invalid dates. Both date values need to be set properly.
50601 >Requested start date is older than 365 days. KPI data is available for a maximum of 365 days.
50602 Requested start date’s value is invalid. Start date must be before end date.
50603 Invalid start and/or end dates. Dates must be set to values before today’s date.
50607 Please also send alloy wheels as an equipment when specifying an alloyWheelSize.
99901 This is an invalid operation. Please check again.
99902 Invalid request - Missing access token.
99903 Invalid request - Duplicate access token.
99904 Invalid request - Invalid access token.
99905 Invalid request - Validation error.
99906 Invalid Request. Version {versionNumber} is no longer supported.
99907 Invalid Request. Access to this endpoint is denied.
99908 Invalid Request. Invalid API version value.
99913 Invalid Request. X-AS24-Version is missing.

Change Log

This section documents all the changes on the AutoScout24 RESTful API. This includes documentation for the new features, changes to old features, and deprecated features.

Versions

Version Release Date Shutdown Date
1.1 22.02.2016 -
1.0 01.04.2015 22.08.2016

August 9th, 2018 – API version 1.1

The following changes will be effective from the 10th of September, 2018.

Format changes for ImageID

The current ImageID, even if is not explicitly documented, is an unsigned integer. Current modifications will change the value to be be a string (UUID).

Current Type Future Type
ImageID: Unsigned Integer (ex: 1321961722) ImageID: String (ex: 6fb6d93c-7189-471a-a0a2-169597a01cab)

After the activation date any request to the API should be done using the UUID, and not the Integer, for the existing image.

If ImageIds are saved locally in your system you will need to update them to the new format before doing any request on images. The following possibilities are available: - Retrieve entire list of images for a vehicle. - Retrieve entire list of images for a vehicle from image order. - Delete all images for a vehicle and upload them again.

Image Deduplication

After the change it will not be possible to upload multiple times the same image (same md5 checksum) for the same vehicle.

Action on Single Vehicle Current Response Future Behavior
Upload image 1 (md5: 74b87337454200d4d33f80c4663dc5e5) Success Response, ImageID: 12345, number of images: 1 Success Response, ImageID: 704fa1b9-631d-460f-938f-6cf13d6b790f, number of images: 1
Upload image 2 (md5: 74b87337454200d4d33f80c4663dc5e5) Success Response, ImageID: 67890, number of images: 2 Success Response, ImageID: 704fa1b9-631d-460f-938f-6cf13d6b790f, number of images: 1
Upload image 3 (md5: 9448a1bf333fadd2a57965ec38487b89) Success Response, ImageID: 65437, number of images: 3 Success Response, ImageID: 6fb6d93c-7189-471a-a0a2-169597a01cab, number of images: 2

September 27th, 2017 – API version 1.1

PUT method for update an image is no longer available.

June 2nd, 2017 – API version 1.1

PUT method for update an image will be deprecated and no longer be available after 31st July 2017.

Please make sure that your application is no longer using this functionality until the end of July 2017!

April 18th, 2017 - API version 1.1

New features

- AlloyWheelSize

Introduction of AlloyWheelSize as a new attribute for car listings.

February 20th, 2017 - API version 1.1

New features

- CustomerDetails

Data providers can now retrieve customer details including the customer identification number (Sell-ID) for a valid access token.

April 12th, 2016 - API version 1.1

New Features

- Equipment Update:

API ID Equipment Name (German) Equipment Name (English)
133 Abstandstempomat Adaptive Cruise Control
134 Armlehne Armrest
135 Beheizbare Frontscheibe Electrically heated windshield
136 Beheizbares Lenkrad Heated steering wheel
137 Berganfahr-Assistent Hill holder
138 DAB-Radio Digital radio
139 Elektrische Heckklappe Electric tailgate
140 LED Scheinwerfer LED Headlights
141 LED Tagfahrlicht LED Daytime Running Lights
142 Lederlenkrad Leather steering wheel
143 Luftfederung Air suspension
145 Massagesitze Massage seats
146 Müdigkeits-Warnsystem Driver drowsiness detection
147 Nachtsicht-Assistent Night view assist
148 Notbrems-Assistent Emergency brake assistant
149 Notrufsystem Emergency system
150 Reifendruck-Kontrollsystem Tire pressure monitoring system
151 Schaltwippen Shift paddles
152 Schiebetür Sliding door
153 Schlüssellose Zentralverriegelung Keyless central door lock
154 Sitzbelüftung Seat ventilation
155 Soundsystem Sound system
156 Sprachsteuerung Voice Control
157 Spurhalte-Assistent Lane departure warning system
158 Totwinkel-Assistent Blind spot monitor
159 Touchscreen Touch screen
160 TV Television
161 USB USB
162 Verkehrszeichenerkennung Traffic sign recognition

- Interior Colors Update:

New Interior colors have been added that could give the vehicles a better description:

API ID Interior Color Name (German) Interior Color Name (English)
6 Blau Blue
7 Rot Red
8 Grün Green
9 Gelb Yellow
10 Orange Orange
11 Weiß White

April 6th, 2016 - API version 1.1

New Features

- Statistics:

Dealers can now retrieve the statistics of their entire stock as well as their individual vehicles.

- Bikes:

Dealers can now insert not only cars, but they can also insert bikes via the /vehicles endpoint.

- Financing Offers:

A new Financing Offers sub-resource /vehicles/{vehicleId}/financingoffers was added to the Vehicles resource. This would enable dealers to offer their customers the opportunity to get a financing offer when buying the vehicle. A dealer can now create, update, retrieve, and delete one financing offer for each vehicle.

- Detail Page URI:

The link to the detail page is now returned when published a vehicle on a specific channel. In addition, the Channel’s respective detail page URI is returned when requesting information about the publication channels. For more information, please check the /publications resource.

- Version Header:

A new HTTP header X-AS24-Version was introduced to explicitly define which version the consumer application is trying to communicate with. This header is mandatory for all the requests to the API.

Changes On v1.0

- New Response Structure:

A new data structure is introduced that unifies what the API responses look like. This new data structure would enable the consumers of the API to handle all the responses of the API in the same way. In addition, Hypermedia is used to represent the relationship to other resources. The new data structure will replace the old data structure that was used in v1.0.

- New data types for the Reference Object’s fields:

vehicleType and country fields of the Reference object have been changed in version 1.1 to be of type array.

- New data type for the Make Object’s fields:

vehicleType field of the Make object has been changed in version 1.1 to be of type array.