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>'

Commands

Commands are used to send instructions to the vehicle. For example, you can send a command to lock the vehicle or flash the lights.

To determine which commands can be sent to a specific vehicle, refer to the List commands endpoint. If you send a command unsupported by a vehicle, you will receive a response with the status code 404 Not found and an error message describing the issue.

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

data

Description

Data returned by the specific endpoint.

Example

{
  "data": {
    "brakeFluidLevelWarning": {
      "value": "NO_WARNING",
      "timestamp": "2023-11-14T12:16:34.324Z"
    }
  }
}

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 specification or an invalid json payload was sent.

Status code

401 Unauthorized

Description

Error code which usually indicates an 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

404 Not found

Description

Error code which indicates that the resource could not be found, the description can contain a reason for the response.

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.

Status code

503 Service Unavailable

Description

Error Code which indicate that the server cannot fulfill the request at the moment, check the error message for details.

Status code

504 Gateway Timeout

Description

Error Code which indicates that the server did not receive a timely response from an upstream server.

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

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

{
  "error": {
	  "message": "SERVICE_UNAVAILABLE",
	  "description": "Not allowed, car is in use or asleep"
    }
}

Debugging errors

If the error message from the request body doesn't provide enough information for troubleshooting, you can contact us at developer.portal@volvocars.com.

Before contacting us, please include a GUID in the vcc-api-operationId header of the problematic API request. This will help us locate your requests in our systems. If a vcc-api-operationId is not provided in a request, a GUID will automatically be generated for the request.

The vcc-api-operationId header will also always be returned in the response as a header with the same name.

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

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