APIs/Connected Vehicle API
APIs/Connected Vehicle API

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.

FieldDescription
Field
status
Description
The HTTP status codes.
Field
operationId
Description
The id of the specific operation which can be used for fault tracing.
Field
data
Description
The data contains the dataset which the specific endpoint serves.

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.

FieldDescription
Field
limit
Description
The current limit used.
Field
next
Description
The query string that should be used to fetch the next set of results.
Field
offset
Description
The current offset used.
Field
previous
Description
The query string to fetch the previous set of results.
Field
total
Description
The total number of results that are available.

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.

Status codeDescription
Status code
200 OK
Description
Indicates a successful request.
Status code
202 Accepted
Description
Indicates a successful request, but the processing has not been completed.
Status code
204 No Content
Description
Indicates a successful request, the response will not contain a body.
Status code
400 Bad Request
Description
Error code which indicates that the update did not pass the validation rules defined in the Open API spec or an invalid json payload was sent.
Status code
401 Unauthorized
Description
Error code which usually indicates and error with either the VCC-API-key or Bearer token, check the error message for details.
Status code
403 Resource Forbidden
Description
Error code which usually indicates that there are scopes missing in the Bearer token, check the error message for details.
Status code
406 Not Acceptable
Description
Error code which indicates that an invalid mediatype was sent in the Accept header.
Status code
415 Unsupported Media Type
Description
Error code which indicates that an invalid mediatype was sent in the Content-Type header, only applicable on endpoints where a request body is sent (e.g POST/PUT endpoints).
Status code
422 Unprocessable Entity
Description
Error code which indicates that the update passes the validation rules defined in the Open API spec but fails against the internal business rules.
Status code
500 Internal Server Error
Description
Error Code which indicate that something went wrong when processing the request, check the error message for details.
Status code
502 Bad Gateway
Description
Error Code which indicate that something went wrong when calling the API.

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.

FieldDescription
Field
status
Description
The HTTP status codes.
Field
operationId
Description
The id of the specific operation which can be used for fault tracing.
Field
error.message
Description
A message explaining the error.
Field
error.description
Description
A more in detail description of the error.
Field
error.detail
Description
An object describing in detail what exactly went wrong, the format of the details object can differ between the endpoint and error codes.

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:

StatusDescription
Status
VEHICLE_REQUEST_TIMEOUT
Description
The service invocation request failed due to a timeout sending the request to the vehicle, e.g. the vehicle has poor connectivity.
Status
VEHICLE_RESPONSE_TIMEOUT
Description
The service invocation request failed due a timeout when waiting for a response from the vehicle.
Status
VEHICLE_RESPONSE_ERROR
Description
The service invocation request failed due to a vehicle error.
Status
VEHICLE_IN_SLEEP_MODE
Description
The service invocation request failed due to the vehicle being in sleep mode.
Status
UNLOCK_TIME_FRAME_PASSED
Description
The vehicle was not unlocked within the given time frame. The user did not press trunk handle within time limit to unlock the car.
Status
UNABLE_TO_LOCK_DOOR_OPEN
Description
Service invocation request failed to complete due to an open door.
Status
PRIVACY_POLICY_ENABLED
Description
The vehicle in question has privacy policy enabled.

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"
  }
}

Details/Application