Device Definitions API

Developer Notes

As of 2024, the source of truth for Device Definitions are now stored in Tableland - a decentralized cloud database. Device Definitions details can now be returned from Identity API (see common queries). This API now consist of some helper functions for development needs.

Base URLs

Production

https://device-definitions-api.dimo.zone

---

VIN Decoding

Submit a Decode VIN Request

POST {baseUrl}/device-definitions/decode-vin

Submits a decoding request for vehicle identification number, returns the device definition ID corresponding to the VIN.

Use application/json for raw body parameters.

Request Body

Name	Type	Description
countryCode*	String	3-letter ISO 3166-1 alpha-3 country code. Example: "countryCode": "USA"
vin*	String	Vehicle identifier number. Example: "vin": "1HGCM66886A015965"

Headers

Name	Type	Description
Authorization*	String	Developer JWT from the authentication step.

200: Success

{ deviceDefinitionId: 'lexus_nx_2021', newTransactionHash: '' }

404: Not Found

500: Internal Server Error

VIN Decoding: Data SDK Function Calls

TypeScript

await dimo.devicedefinitions.decodeVin({
    developerJwt, 
    countryCode, 
    vin
});

Python

dimo.device_definitions.decode_vin(dev_jwt, country_code, vin)

C#

dimoClient.DeviceDefinitionsService.DecodeVinAsync(
    access_token,
    countryCode,
    vin
);

---

Device Definitions Lookup

Get Device Definitions by Search Filters

GET {baseUrl}/device-definitions/search

Retrieves a list of device definitions by search filters.

Query Parameters

Name	Type	Description
query*	String	Query filter (e.g. Lexus gx 2023)
makeSlug	String	Make of the vehicle (e.g. audi, lexus, etc)
modelSlug	String	Model of the vehicle (e.g. Tacoma, Accord, etc)
year	Number	Year of the vehicle (e.g. 2024)
page	Number	Page number (for pagination, defaults to the 1st page)
pageSize	Number	Page size (to specify the items to show in one page)

200: Success

{
  "deviceDefinitions": [
    {
      "id": "lexus_gx_2023",
      "legacy_ksuid": "2ZvYP0pSbQoXPh2WUdQPeA6g4dM",
      "name": "2023 Lexus GX",
      "make": "Lexus",
      "model": "GX",
      "year": 2023,
      "imageUrl": ""
    },
    {
      "id": "lexus_gx-460_2023",
      "legacy_ksuid": "2CMmZpP6YjaKQlQnGDSAzQ4PJEG",
      "name": "2023 Lexus GX 460",
      "make": "Lexus",
      "model": "GX 460",
      "year": 2023,
      "imageUrl": ""
    }
  ],
  "facets": {
    "makes": [
      {
        "name": "Lexus",
        "count": 2
      }
    ],
    "models": [
      {
        "name": "GX",
        "count": 1
      },
      {
        "name": "GX 460",
        "count": 1
      }
    ],
    "years": [
      {
        "name": "2023",
        "count": 2
      }
    ]
  },
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 2,
    "totalPages": 1
  }
}

500: Internal Server Error

Device Definitions by Search: Data SDK Function Calls

TypeScript

await dimo.DeviceDefinitions.search({
    query, 
    makeSlug, 
    modelSlug, 
    year, 
    page, 
    pageSize
});

Python

dimo.device_definitions.search(query, make_slug, model_slug, year, page, page_size)

C#

dimoClient.DeviceDefinitionsService.SearchAsync(
    query,
    makeSlug,
    modelSlug,
    year,
    page,
    pageSize
);