Devices API

Vehicle (User Device) Queries 🔐

List All Devices Associated with the User

GET {baseUrl}/v1/user/devices/me

Lists all devices associated with the authenticated user.

Headers

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

200: OK

401: Unauthorized

500: Internal Server Error

List All Devices Shared with the User

GET {baseUrl}/v1/user/devices/shared

Lists all devices shared with the authenticated user.

Headers

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

200: OK

401: Unauthorized

500: Internal Server Error

Device Commands 🔐

Get Aftermarket Device Data by Device Serial Number

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

Retrieves the aftermarket device data for the device serial number.

Headers

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

200: OK

{
    "isUpdated": true,
    "deviceId": "",
    "unitId": "24601960806",
    "dockerReleases": null,
    "hwRevision": "",
    "template": 0,
    "lastCommunication": "0001-01-01T00:00:00Z",
    "releaseVersion": "",
    "shouldUpdate": false,
    "tokenId": 13986,
    "ethereumAddress": "0xddf4c4ec0023d957f4dbefebbd158bf6e02be7c8",
    "ownerAddress": "0xf9D26323Ab49179A6d57C26515B01De018553487",
    "beneficiaryAddress": "0xf9d26323ab49179a6d57c26515b01de013253787",
    "claim": {
        "status": "Confirmed",
        "hash": "0xa4944c7a148810c196d034af682d39dbe653e6eb56f13924dec2852e122f674f",
        "createdAt": "2024-01-02T23:37:56.783001Z",
        "updatedAt": "2024-01-02T23:38:13.557678Z"
    },
    "pair": {
        "status": "Confirmed",
        "hash": "0x3552c112c4281822eed1c45f0ee23c53969acfe8961419d673bdb504234d61d7",
        "createdAt": "2024-02-03T22:20:58.597529Z",
        "updatedAt": "2024-02-03T22:21:18.823898Z"
    },
    "manufacturer": {
        "tokenId": 142,
        "name": "Hashdog"
    }
}

500: Internal Server Error

401: Unauthorized Invalid or expired JWT.

Get Aftermarket Device Data by Device Serial Number

POST {baseUrl}/v1/aftermarket/device/by-serial/{serial}/update

Retrieves the aftermarket device data for the device serial number.

Headers

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

200: OK

{
    "isUpdated": true,
    "deviceId": "",
    "unitId": "24601960806",
    "dockerReleases": null,
    "hwRevision": "",
    "template": 0,
    "lastCommunication": "0001-01-01T00:00:00Z",
    "releaseVersion": "",
    "shouldUpdate": false,
    "tokenId": 13986,
    "ethereumAddress": "0xddf4c4ec0023d957f4dbefebbd158bf6e02be7c8",
    "ownerAddress": "0xf9D26323Ab49179A6d57C26515B01De018553487",
    "beneficiaryAddress": "0xf9d26323ab49179a6d57c26515b01de013253787",
    "claim": {
        "status": "Confirmed",
        "hash": "0xa4944c7a148810c196d034af682d39dbe653e6eb56f13924dec2852e122f674f",
        "createdAt": "2024-01-02T23:37:56.783001Z",
        "updatedAt": "2024-01-02T23:38:13.557678Z"
    },
    "pair": {
        "status": "Confirmed",
        "hash": "0x3552c112c4281822eed1c45f0ee23c53969acfe8961419d673bdb504234d61d7",
        "createdAt": "2024-02-03T22:20:58.597529Z",
        "updatedAt": "2024-02-03T22:21:18.823898Z"
    },
    "manufacturer": {
        "tokenId": 142,
        "name": "Hashdog"
    }
}

500: Internal Server Error

401: Unauthorized Invalid or expired JWT.

Document Operations 🔐

List All Documents for the User

GET {baseUrl}/v1/documents

Retrieves a list containing all documents for an authorized user.

Headers

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

200: OK Successfully retrieved a list of all documents.

401: Unauthorized Invalid or expired JWT.

500: Internal Server Error

Get a Document for the User by Document ID

GET {baseUrl}/v1/documents/{documentId}

Retrieves a document for an authorized user with the provided document ID.

Path Parameters

Name	Type	Description
documentId*	String

Headers

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

200: OK Successfully retrieved a document.

401: Unauthorized Invalid or expired JWT.

500: Internal Server Error

Download a Document for the User by Document ID

GET {baseUrl}/v1/documents/{documentId}/download

Downloads a document for an authorized user with the provided document ID.

Path Parameters

Name	Type	Description
documentId*	String

Headers

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

200: OK Successfully downloaded a document.

401: Unauthorized Invalid or expired JWT.

500: Internal Server Error

Upload a New Document for the User

POST {baseUrl}/v1/documents

Uploads a new document for an authorized user.

⚠️ Body type needs to be form-data

Headers

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

Request Body

Name	Type	Description
file*	File	The file to upload.
name*	String	The name of the document.
type*	String	The type of the document.
userDeviceId	String	Optional user device ID.

200: OK Successfully uploaded a document.

401: Unauthorized Invalid or expired JWT.

500: Internal Server Error

Delete a Document for the User by Document ID

DELETE {baseUrl}/v1/documents/{documentId}

Deletes a document for an authorized user with the provided document ID.

Path Parameters

Name	Type	Description
documentId*	String

Headers

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

401: Unauthorized Invalid or expired JWT.

500: Internal Server Error

204: No Content Successfully removed a document.

Aftermarket Device Operations

Unclaim the Device by Device Serial Number

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

Dev-only endpoint for removing a claim. Removes the flag on-chain and clears the owner in the database.

Path Parameters

Name	Type	Description
serial*	String

Headers

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

204: No Content

401: Unauthorized Invalid or expired JWT.

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

---

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 Devices Endpoints

Path Parameters

Name	Type	Description
address*	String	Ethereum address.

200: Success

500: Internal Server Error

---

Vehicle Error Codes 🔐

Developer Notes

1. The following endpoints defers back to using the User JWT 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	Developer JWT from the authentication step.

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	Developer JWT from the authentication step.

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	Developer JWT from the authentication step.

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

---