API Reference

Based on simple REST principles, the AutoScout24 REST API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The base address of the API is https://api.autoscout24.ch. To access seller’s data, such as listings, images and equipment, an application must get access permissions. Authentication and authorization is performed via the AutoScout24 Auth Service.

Quickstart

If you already received the credentials (Client ID and Client Secret) from the AutoScout24 Team:

  1. Obtain an access token from the Auth Service:

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'client_id=<partner_client_id>' -d 'client_secret=<partner_client_secret>' -d 'grant_type=client_credentials' -d 'audience=https://api.autoscout24.ch' https://api.autoscout24.ch/public/v1/clients/oauth/token

{
  "access_token": "eyJhbG...qMEtAw",
  "token_type": "Bearer",
  "expires_in": 86400
}
  1. Use the access token to access the API:

curl -X GET -H 'Authorization: Bearer eyJhbG...qMEtAw' https://api.autoscout24.ch/public/v1/vehicle-categories

{
  "vehicleCategories": [
    "car",
    "utility"
  ]
}

After you successfully authenticate and make an API request, you’re ready to begin integrating AutoScout24.

Make sure you:

Authentication & Authorization

Authentication and authorization are performed via the authorization service, which is built on standard protocols, OpenID Connect and OAuth 2.0, enabling integrations and allowing fast growth of the AutoScout24 universe.

Most of the requests to the API require authentication. You need to obtain an access token first and include it in the request header (Authorization: Bearer < access_token>) for each API request, as long as the token remains valid.

Obtaining an Access Token

To obtain your client ID and client secret, which are required for requesting an access token, please reach out to the AutoScout24 team.

Access tokens are obtained using the client credentials flow, where a client (e.g., a backend service) authenticates itself using a client ID and client secret to request a token from the obtain token endpoint. This flow is intended for machine-to-machine communication and does not involve user authentication.

Tokens are issued with a predefined expiration time (e.g., 86400 seconds / 24 hours). Once the token expires or gets invalidated, you must request a new one by repeating the same process. Make sure to handle token expiration appropriately by either caching and reusing valid token, or re-obtaining a new token when resource server responds with unahthorized status code.

For detailed instructions on obtaining an access token, including example requests, refer to the client OAuth token endpoint documentation.

Request:

curl -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=<partner_client_id>' \
  -d 'client_secret=<partner_client_secret>' \
  -d 'grant_type=client_credentials' \
  -d 'audience=https://api.autoscout24.ch' \
  https://api.autoscout24.ch/public/v1/clients/oauth/token

Response:

{
  "access_token": "eyJhbG...qMEtAw",
  "token_type": "Bearer",
  "expires_in": 86400
}

Additional Notes

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests that require authentication will fail if an invalid or expired access token is provided.

Your API credentials carry many privileges, so be sure to keep them secure! Do not share your credentials in publicly accessible areas such as GitHub, client-side code, and so forth.

Errors

AutoScout24 uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an update failed due to business logic violation, etc.). Codes in the 5xx range indicate an error with AutoScout24’s servers (these are rare).

Some 4xx errors could be handled programmatically.

Status Code Description
200 OK - The request has succeeded. The client can read the result of the request in the body and/or the headers of the response.
201 Created - The request has been fulfilled and resulted in a new resource being created.
202 Accepted - The request has been accepted for processing, but the processing has not been completed.
204 No Content - The request has succeeded but returns no message body.
400 Bad Request - The request could not be understood, often due to missing a required parameter. The message body will contain more information.
401 Unauthorized - No valid user authentication (access token) provided.
403 Forbidden - The authenticated user doesn’t have required permissions to perform the request.
404 Not Found - The requested resource could not be found.
422 Unprocessable Entity - The request is valid, but the business rules validations failed. The message body will contain more information.
429 Too Many Requests - Rate limiting has been applied.
500, 502, 503, 504 Server Errors - Something went wrong on AutoScout24’s end. These errors are rare.

Response Schema

This error type is specific to the API. Apart from the response code, unsuccessful responses for 400 Bad Request and 422 Unprocessable Entity return a JSON object containing the following information:

Key Value Type Value Description
code string A high level description of the error.
description string A more detailed description of the error.
fieldErrors array An array of field specific errors.

An example of a failing request to create a listing:

curl -X POST -H 'Authorization: Bearer eyJhbG...qMEtAw' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{}' https://api.autoscout24.ch/public/v1/sellers/1923/listings

{
  "code": "VALIDATION_FAILED",
  "description": "Validation failed for object",
  "fieldErrors": [
    {
      "code": "REQUIRED_NOT_NULL",
      "message": "must not be null",
      "property": "price",
      "rejectedValue": null,
      "path": "price"
    }
  ]
}

Date/Time Format

All dates in the API use UTC and are strings in the ISO 8601 format:

  • date: 2023-10-18
  • date-time: 2024-05-15T15:50:38Z

Pagination

Some endpoints support a way of paging the dataset, taking a page and size as query parameters:

curl https://api.autoscout24.ch/public/v1/sellers/1234/listings?page=2&size=10

In this example, in a list of 50 (totalElements) listings of the specified dealer: skip the first two pages (first 20 listings on pages 0 and 1) and retrieve the next 10 (size) listings.

Note: The page numbering is zero-based. Check the specification for the specific endpoint and verify the default values.

Images CDN

When accessing images (e.g. listing images) via the API, such as https://images.autoscout24.ch/public/listing/890/12387890/0.jpg, you may optionally provide a limited set of query parameters for responsive image rendering.

Example: https://images.autoscout24.ch/public/listing/890/12387890/0.jpg?w=320

Allowed Query Parameters

Parameter Description Allowed Values
w Width in pixels 16, 32, 48, 64, 96, 128, 256, 320, 360, 384, 768, 1024, 1280, 1920

If unsupported values or parameters are provided, the default server settings will be applied.

Best Practices

  • Use the srcset attribute to deliver responsive images using allowed widths
  • Stick to allowed w values to benefit from CDN caching
  • Avoid using any unlisted parameters — they will be ignored

Free Text Input

All free text input fields are scanned and sanitized upon submission, before saving the data in the AutoScout24 database. Not allowed content will be stripped off automatically.

Some fields, like the Listing’s description, may be formatted by HTML tags. The list of supported tags includes <b> (bold), <br> (line break), <i> (italic), <u> (underlined), <ol>/<ul> (ordered/unordered list), <li> (list item) and few more. A line break can also be represented by a newline character \n.

Rate Limiting

Rate Limiting enables the API to share access bandwidth to its resources equally across all users and applications.

Note: If the API returns status code 429, it means that you have sent too many requests. When this happens, wait some time before you try your request again.

Versioning

AutoScout24 considers the following changes to be backwards-compatible:

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.
  • Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.
  • Adding new enum values.
  • Your client should gracefully handle unfamiliar enum values.

Swagger UI & OpenAPI Specification