Samsara Developer Portal

Integrate your data with the Samsara API, customize the Samsara experience, and join a community of developers building with Samsara.

Get Started

Custom Attributes

Manage custom fields associated with different objects to help categorize and filter data

🚧

Beta APIs

These APIs are in beta and are likely to change before they enter a broader release. This guide gives you the opportunity to experiment and provide feedback – before the final release.

The final release of these APIs will be announced via the changelog.

Overview

You can define custom attributes for entities in your organization using the Attributes API. You can use these attributes to store information such as license types on drivers, vehicle types on vehicles, or whatever else fits your business needs.

To get started, you can create an attribute by specifying the attribute's properties, such as the name of the attribute, the type (string or number), whether it's single- or multi-valued, and the type of entity the attribute can be applied to.

Once an attribute is defined, you can set its value on different entities within your organization by using the PATCH operation for the entity.

When you retrieve or list entities via GET requests, the attribute will be included with the entity.

Attribute Object

The following properties define an attribute's configuration:

Property name

Description

attributeType
required

Indicates if the attribute is a string or a number type. For example, a "License Type" attribute might have string values and a "Vehicle Length" attribute might have number values.

attributeValueQuantity
required

Indicates if the attribute is single- or multi- valued. For example, a "Vehicle Length" attribute should only have a single value. On the other hand, you may want to allow a driver to have multi values for a "License Type" attribute.

entityType
required

Defines the type of entity that the attribute can be applied to. Attributes can be defined for driver or vehicle entities.

name
required, must be unique

Name of the attribute. Must be unique. For example, "License Type" or "Vehicle Length".

numberValues[] or stringValues[]
one is required

The list of valid values for the attribute. If the attribute is a string type, then the attribute will contain a list of valid stringValues. If the attribute is a number type, then it will contain a list of valid numberValues. Entities can only contain valid values for an attribute. For example, a "License Type" attribute could have "stringValues": ["Class A", "Class B", "Class C"]. Only those values would be allowed on the "License Type" attribute for drivers. Either numberValues[] or stringValues[] must be included when creating the attribute.

entities[]
optional

Lists all the entities that have values for the attribute (i.e., the drivers or vehicles have values for the attribute).

Create an attribute

To create a custom attribute, use the following POST request and include your API token in the Authorization header.

POST https://api.samsara.com/attributes

All create requests require you to submit a JSON request body.

The following JSON shows a sample request to create a custom attribute. All the fields below are required fields. (If the attribute is a number attribute, then numberValues[] must be included instead).

{
    "attributeType": "string",
    "attributeValueQuantity": "multi",
    "entityType": "driver",
    "name": "License Type",
    "stringValues": [
        "Class A",
        "Class B",
        "Class C"
    ]
}

The response will contain the attribute's id, which you should save in order to use the attribute later.

{
    "data": {
        "attributeType": "string",
        "attributeValueQuantity": "multi",
        "entityType": "driver",
        "name": "License Type",
        "stringValues": [
            "Class A",
            "Class B",
            "Class C"
        ],
        "id": "96129c91-99e8-4f21-83f2-b1316d5375b6",
        "entities": []
    }
}

The entities list is currently empty because the attribute has not been set on any entities yet.

If you want to set the attribute on multiple entities upon creation of the attribute, you can include the entities parameter in your POST request. The entityId should be the ID of the entity that you want to assign the attribute to (either a driver ID or a vehicle ID, depending on the type of attribute).

{
    "attributeType": "string",
    "attributeValueQuantity": "multi",
    "entityType": "driver",
    "name": "License Type",
    "stringValues": [
        "Class A",
        "Class B",
        "Class C"
    ],
    "entities": [
        {
            "entityId": "1654973",
            "stringValues": ["Class A"]
        },
        {
            "entityId": "4263096",
            "stringValues": ["Class B"]
        },
        ...
    ]
}

For setting the value of an attribute on an entity-by-entity basis, see Set Attribute Values.

For the full list of request and response properties, see the API Reference.

Limits

  • The maximum number of attributes allowed in an organization is 1000.
  • The maximum number of distinct values that an attribute can have is 1000.
  • The maximum number of attributes that a single entity can have is 20.
  • The maximum number of characters allowed for the name of an attribute is 190. Names must be unique.
  • Changing the attributeType after creation is not allowed.
  • attributeValueQuantity can be changed from single to multi after attribute creation but the reverse is not allowed.

