BMW CarData Customer API

The BMW CarData Customer API lets an authenticated BMW customer (or a delegate acting on their behalf via the customer portal) read vehicle metadata and telematics for the VINs mapped to their BMW ID account. Endpoints cover vehicle mappings, basic data, telematic data, charging history, smart-maintenance tyre diagnosis, location-based charging settings, vehicle images, and CRUD over CarData "containers" that define which descriptors a client subscribes to. Authentication uses the GCDM (Global Customer Data Management) bearer token obtained via the OAuth 2.0 Device Code Flow against the `cardata:api:read` scope. The base URL is `https://api-cardata.bmwgroup.com` with header `x-version: v1`. ID tokens are valid for one hour and must be refreshed via the standard OAuth refresh-token grant.

BMW CarData Customer API is one of 3 APIs that BMW ConnectedDrive publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

Tagged areas include CarData, Vehicles, Telematics, Containers, and Charging. The published artifact set on APIs.io includes API documentation and an OpenAPI specification.

OpenAPI Specification

bmw-cardata-customer-api-openapi.json Raw ↑
{
  "openapi": "3.1.0",
  "info": {
    "title": "CARDATA API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api-cardata.bmwgroup.com",
      "description": "Generated server url"
    }
  ],
  "tags": [
    {
      "name": "Containers",
      "description": "Management of containers"
    },
    {
      "name": "Vehicles",
      "description": "Access vehicle data and information"
    }
  ],
  "paths": {
    "/customers/containers": {
      "get": {
        "tags": [
          "Containers"
        ],
        "summary": "List the containers",
        "operationId": "listContainers",
        "parameters": [
          {
            "in": "header",
            "name": "x-version",
            "required": true,
            "schema": {
              "type": "string",
              "default": "v1"
            }
          }
        ],
        "responses": {
          "400": {
            "description": "Bad request. Please check API specification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Access to resource is forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "A permanent server error occurred. Report this error if it occurs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "A temporary server error occurred. Retry again later or report this error if it persists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "200": {
            "description": "List of available containers is returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContainerListDto"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ContainerListDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Containers"
        ],
        "summary": "Create a container",
        "operationId": "createContainer",
        "description": "Please note that some keys are bound to dedicated endpoints. These keys can be added to a container, but the corresponding endpoint for which the container is an input-parameter (/telematicData/), won't return these keys. For further details, check the Integration Guide (chapter 3.3.2).",
        "parameters": [
          {
            "in": "header",
            "name": "x-version",
            "required": true,
            "schema": {
              "type": "string",
              "default": "v1"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateContainerRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "400": {
            "description": "Bad request. Please check API specification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Access to resource is forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "A permanent server error occurred. Report this error if it occurs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "A temporary server error occurred. Retry again later or report this error if it persists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "201": {
            "description": "Successful operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContainerDetailsDto"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ContainerDetailsDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/customers/vehicles/{vin}/telematicData": {
      "get": {
        "tags": [
          "Vehicles"
        ],
        "summary": "Request Vehicle's telematic data for a container, for the specified vehicle.",
        "operationId": "getTelematicData",
        "description": "Please note that some keys are bound to dedicated endpoints. These keys can be added to a container, but the corresponding endpoint for which the container is an input-parameter (/telematicData/), won't return these keys. For further details, check the Integration Guide (chapter 3.3.2).",
        "parameters": [
          {
            "in": "header",
            "name": "x-version",
            "required": true,
            "schema": {
              "type": "string",
              "default": "v1"
            }
          },
          {
            "name": "vin",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "containerId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "400": {
            "description": "Bad request. Please check API specification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Access to resource is forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "A permanent server error occurred. Report this error if it occurs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "A temporary server error occurred. Retry again later or report this error if it persists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "200": {
            "description": "A specific list of telematic key and values was returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExVeTelematicDataResponseDto"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ExVeTelematicDataResponseDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/customers/vehicles/{vin}/smartMaintenanceTyreDiagnosis": {
      "get": {
        "tags": [
          "Vehicles"
        ],
        "summary": "Request a vehicle Smart Maintenance Tyre Diagnosis for the specified vehicle.",
        "operationId": "getSmartMaintenanceTyreDiagnosis",
        "parameters": [
          {
            "in": "header",
            "name": "x-version",
            "required": true,
            "schema": {
              "type": "string",
              "default": "v1"
            }
          },
          {
            "name": "vin",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "400": {
            "description": "Bad request. Please check API specification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Access to resource is forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "A permanent server error occurred. Report this error if it occurs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "A temporary server error occurred. Retry again later or report this error if it persists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "200": {
            "description": "Specific vehicle Smart Maintenance Tyre Diagnosis Data is provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SmartMaintenanceTyreDiagnosisDto"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/SmartMaintenanceTyreDiagnosisDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/customers/vehicles/{vin}/locationBasedChargingSettings": {
      "get": {
        "tags": [
          "Vehicles"
        ],
        "summary": "Request Vehicle's location based charging settings",
        "operationId": "getLocationBasedChargingSettings",
        "parameters": [
          {
            "in": "header",
            "name": "x-version",
            "required": true,
            "schema": {
              "type": "string",
              "default": "v1"
            }
          },
          {
            "name": "vin",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "nextToken",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "400": {
            "description": "Bad request. Please check API specification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Access to resource is forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "A permanent server error occurred. Report this error if it occurs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "A temporary server error occurred. Retry again later or report this error if it persists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "200": {
            "description": "List of location based charging settings returned for the VIN.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocationBasedChargingSettingsDto"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/LocationBasedChargingSettingsDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/customers/vehicles/{vin}/image": {
      "get": {
        "tags": [
          "Vehicles"
        ],
        "summary": "Request a vehicle image for the specified vehicle.",
        "operationId": "getImage",
        "produces": [
          "image/png,image/jpeg,application/json"
        ],
        "parameters": [
          {
            "in": "header",
            "name": "x-version",
            "required": true,
            "schema": {
              "type": "string",
              "default": "v1"
            }
          },
          {
            "name": "vin",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "400": {
            "description": "Bad request. Please check API specification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Access to resource is forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "A permanent server error occurred. Report this error if it occurs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "A temporary server error occurred. Retry again later or report this error if it persists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "200": {
            "description": "A specific vehicle image is provided",
            "content": {
              "*/*": {
                "schema": {
                  "type": "file"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/customers/vehicles/{vin}/chargingHistory": {
      "get": {
        "tags": [
          "Vehicles"
        ],
        "summary": "Request the vehicle's Charging History sessions.",
        "operationId": "getChargingHistory",
        "parameters": [
          {
            "in": "header",
            "name": "x-version",
            "required": true,
            "schema": {
              "type": "string",
              "default": "v1"
            }
          },
          {
            "name": "vin",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "nextToken",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "400": {
            "description": "Bad request. Please check API specification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Access to resource is forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "A permanent server error occurred. Report this error if it occurs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "A temporary server error occurred. Retry again later or report this error if it persists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "200": {
            "description": "Whatever Charging History respond will be passed on.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChargingHistoryResponseDto"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ChargingHistoryResponseDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/customers/vehicles/{vin}/basicData": {
      "get": {
        "tags": [
          "Vehicles"
        ],
        "summary": "Request basic vehicle data for the specified vehicle.",
        "operationId": "getBasicData",
        "parameters": [
          {
            "in": "header",
            "name": "x-version",
            "required": true,
            "schema": {
              "type": "string",
              "default": "v1"
            }
          },
          {
            "name": "vin",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "400": {
            "description": "Bad request. Please check API specification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Access to resource is forbidden",


# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bmw-connecteddrive/refs/heads/main/openapi/bmw-cardata-customer-api-openapi.json