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:
🔏 Restricted by Privilege Token
🔐 Restricted by Access Token
Base URLs
https://devices-api.dimo.zone
Vehicle Creation 🔐
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 |
---|---|---|
| String | Bearer authentication using the |
Request Body
Name | Type | Description |
---|---|---|
| String | 3-letter ISO 3166-1 alpha-3 country code. |
| 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
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
Request Body
Name | Type | Description |
---|---|---|
| String | The auth code received Smartcar's handle response step. |
| String | 3-letter ISO 3166-1 alpha-3 country code. |
| 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
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
Request Body
Name | Type | Description |
---|---|---|
| String | CAN bus protocol. |
| String | 3-letter ISO 3166-1 alpha-3 country code. |
| 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
Name | Type | Description |
---|---|---|
| String | For |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
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 |
---|---|---|
| String | Serial number of the aftermarket device. |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
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 |
---|---|---|
| String | Serial number of the aftermarket device. |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
Request Body
Name | Type | Description |
---|---|---|
| Object |
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 |
---|---|---|
| String | For |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
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 |
---|---|---|
| String | For |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
Request Body
Name | Type | Description |
---|---|---|
| Object |
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 |
---|---|---|
| String | For |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
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 |
---|---|---|
| String | For |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
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 |
---|---|---|
| String | Vehicle token ID, this is the token ID of your vehicle NFT. A prerequisite is to obtain a |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
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 |
---|---|---|
| String | Vehicle token ID, this is the token ID of your vehicle NFT. A prerequisite is to obtain a |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
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 |
---|---|---|
| String | Vehicle token ID, this is the token ID of your vehicle NFT. A prerequisite is to obtain a |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
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 |
---|---|---|
| String | Vehicle token ID, this is the token ID of your vehicle NFT. A prerequisite is to obtain a |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
Vehicle Error Codes 🔐
Developer Notes
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.
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 |
---|---|---|
| String | For |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
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 |
---|---|---|
| String | For |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
Request Body
Name | Type | Description |
---|---|---|
| Object |
|
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 |
---|---|---|
| String | For |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
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 |
---|---|---|
| String | Bearer authentication using the |
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 |
---|---|---|
| String | Bearer authentication using the |
Request Body
Name | Type | Description |
---|---|---|
| Object |
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 |
---|---|---|
| String | Geofence ID. |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
Request Body
Name | Type | Description |
---|---|---|
| Object | A geofence body example: |
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 |
---|---|---|
| String | Geofence ID. |
Headers
Name | Type | Description |
---|---|---|
| String | Bearer authentication using the |
Swagger Doc
Last updated