Devices Endpoints

DIMO Check-in

This is a legacy API endpoint that consists of different operations. Be mindful of the different authorization headers for each API call, as we've noted them with some visual cues:

Base URLs

https://devices-api.dimo.zone


Vehicle Creation 🔐

Developer Notes

This is a pre-requisite to interacting with vehicles. If you already have vehicles created/minted via the DIMO Mobile App (iOS/Android), you can skip to the later steps.

Create a Vehicle

POST {baseUrl}/v1/user/devices

Creates a vehicle in the system with a specific device definition. Optionally, a device definition will be created if only supplied with Make, Model, and Year.

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.

Request Body

NameTypeDescription

countryCode*

String

3-letter ISO 3166-1 alpha-3 country code.

deviceDefinitionId*

String

Vehicle Device Definition ID.

Create a Vehicle via Smartcar Redirect

POST {baseUrl}/v1/user/devices/fromsmartcar

Creates a vehicle in the system via Smartcar integration.

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.

Request Body

NameTypeDescription

code*

String

The auth code received Smartcar's handle response step.

countryCode*

String

3-letter ISO 3166-1 alpha-3 country code.

redirectURI*

String

The redirect URI provided in Smartcar's redirect to Connect step.

Create a Vehicle via VIN Decoding

POST {baseUrl}/v1/user/devices/fromvin

Creates a vehicle in the system by decoding a Vehicle Identification Number (VIN).

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.

Request Body

NameTypeDescription

canProtocol

String

CAN bus protocol.

countryCode*

String

3-letter ISO 3166-1 alpha-3 country code.

vin*

String

Vehicle Identification Number (VIN).


Updating Vehicle VIN 🔐

Update Vehicle VIN

PATCH {baseUrl}/v1/user/devices/{userDeviceId}/vin

Updates the Vehicle Identification Number (VIN) by User Device ID.

Path Parameters

NameTypeDescription

userDeviceId*

String

For userDeviceId, please refer to the User Device entity under Devices API

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.


Claiming an Aftermarket Device 🔐

Get the Claiming Payload by Device Serial Number

GET {baseUrl}/v1/aftermarket/device/by-serial/{serial}/commands/claim

Retrieves the EIP-712 payload for Aftermarket device claiming.

Path Parameters

NameTypeDescription

serial*

String

Serial number of the aftermarket device.

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.

{
  "domain": {
    "chainId": {},
    "name": "string",
    "salt": "string",
    "verifyingContract": "string",
    "version": "string"
  },
  "message": {
    "additionalProp1": {}
  },
  "primaryType": "string",
  "types": {
    "additionalProp1": [
      {
        "name": "string",
        "type": "string"
      }
    ],
    "additionalProp2": [
      {
        "name": "string",
        "type": "string"
      }
    ],
    "additionalProp3": [
      {
        "name": "string",
        "type": "string"
      }
    ]
  }
}

Sign the Claiming Payload by Device Serial Number to Claim Device

POST {baseUrl}/v1/aftermarket/device/by-serial/{serial}/commands/claim

Claims the aftermarket device identified by serial number, signs the claiming payload with a device signature and a user signature while sending to the blockchain.

Path Parameters

NameTypeDescription

serial*

String

Serial number of the aftermarket device.

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.

Request Body

NameTypeDescription

claimRequest*

Object

{
    "aftermarketDeviceSignature": "string",
    "userSignature": "string"
}


Minting a Vehicle 🔐

[Deprecating] Get the Minting Payload by User Device ID

GET {baseUrl}/v1/user/devices/{userDeviceId}/commands/mint

Retrieves the payload for user device minting.

Path Parameters

NameTypeDescription

userDeviceId*

String

For userDeviceId, please refer to the User Device entity under Devices API

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.

{
  "domain": {
    "chainId": {},
    "name": "string",
    "salt": "string",
    "verifyingContract": "string",
    "version": "string"
  },
  "message": {
    "additionalProp1": {}
  },
  "primaryType": "string",
  "types": {
    "additionalProp1": [
      {
        "name": "string",
        "type": "string"
      }
    ],
    "additionalProp2": [
      {
        "name": "string",
        "type": "string"
      }
    ],
    "additionalProp3": [
      {
        "name": "string",
        "type": "string"
      }
    ]
  }
}

