Devices API 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:

• 🔏 Restricted by Privilege Token

• 🔐 Restricted by Access Token

Base URLs

Dev

https://devices-api.dev.dimo.zone

Production

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

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

Request Body

Name	Type	Description
countryCode*	String	3-letter ISO 3166-1 alpha-3 country code.
deviceDefinitionId*	String	Vehicle Device Definition ID.

201: Created

400: Bad Request

424: Failed Dependency

500: Internal Server Error

Create a Vehicle via Smartcar Redirect

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

Creates a vehicle in the system via Smartcar integration.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

Request Body

Name	Type	Description
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.

201: Created

400: Bad Request

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

409: Conflict

429: Too Many Requests

500: Internal Server Error

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

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

Request Body

Name	Type	Description
canProtocol	String	CAN bus protocol.
countryCode*	String	3-letter ISO 3166-1 alpha-3 country code.
vin*	String	Vehicle Identification Number (VIN).

201: Created

400: Bad Request

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

424: Failed Dependency

500: Internal Server Error

---

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

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

200: Success

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

---

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

Name	Type	Description
serial*	String	Serial number of the aftermarket device.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

200: Success

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

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

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

Name	Type	Description
serial*	String	Serial number of the aftermarket device.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

Request Body

Name	Type	Description
claimRequest*	Object	{ "aftermarketDeviceSignature": "string", "userSignature": "string" }

204: No Content

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

---

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

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

200: Success

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

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

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

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

Request Body

Name	Type	Description
mintRequest*	Object	{ "imageData": "string", "imageDataTransparent": "string", "signature": "string" }

200: Success

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

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

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

204: No Content

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

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

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

204: No Content

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

429: Too Many Requests

500: Internal Server Error

---

Pairing a Vehicle with Aftermarket Device 🔐

[Deprecating] Get the Pairing Payload by User Device ID

GET {baseUrl}/v1/user/devices/{userDeviceId}/aftermarket/commands/pair

Retrieves the EIP-712 payload for user device <> vehicle pairing.

Path Parameters

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

200: Success

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

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

Sign the Pairing Payload by User Device ID to Pair Device

POST {baseUrl}/v1/user/devices/{userDeviceId}/aftermarket/commands/pair

Pairs the aftermarket device identified by User Device ID, signs the pairing payload with a device signature and a user signature while sending to the blockchain.

Path Parameters

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

Request Body

Name	Type	Description
userSignature*	Object	{ "aftermarketDeviceSignature": [ 0 ], "externalId": "string", "signature": [ 0 ] }

204: No Content

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

---

Unpairing a Vehicle with Aftermarket Device 🔐

[Deprecating] Get the Unpairing Payload by User Device ID

GET {baseUrl}/v1/user/devices/{userDeviceId}/aftermarket/commands/unpair

Retrieves the EIP-712 payload for user device <> vehicle pairing.

Path Parameters

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

200: Success

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

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

Sign the Unpairing Payload by User Device ID to Unpair Device

POST {baseUrl}/v1/user/devices/{userDeviceId}/aftermarket/commands/pair

Unpairs the aftermarket device identified by User Device ID, signs the unpairing payload with a device signature and a user signature while sending to the blockchain.

Path Parameters

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

Request Body

Name	Type	Description
userSignature*	Object	{ "aftermarketDeviceSignature": [ 0 ], "externalId": "string", "signature": [ 0 ] }

204: No Content

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

---

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

Name	Type	Description
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

Name	Type	Description
Authorization*	String	Bearer authentication using the token generated from the Token Exchange.

200: Success

{
    "requestId": "2bh8fNMoix9qduuiE9NHUzTGpZx"
}

409: Conflict

{
    "code": 409,
    "message": "Integration is not capable of this command with this device."
}

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

Name	Type	Description
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

Name	Type	Description
Authorization*	String	Bearer authentication using the token generated from the Token Exchange.

200: Success

{
    "requestId": "2bh8fNMoix9qduuiE9NHUzTGpZx"
}

409: Conflict

{
    "code": 409,
    "message": "Integration is not capable of this command with this device."
}

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

