Details

Application

To use this API, you must first create an application. When your application is created, you will receive a VCC API key. This key must be included in the header of each request sent to the API.

Visit your account page to create or view applications.

Example

-H 'vcc-api-key: <your-vcc-api-key>'

Authorisation

This API implements the OAuth2 framework. An access token must be included in the header of each request sent to the API.

Visit the authorisation page for more information.

Example

-H 'authorization: Bearer <your-access-token>'

Common response model

Most of the responses from the API will have a common response body regardless of which endpoint is called, for successful (except 204) responses the response body will contain a data field which contains the information exposed by the endpoint. Each endpoint contains different datasets hence the format of the data field will change.

Example

{
  "status": 0,
  "operationId": "string",
  "data": {}
}

Pagination

Endpoint where the media type includes "list" will have a pagination section in the response.

This part contains the information about the current set of results returned and where to find the next set in the sequence.

Regarding next and previous, if for example the current request has been made with the query string ?limit=100&offset=0, next will contain ?limit=100&offset=1 if there are more results available. If next is empty or not available in the response it means that you have reached the last set of results and no more are available.

Example

{
  "pagination": {
    "limit": 0,
    "next": "string",
    "offset": 0,
    "previous": "string",
    "total": 0
  }
}

Status codes

All the status codes which the API can return are described below.

Error handling

Sometimes things go wrong, in such cases the API will in addition to the error code return a message body containing information about the error. The message body has a base structure which will be the same regardless of the error. It can also contain a dynamic detail field with specific data for the particular HTTP status code and endpoint.

Example

{
  "status": 0,
  "operationId": "string",
  "error": {
    "message": "string",
    "description": "string",
    "detail": "object"
  }
}

Debugging errors

In case the request error message does not help you resolve the issue, you can report it to developer.portal@volvocars.com. You can include a GUID in the vcc-api-operationId header of each request towards the API. This will make it easier for us to find your requests in our logs in cases where deeper analysis is needed.

Example

-H 'vcc-api-operationId: <GUID>'

Vehicle sleep and error modes

When the car has not been used for more than 3-5 days, the invocation command request may not be able to perform because is set in standby mode. When starting the car the system reactivates and you can send invocation commands again.

The different error statuses that is possible to get from invocation commands are:

Example response when vehicle in sleep mode

{
  "status": 200,
  "operationId": "d1458f6a-53ae-4668-90de-321c95bd3ec6",
  "data": {
    "created": "2021-05-03T10:19:16.762Z",
    "updated": "2021-05-03T10:19:18.133Z",
    "command": "FLASH",
    "requestId": "6567aa84-0d96-485e-b140-2be516d430db",
    "invokeStatus": "VEHICLE_IN_SLEEP"
  }
}