List of Deprecating Resources

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

---

Device Data API

Get Daily Distance Driven by User Device ID

GET {baseUrl}/v1/user/device-data/{userDeviceId}/daily-distance

Retrieves a daily summary of distances driven (in kilometers) tracked on the user device.

Path Parameters

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

Query Parameters

Name	Type	Description
time_zone*	String	Timezone in TZ Identifier format. Common examples are America/Los_Angeles and America/New_York; etcetera source files (Etc/GMT-0) is also supported.

Headers

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

200: Success

{
    "days": [
        {
            "date": "2024-01-14",
            "distance": 37.19921875
        },
        {
            "date": "2024-01-15",
            "distance": null
        },
        {
            "date": "2024-01-16",
            "distance": null
        },
        {
            "date": "2024-01-17",
            "distance": 8.40234375
        },
        {
            "date": "2024-01-18",
            "distance": 14.5
        },
        {
            "date": "2024-01-19",
            "distance": null
        },
        {
            "date": "2024-01-20",
            "distance": null
        },
        {
            "date": "2024-01-21",
            "distance": null
        },
        {
            "date": "2024-01-22",
            "distance": null
        },
        {
            "date": "2024-01-23",
            "distance": null
        },
        {
            "date": "2024-01-24",
            "distance": 11
        }
    ]
}

401: Unauthorized

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

404: Not Found

Get Total Distance Driven by User Device ID

GET {baseUrl}/v1/user/device-data/{userDeviceId}/distance-driven

Retrieves a total distance driven (in kilometers) tracked on the user device since connection was established. Returns 0 if no odometer data was ever received.

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

{
    "distanceDriven": 778.0999999999985,
    "units": "kilometers"
}

401: Unauthorized

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

404: Not Found

---

Device Definitions API

List All Device Definitions

GET {baseUrl}/device-definitions/all

Retrieves a list of all device definitions.

⚠️ This endpoint returns all the device definitions of all vehicles, the data volume is very large so please handle with care.

200: OK Successfully retrieved all device definitions.

401: Unauthorized Invalid or expired JWT.

List All Available Integrations for a Device Definition by Device Definition ID

GET {baseUrl}/device-definitions/{deviceDefinitionId}/integrations

Lists all available integrations for a specific device definition by Device Definition ID.

200: OK Successfully retrieved all available integrations for the particular device definition.

401: Unauthorized Invalid or expired JWT.

404: Not Found The device definition cannot be found.

500: Internal Server Error DIMO server errors.

Decode An Array of VINs Returning JSON

POST {baseUrl}/bulk-decode

Decodes a list of Vehicle Identification Numbers, returning in JSON format.

Request Body

Name	Type	Description
vins*	[String]	An array of Vehicle Identification Numbers (VIN).

200: OK Successfully decodes a list of VINs.

{
    "decoded_vins": [
        {
            "vin": "JTJGARBZ0M5023423",
            "device_definition_id": "26G4j1YDKZhFeCsn13MAlyU3Y2X",
            "device_make": {
                "id": "2681cTRIYnN3uTGARvXu9BCPis7",
                "name": "Lexus",
                "logo_url": null,
                "oem_platform_name": "Lexus Enform",
                "tokenId": 69,
                "nameSlug": "lexus",
                "external_ids": {
                    "edmunds": "200705856",
                    "parkers": "lexus"
                },
                "externalIdsTyped": [
                    {
                        "vendor": "edmunds",
                        "id": "200705856"
                    },
                    {
                        "vendor": "parkers",
                        "id": "lexus"
                    }
                ],
                "metadata": null,
                "metadataTyped": null,
                "hardware_template_id": null,
                "created_at": "0001-01-01T00:00:00Z",
                "updated_at": "0001-01-01T00:00:00Z"
            },
            "device_year": 2021,
            "device_model": "Standard Trim",
            "compatibility_features": [
                {
                    "features": [
                        {
                            "key": "location",
                            "support_level": 2,
                            "css_icon": "location_on",
                            "display_name": "Location"
                        },
                        {
                            "key": "odometer",
                            "support_level": 2,
                            "css_icon": "custom_odometer",
                            "display_name": "Odometer"
                        },
                        {
                            "key": "vin",
                            "support_level": 2,
                            "css_icon": "badge",
                            "display_name": "VIN"
                        }
                    ],
                    "level": "Bronze",
                    "integration_id": "22N2xaPOq2WW2gAHBHd0Ikn4Zob",
                    "integration_vendor": "SmartCar",
                    "region": "Americas",
                    "score": 44.68085
                },
                {
                    "features": [
                        {
                            "key": "location",
                            "support_level": 2,
                            "css_icon": "location_on",
                            "display_name": "Location"
                        },
                        {
                            "key": "odometer",
                            "css_icon": "custom_odometer",
                            "display_name": "Odometer"
                        },
                        {
                            "key": "vin",
                            "support_level": 2,
                            "css_icon": "badge",
                            "display_name": "VIN"
                        },
                        {
                            "key": "speed",
                            "css_icon": "speed",
                            "display_name": "Speed"
                        }
                    ],
                    "level": "Bronze",
                    "integration_id": "27qftVRWQYpVDcO5DltO5Ojbjxk",
                    "integration_vendor": "AutoPi",
                    "region": "Americas",
                    "score": 25.531916
                },
                {
                    "features": [
                        {
                            "key": "location",
                            "support_level": 1,
                            "css_icon": "location_on",
                            "display_name": "Location"
                        },
                        {
                            "key": "odometer",
                            "css_icon": "custom_odometer",
                            "display_name": "Odometer"
                        },
                        {
                            "key": "vin",
                            "support_level": 1,
                            "css_icon": "badge",
                            "display_name": "VIN"
                        },
                        {
                            "key": "range",
                            "display_name": "Range"
                        }
                    ],
                    "level": "No Data",
                    "integration_id": "27qftVRWQYpVDcO5DltO5Ojbjxk",
                    "integration_vendor": "AutoPi",
                    "region": "Europe"
                }
            ]
        }
    ],
    "not_decoded_vins": []
}

404: Not Found

500: Internal Server Error

Decode An Array of VINs Returning CSV

POST {baseUrl}/bulk-decode/csv

Decodes a list of Vehicle Identification Numbers, returning in CSV format.

Request Body

Name	Type	Description
vins*	[String]	An array of Vehicle Identification Numbers (VIN).

200: OK Successfully decodes a list of VINs.

404: Not Found

500: Internal Server Error

---

Users API

Get User's Other Accounts

GET {baseUrl}/v1/user/check-accounts

Retrieves other connected accounts of the authenticated user.

Headers

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

200: OK Successfully retrieved user's other accounts.

{
    "otherAccounts": [
        {
            "type": "google",
            "login": "[e-mail]"
        }
    ]
}

400: Bad Request

500: Internal Server Error

401: Unauthorized Invalid or expired JWT.