Name	Type	Description
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

Name	Type	Description
Authorization*	String	Bearer authentication using the token generated from the Token Exchange.

200: Success

{
    "requestId": "2bh8fNMoix9qduuiE9NHUzTGpZx"
}

409: Conflict

{
    "code": 409,
    "message": "Integration is not capable of this command with this device."
}

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

Name	Type	Description
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

Name	Type	Description
Authorization*	String	Bearer authentication using the token generated from the Token Exchange.

200: Success

{
    "requestId": "2bh8fNMoix9qduuiE9NHUzTGpZx"
}

409: Conflict

{
    "code": 409,
    "message": "Integration is not capable of this command with this device."
}

---

Vehicle Error Codes 🔐

Developer Notes

1. The following endpoints defers back to using the Authentication 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

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

200: Success

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

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

404: Not Found

500: Internal Server Error

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

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

Request Body

Name	Type	Description
queryDeviceErrorCodes*	Object	{ "errorCodes": [ "P0106", "P0279" ] }

200: Success

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

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

404: Not Found

500: Internal Server Error

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

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

200: Success

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

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

404: Not Found

429: Too Many Requests

500: Internal Server Error

---

On-chain Queries 🔏

Developer Notes

The following endpoints are publicly available providing on-chain metadata.

Get Synthetic Device Metadata by Token ID

GET {baseUrl}/v1/synthetic/device/{tokenId}

Retrieves the synthetic device metadata for the given token ID.

Path Parameters

Name	Type	Description
tokenId*	String	Device token ID, this is the token ID of your device NFT. This is publicly available to query in the Identity API.

200: Success

500: Internal Server Error

Get Aftermarket Device Metadata by Token ID

GET {baseUrl}/v1/aftermarket/device/{tokenId}

Retrieves the aftermarket device metadata for the given token ID. This returns the same data as Get Aftermarket Device Metadata by Ethereum Address.

Path Parameters

Name	Type	Description
tokenId*	String	Device token ID, this is the token ID of your device NFT. This is publicly available to query in the Identity API.

200: Success

500: Internal Server Error

Get Aftermarket Device Image by Token ID

GET {baseUrl}/v1/aftermarket/device/{tokenId}/image

Retrieves the aftermarket device image for the given token ID.

Path Parameters

Name	Type	Description
tokenId*	String	Device token ID, this is the token ID of your device NFT. This is publicly available to query in the Identity API.

200: Success

500: Internal Server Error

Get Aftermarket Device Metadata by Ethereum Address

GET {baseUrl}/v1/aftermarket/device/by-address/{address}

Retrieves the aftermarket device metadata for the given 0x Ethereum address. This returns the same data as in Get Aftermarket Device Metadata by Token ID

Path Parameters

Name	Type	Description
address*	String	Ethereum address.

200: Success

500: Internal Server Error

---

DCN Operations

Get DCN Metadata by Node ID

GET {baseUrl}/v1/dcn/{nodeId}

Retrieves DCN Metadata identified by the node ID.

Path Parameters

Name	Type	Description
nodeId*	String

Get DCN Image by Node ID

GET {baseUrl}/v1/dcn/{nodeId}/image

Retrieves DCN image identified by the node ID.

Path Parameters

Name	Type	Description
nodeId*	String

---

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

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

200: Success

{
    "geofences": []
}

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

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

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

Request Body

Name	Type	Description
geofence*	Object	{ "h3Indexes": [ "string" ], "name": "string", "type": "string", "userDeviceIds": [ "string" ] }

201: Created

{
    "id": "2bjtLvUGPjtoffSFHR2CjshPb3t"
}

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

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

Name	Type	Description
geofenceId*	String	Geofence ID.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

Request Body

Name	Type	Description
geofence*	Object	A geofence body example: { "h3Indexes": [ "string" ], "name": "string", "type": "string", "userDeviceIds": [ "string" ] }

204: No Content

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

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

Name	Type	Description
geofenceId*	String	Geofence ID.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

204: No Content

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

---

Swagger Doc

Swagger UI