📘

This guide is meant to walk you through best practices for TMS integrations and provide an overview of Samsara platform.

For a quick listing of data available through the API, check out the REST API Overview page.

Introduction

A TMS integration with Samsara can consist of many different features:

• Hours of Service
• GPS tracking
• Load assignment and tracking
• Dispatch ↔️ driver messaging
• Driver forms

Samsara gateways, cameras, and sensors capture GPS and telematics data and send it to the Samsara cloud.

Drivers use the Samsara mobile app to track hours of service, view and complete loads, send messages with fleet admins, and submit forms.

A transport management system can integrate with all of these processes through the Samsara REST API and webhooks.

The Samsara Platform

The Cloud Dashboard

In Samsara, each fleet or carrier has its own organization that houses its set of drivers, vehicles, routes, etc.

Each organization has its own dashboard at cloud.samsara.com, where administrators can log in to manage the fleet.

Check out the Set Up & Administration section of the knowledge base to learn more about admins and working with the dashboard.

Vehicles, Trailers, and more

In Samsara, a vehicle is created whenever a Samsara Vehicle Gateway is activated within an organization. Vehicle gateways can be plugged into any OBD-II or J1939 port, such as in cars and light trucks, tractor trailers, and heavy duty, industrial, or specialized vehicles.

The vehicle object will contain all the GPS and diagnostic data that the gateway sends to the cloud.

Check out the Vehicle Gateway section of the knowledge base for details on vehicle gateway installation, settings, and management.

In Samsara, trailers are created and managed through the cloud dashboard. Organizations can also enable drivers to create trailers through the Driver App. Once defined in the dashboard, trailers can be linked to Samsara Asset Gateways for GPS and diagnostic tracking. See the Trailer Management in Samsara knowledge base article for more details.

Within the Samsara API, assets is a broad term that refers to entities connected to a Samsara Asset Gateway. These can be trailers (as described above), heavy duty powered equipment, or unpowered asset trackers. See the Assets & Sensors section of the knowledge base for more details.

Drivers and the Driver App

Drivers log into the Samsara mobile app to track hours of service, view and complete loads, send messages with fleet admins, and submit forms.

Drivers are created and managed by Samsara administrators through the cloud dashboard, or they can be managed through the API.

The presentation below gives an overview of the Driver App workflow. Check out the Driver App section of the knowledge base for details on the mobile app.

Getting Started

Development Tools

There are two types of development tools available to build integrations with the Samsara platform: the REST API and webhooks.

The REST API allows your integration to send HTTP requests to create, read, update, manage, and delete data within an organization (GPS data, hours of service, routes, etc). You authenticate with the REST API using an API token. Check out the REST API Overview for a quick description of all the data available through the REST API.

Webhooks allows your integration to receive HTTP requests from Samsara when an alert is triggered, such as entering/exiting geofences, document submissions, etc. Webhooks and alerts are created and managed using the Samsara dashboard. Check out the Webhooks guide for details.

The Developer Metrics Page within the Samsara dashboard allows you to debug both REST API requests and webhook notifications.

Authentication

All calls to the Samsara REST API must be authenticated using an API access token.

A token is generated by an administrator in the Samsara dashboard. The token can then be used to access the organization's data using the REST API. Tokens can either have full-access or read-only privileges. See the Authentication page for instructions on how to create an API access token.

The token is passed into the Authorization HTTP header. In the example request below, you would replace TOKEN with your API token:

curl --request GET 'https://api.samsara.com/me' \
--header 'Authorization: Bearer <<token>>'

The response is in JSON format. The /me endpoint above returns information about the organization that the API token belongs to - specifically an organization's ID, name, and carrier settings.

{
    "data": {
        "id": "1234",
        "name": "Samsara Trucking",
        "carrierSettings": {
            "carrierName": "Samsara Trucking",
            "mainOfficeAddress": "1990 Alameda St, San Francisco, CA 94103",
            "dotNumber": 1234
        }
    }
}

External IDs

Many different entities within Samsara support external IDs, or user-provided identifiers. External IDs are managed through the API and help in synchronizing data between Samsara and an external system. For example, you could create a "tmsIntegration" ID on an organization's drivers to be able to reference drivers by their IDs within the TMS system.

Check out the External IDs guide for details on working with external IDs.

Tags

Tags are used by Samsara administrators to organize or group the data within an organization. Adminstrators can create tags to represent geographies (regions, terminals, etc), organizational departments, or other divisions within the organization.

Once a tag has been created, entities such as vehicles, drivers, and addresses can be added to the tag. Entities can be part of multiple tags.