Sign the Minting Payload by User Device ID to Mint Vehicle

POST {baseUrl}/v1/user/devices/{userDeviceId}/commands/mint

Mints the vehicle identified by user device ID, signs the minting payload with a signature while sending to the blockchain.

Path Parameters

NameTypeDescription

userDeviceId*

String

For userDeviceId, please refer to the User Device entity under Devices API

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.

Request Body

NameTypeDescription

mintRequest*

Object

{
    "imageData": "string",
    "imageDataTransparent": "string",
    "signature": "string"
}

Opt the Device to Share Data by User Device ID

POST {baseUrl}/v1/user/devices/{userDeviceId}/commands/opt-in

Opts the device into data-sharing to qualify for $DIMO rewards.

Path Parameters

NameTypeDescription

userDeviceId*

String

For userDeviceId, please refer to the User Device entity under Devices API

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.

Initiate Refresh Process of a Vehicle Connected with Smartcar by User Device ID

POST {baseUrl}/v1/user/devices/{userDeviceId}/commands/refresh

Starts the process of refreshing device status from Smartcar. Note that this endpoint is rate-limited separately as it involves with our API agreement with Smartcar.

Path Parameters

NameTypeDescription

userDeviceId*

String

For userDeviceId, please refer to the User Device entity under Devices API

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.


Vehicle Commands 🔏

Developer Notes

To access the vehicle commands, a token exchange transaction is required to obtain a 2nd JWT to get permission to access the vehicle's commands. Please check Token Exchange API prior to using this endpoint.

Send a Vehicle Command to Lock the Doors

POST {baseUrl}/v1/vehicle/{tokenId}/commands/doors/lock

Sends a vehicle command to lock the doors.

Path Parameters

NameTypeDescription

tokenId*

String

Vehicle token ID, this is the token ID of your vehicle NFT. A prerequisite is to obtain a token that is permitted to access trips data for this specific vehicle.

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the token generated from the Token Exchange.

{
    "requestId": "2bh8fNMoix9qduuiE9NHUzTGpZx"
}

Send a Vehicle Command to Unlock the Doors

POST {baseUrl}/v1/vehicle/{tokenId}/commands/doors/unlock

Sends a vehicle command to unlock the doors.

Path Parameters

NameTypeDescription

tokenId*

String

Vehicle token ID, this is the token ID of your vehicle NFT. A prerequisite is to obtain a token that is permitted to access trips data for this specific vehicle.

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the token generated from the Token Exchange.

{
    "requestId": "2bh8fNMoix9qduuiE9NHUzTGpZx"
}

Send a Vehicle Command to Open the Frunk

POST {baseUrl}/v1/vehicle/{tokenId}/commands/frunk/open

Sends a vehicle command to open the frunk.

Path Parameters

NameTypeDescription

tokenId*

String

Vehicle token ID, this is the token ID of your vehicle NFT. A prerequisite is to obtain a token that is permitted to access trips data for this specific vehicle.

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the token generated from the Token Exchange.

{
    "requestId": "2bh8fNMoix9qduuiE9NHUzTGpZx"
}

Send a Vehicle Command to Open the Trunk

POST {baseUrl}/v1/vehicle/{tokenId}/commands/trunk/open

Sends a vehicle command to open the trunk.

Path Parameters

NameTypeDescription

tokenId*

String

Vehicle token ID, this is the token ID of your vehicle NFT. A prerequisite is to obtain a token that is permitted to access trips data for this specific vehicle.

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the token generated from the Token Exchange.

{
    "requestId": "2bh8fNMoix9qduuiE9NHUzTGpZx"
}

Vehicle Error Codes 🔐

