🚧

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, asset types for assets, or whatever else fits your business needs.

Once attributes have been created via the API, dashboard admins can use them as filters on report pages:

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:

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 (this should be a Driver ID if the entityType is set to driver, and this should be a Vehicle, Trailer, or Equipment ID if the entityType is set to asset).

{
    "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 [beta] Create an attribute reference docs.

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 an asset (either a Vehicle, Trailer, or Equipment object), use the PATCH endpoint for that object 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 object. The attributes field contains the list of attributes assigned for that vehicle (these attributes will have an entityType of asset because a Vehicle is a type of asset).

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 asset

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 [beta] Retrieve an attribute reference docs.

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 asset

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 [beta] List all attributes by entity type reference docs.

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 asset

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 [beta] Deleting an attribute reference docs.