The cloud dashboard allows admins to filter reports and pages to specific tags, and the API also provides the ability to filter responses to specific tags.

Tags can also be hierarchical, meaning a parent tag can have child tags with to represent hierarchical groupings.

Many API endpoints allow filtering by tags via query parameters. See the Filtering guide for details and examples.

Synchronizing Data

Drivers

Drivers can be created and managed both through the Samsara cloud dashboard as well as the Samsara REST API.

Once a driver has been created, it cannot be deleted. Instead, drivers can be deactivated.

Active drivers are those that are actively working for the fleet. Deactivated drivers are not currently working for the fleet, but their data is still available for compliance purposes. Drivers can be deactivated and reactivated at any time both through the cloud dashboard and the REST API.

To deactivate or reactivate drivers via the API, set the driverActivationStatus field to be active or deactivated via the Update a driver endpoint for the given driver:

curl --request PATCH 'https://api.samsara.com/fleet/drivers/:driverId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <<token>>' \
--data-raw '{
    "driverActivationStatus": "deactivated"
}'

Samsara ➡️ TMS

You can call the List all drivers endpoint to list all active drivers in the Samsara system:

curl --request GET 'https://api.samsara.com/fleet/drivers' \
--header 'Authorization: Bearer <<token>>'

The JSON response will contain a list of drivers in the data array. If there are many drivers in the fleet, the response will be paginated. See the Pagination guide for details.