Set attribute values

To set an attribute on a given entity, use the PATCH operation on the entity and include the list of attributes you'd like to apply to the entity.

For example, the following PATCH request sets the License Type attribute for the specified driver:

PATCH https://api.samsara.com/fleet/drivers/1654973
{
    "attributes": [
        {
            "id": "96129c91-99e8-4f21-83f2-b1316d5375b6",
            "stringValues": ["Class A"]
        }
    ]
}

The attributes array should contain the list of attributes you want to assign for the entity. You should include the id of the attribute and the desired stringValues or numberValues that you want to assign to that entity.

You can also include the attributes array in a POST request to /fleet/drivers if you want to assign attributes upon creation of the driver.

To set an attribute on a vehicle, use the PATCH endpoint for the vehicle with the desired attributes included in the request.

📘

Maximum number of attributes per entity

You may have a maximum of 20 attributes per entity.

Read entity attributes

When you GET an entity or a list of entities, the attributes for that entity will be included.

For example, the following GET request retrieves a vehicle. The attributes field contains the list of attributes assigned for that vehicle.

GET https://api.samsara.com/fleet/vehicles/samsara.vin:JTMBK32V895081147
{
    "data": {
        "id": "281474977075805",
        "name": "Little Red",
        "attributes": [
            {
                "name": "Ownership Type",
                "stringValues": ["Owned"],
                "id": "c37372fb-c266-457b-935c-4aaddf9f3252"
            }
        ],
        "vin": "JTMBK32V895081147",
        "serial": "G9MTH7CNKZ",
        "make": "TOYOTA",
        "model": "RAV4",
        "year": "2009",
        "harshAccelerationSettingType": "automatic",
        "notes": "",
        "licensePlate": "6KDB798",
        "externalIds": {
            "samsara.serial": "G9MTH7CNKZ",
            "samsara.vin": "JTMBK32V895081147"
        }
    }
}

Get attribute assignments

To list all entities that have been assigned to the attribute, use the following GET endpoint and include your API token in the Authorization header.

GET https://api.samsara.com/attributes/{id}?entityType=driver or vehicle

You must include the required query parameter entityType, and it must match the entityType of the attribute you are retrieving.

For example:

GET https://api.samsara.com/attributes/96129c91-99e8-4f21-83f2-b1316d5375b6?entityType=driver
{
    "data": {
        "name": "License Type",
        "id": "96129c91-99e8-4f21-83f2-b1316d5375b6",
        "entityType": "driver",
        "attributeType": "string",
        "attributeValueQuantity": "multi",
        "stringValues": ["Class A", "Class B", "Class C", "Non CDL"],
        "entities": [
            {
                "entityId": "1654973",
                "externalIds": {
                  "payrollId": "1234"
                },
                "name": "Tyler Freckmann",
                "stringValues": ["Class A"]
            },
            {
                "entityId": "4263096",
                "externalIds": {
                  "payrollId": "5678"
                },
                "name": "Matthew Moon",
                "stringValues": ["Class B"]
            },
            ...
        ]
    }
}

For the full list of request and response properties, see the API Reference.

List all attributes

To list all the attributes that you have defined in your organization, use the following GET endpoint and include your API token in the Authorization header.

GET https://api.samsara.com/attributes?entityType=driver or vehicle

Note: you must include the required query parameter entityType.

A successful response returns an HTTP 200 status code, and a JSON response like the following:

{
    "data": [
        {
            "name": "License Type",
            "id": "96129c91-99e8-4f21-83f2-b1316d5375b6",
            "entityType": "driver",
            "attributeType": "string",
            "attributeValueQuantity": "multi",
            "stringValues": ["Class A", "Class B", "Class C", "Non CDL"]
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

If you have many custom attributes, the response may be paginated. See the Pagination guide for details.

Note: this endpoint does not list the entities associated with each attribute. To list all entities associated with an attribute, see Get Attribute Assignments.

For the full list of request and response properties, see the API Reference.

Delete an attribute

To delete an attribute and all its assignments, use the following DELETE endpoint and include your API token in the Authorization header.

DELETE https://api.samsara.com/attributes?entityType=driver or vehicle

Note: you must include the required query parameter entityType.

A successful response returns an HTTP 204 status code with an empty response body.

For the full list of request and response properties, see the API Reference.

Updated 12 days ago


Custom Attributes


Manage custom fields associated with different objects to help categorize and filter data

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.