Developer Notes

  1. The following endpoints defers back to using the Web3 access token given that API users are interacting with user devices under their personal possession. No additional permission is needed.

  2. Vehicle error codes are not actively synced with the DIMO Network, hence a submission of error codes is required to store error code history. This is also a function seen in the DIMO Mobile App: https://dimo.zone/news/how-to-scan-your-cars-error-codes-with-dimo-mobile

List All Available Error Codes by User Device ID

GET {baseUrl}/v1/user/devices/{userDeviceId}/error-codes

Retrieves a list of error code queries made for the vehicle identified by the user device ID.

Path Parameters

NameTypeDescription

userDeviceId*

String

For userDeviceId, please refer to the User Device entity under Devices API.

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.

{
  "queries": [
    {
      "clearedAt": "2023-05-23T12:57:05Z",
      "errorCodes": [
        {
          "code": "P0148",
          "description": "Fuel delivery error"
        }
      ],
      "requestedAt": "2023-05-23T12:56:36Z"
    }
  ]
}

Submit Error Codes for Description by User Device ID

POST {baseUrl}/v1/user/devices/{userDeviceId}/error-codes

Submits a list of error codes for the vehicle identified by the user device ID. This submission will actively store the error codes provided for the vehicle while returning the full descriptions for evaluation.

Use application/json for raw body parameters.

Path Parameters

NameTypeDescription

userDeviceId*

String

For userDeviceId, please refer to the User Device entity under Devices API.

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.

Request Body

NameTypeDescription

queryDeviceErrorCodes*

Object

{ "errorCodes": [ "P0106", "P0279" ] }

{
  "queries": [
    {
      "clearedAt": "2023-05-23T12:57:05Z",
      "errorCodes": [
        {
          "code": "P0148",
          "description": "Fuel delivery error"
        }
      ],
      "requestedAt": "2023-05-23T12:56:36Z"
    }
  ]
}

Submit to Clear Most Recently Submitted Error Codes by User Device ID

POST {baseUrl}/v1/user/devices/{userDeviceId}/error-codes/clear

Submits a clearing signal to DIMO, indicating that the most recently error codes submitted for the vehicle has been cleared.

Path Parameters

NameTypeDescription

userDeviceId*

String

For userDeviceId, please refer to the User Device entity under Devices API.

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.

{
  "clearedAt": "2023-05-23T12:57:05Z",
  "errorCodes": [
    {
      "code": "P0148",
      "description": "Fuel delivery error"
    }
  ],
  "requestedAt": "2023-05-23T12:56:36Z"
}

Geofence Operations 🔐

Get Geofences for the User

GET {baseUrl}/v1/user/geofences

List all geofences for user devices that belongs to the authorized user.

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.

{
    "geofences": []
}

Create a Geofence for the User

POST {baseUrl}/v1/user/geofences

Creates a geofence object bounded by h3indexes for an authorized user account, optionally attaching the geofence to specific user devices.

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.

Request Body

NameTypeDescription

geofence*

Object

{
  "h3Indexes": [
    "string"
  ],
  "name": "string",
  "type": "string",
  "userDeviceIds": [
    "string"
  ]
}
{
    "id": "2bjtLvUGPjtoffSFHR2CjshPb3t"
}

Update a Geofence for the User by Geofence ID

PUT {baseUrl}/v1/user/geofences/{geofenceId}

Updates a geofence object for an authorized user with the provided geofence ID.

Path Parameters

NameTypeDescription

geofenceId*

String

Geofence ID.

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.

Request Body

NameTypeDescription

geofence*

Object

A geofence body example:

{
  "h3Indexes": [
    "string"
  ],
  "name": "string",
  "type": "string",
  "userDeviceIds": [
    "string"
  ]
}

Delete a Geofence for the User by Geofence ID

DELETE {baseUrl}/v1/user/geofences/{geofenceId}

Deletes a geofence object for an authorized user with the provided geofence ID.

Path Parameters

NameTypeDescription

geofenceId*

String

Geofence ID.

Headers

NameTypeDescription

Authorization*

String

Bearer authentication using the access_token generated from the authentication step.


Swagger Doc

Last updated