{
    "data": [
        {...},
        {...}
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

If you want to get the list of deactivated drivers in the fleet, you can set the driverActivationStatus query param to deactivated:

curl --request GET 'https://api.samsara.com/fleet/drivers?driverActivationStatus=deactivated' \
--header 'Authorization: Bearer <<token>>'

If you want to list drivers that have been created or updated after a certain time, you can use the createdAfterTime or updatedAfterTime query parameters. Both these parameters accept an RFC 3339 timestamp:

curl --request GET 'https://api.samsara.com/fleet/drivers?createdAfterTime=2020-07-01T00:00:00Z' \
--header 'Authorization: Bearer <<token>>'

After pulling a list of drivers from the Samsara system, it may be helpful to add your own external ID to each driver so that you can reference the drivers by your own ID in the future. To update an existing driver with an external ID, use the Update a driver endpoint for the given driver:

curl --request PATCH 'https://api.samsara.com/fleet/drivers/:samsaraDriverId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <<token>>' \
--data-raw '{
    "externalIds": {
        "tmsIntegration": "tmsDriverId"
}'

TMS ➡️ Samsara

You can synchronize drivers from your system into Samsara by using the Create a driver endpoint for drivers. The following example creates a driver with the bare minimum required fields: the driver's name, Driver App username, and Driver App password. Additionally, the request also includes an external ID so that we can refer to that driver by our custom ID later.

curl --request POST 'https://api.samsara.com/fleet/drivers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <<token>>' \
--data-raw '{
    "name": "Driver Danielle",
    "username": "driver.danielle",
    "password": "password",
    "externalIds": {
        "tmsIntegration": "[email protected]"
    }
}'

Vehicles

In Samsara, vehicle objects are only created when a Samsara Vehicle Gateway is activated within the organization.

Samsara ➡️ TMS

The List all vehicles endpoint allows you to retrieve all vehicles in the fleet:

curl --request GET 'https://api.samsara.com/fleet/vehicles' \
--header 'Authorization: Bearer <<token>>'

The JSON response will contain a list of vehicles in the data array. If there are many vehicles in the fleet, the response will be paginated. See the Pagination guide for details.

{
    "data": [
        {...},
        {...}
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

Within Samsara, vehicles cannot be deleted. This allows their data to be preserved for compliance reasons. If a vehicle is retired from the fleet, it it best to indicate this through the name or notes fields of the vehicle.

If a vehicle gateway has been removed from one vehicle and reactivated in another vehicle, the original vehicle object will be preserved, and a new vehicle object will be created to represent the new physical vehicle. The old vehicle will no longer have a serial field, indicating that vehicle object is not associated with any vehicle gateways.

When a vehicle is created, two external IDs are automatically created:

These automatical external IDs can help you match Samsara vehicles to the vehicle records within your system.

TMS ➡️ Samsara

You can use the Update a vehicle endpoint on vehicles to update the vehicle with information from your system, such the vehicle's name, license plate, notes, or your own external IDs. The following example request updates those fields for an example vehicle:

curl --request PATCH 'https://api.samsara.com/fleet/vehicles/:samsaraVehicleId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <<token>>' \
--data-raw '{
    "name": "Name from TMS",
    "licensePlate": "CA-123456",
    "notes": "Notes from TMS",
    "externalIds": {
        "tmsIntegration": "vehicleTmsId"
    }
}'

Addresses

Addresses in Samsara are geofences that represent known locations. They can be used as the geofence locations for route stops and are utilized in the Time on Site an other reports in the Samsara dashboard.

See the Addresses guide for details on creating, listing, and managing addresses.

TMS Use Cases

Hours of Service

Drivers track hours of service using the Driver App. Administrators can view compliance reports and manage hours of service through the cloud dashboard. Hours of service logs and duty status can be pulled via the API as well.

See the Compliance & ELD API Guide for an overview of different Hours of Service API use cases and example code.

See the Compliance & Hours of Service knowledge base section for details on how Hours of Service tracking works within the Samsara dashboard and Driver App.

GPS Tracking

Samsara gateways provide GPS and diagnostics for real-time and historical reporting purposes.

To track vehicles, see the Telematics guide for details on how to utilize the GET /fleet/vehicles/stats API endpoints.

To track trailers and other assets, you'll want to use the List current location for all assets API endpoint.

To track reefer data, you'll want to use the List stats for all reefers API endpoint.

Load Assignment & Tracking

Samsara refers to loads as routes. Routes are created and managed by administrators through the Samsara cloud dashboard or through the API. Drivers view routes through the Samsara mobile app. The Samsara vehicle gateway allows route progress to be automatically tracked using geofences and GPS data.

Samsara's route tracking system works best when route stops have been defined as a known Address within Samsara.

A typical Load Assignment & Tracking integration will include the following modules:

• Defining geofences to represent load stops. See the Addresses API Guide for how to define geofences using the Samsara API.
• Create & tracking routes. See the Routing API Guide for details and example code for using the Routing APIs.

Additionally, Samsara supports proposing vehicle, trailer, and shipping ID assignments to drivers through the Samsara Driver App. The Carrier Proposed Assignments APIs allow you to do this. (Note: these APIs propose vehicle/trailer assignments to drivers. Utilizing the routing APIs described above to assign loads to drivers).

Dispatch ↔️ Driver Messaging

Samsara administrators send and receive messages with drivers through the cloud dashboard. Admins can send messages to all drivers, a specific driver, or a group of drivers.

Drivers send and receive messages with admins through the Samsara mobile app.

The API provides two endpoints for working with messages:

Send dispatch messages to drivers

The Send a message to a list of driver ids. API allows you to send a dispatch message to a list of drivers.

The JSON request body should have two fields:

curl --request POST 'https://api.samsara.com/v1/fleet/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <<token>>' \
--data-raw '{
    "driverIds": [
        1654973
    ],
    "text": "Hey Driver!"
}'

🚧

The driverIds field does not currently support external IDs. Instead you can call GET /fleet/drivers/externalIdKey:externalIdValue to retrieve the full driver object with its Samsara ID. See the External IDs guide for examples on how to retrieve an object by its external ID.

List all messages

The Get all messages. endpoint allows you to list all messages between a start and end time. This endpoint returns both driver and dispatch messages.

The endpoint has two query parameters:

The following request returns the last 24 hours of messages (using the default values for the query parameters):

curl --request GET 'https://api.samsara.com/v1/fleet/messages' \
--header 'Authorization: Bearer <<token>>'

The JSON response contains a data array that lists both the driver and dispatch messages for the queried time range:

{
    "data": [
        {
            "driverId": 1654973,
            "text": "Yes.",
            "sentAtMs": 1603821606880,
            "sender": {
                "type": "driver",
                "name": "Tyler Freckmann"
            },
            "isRead": false
        },
        {
            "driverId": 1654973,
            "text": "Hey Tyler, can you drop off Trailer 123 at the next stop?",
            "sentAtMs": 1603820622674,
            "sender": {
                "type": "dispatch",
                "name": "Dispatch"
            },
            "isRead": true
        }
    ]
}

Driver Forms

Drivers can submit forms using the Samsara documents feature in the Driver App. Samsara administrators customize different types of forms and view/manage received forms in the cloud dashboard.

See the Documents API guide for details on how to create & submit documents on behalf of drivers, retrieve submitted documents, and create document submission webhook alerts.

Additionally, through the API, documents can be associated with a route stop as a Task for the driver to complete. See the Creating Stop Tasks section of the Routing API guide for how to create a stop task within a route using Documents.