ELD / Samsara Integration

Connecting Samsara to SALLY enables automatic Hours of Service (HOS) data sync, eliminating the need to manually provide driver HOS state when planning routes. SALLY pulls HOS data, vehicle locations, and diagnostic codes from Samsara every 15 minutes (configurable).

What You Get

Once the Samsara integration is active, SALLY automatically:

• Syncs driver HOS — Current hours driven, on-duty time, cycle hours, break status
• Tracks vehicle location — Real-time GPS position for route deviation detection
• Reads diagnostics — Engine fault codes and tire pressure for mechanical alerts
• Matches drivers — Links Samsara driver profiles to SALLY driver records by license number or name

Prerequisites

• A Samsara account with API access enabled
• A Samsara API token (generated at cloud.samsara.com/settings/api)
• Admin or Owner role in SALLY

Step 1: Get Your Samsara API Token

1. Log in to your Samsara dashboard at cloud.samsara.com
2. Navigate to Settings > API Tokens
3. Click Create API Token
4. Name the token (e.g., “SALLY Integration”)
5. Grant the following permissions:
   • Fleet > Read (drivers, vehicles, locations)
   • Safety > Read (HOS data)
   • Diagnostics > Read (fault codes, TPMS)
6. Copy the token

Step 2: Create the Integration in SALLY

curl -X POST https://sally-api.apps.appshore.in/api/v1/integrations \
  -H "X-API-Key: $SALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "samsara",
    "name": "Samsara ELD - Production",
    "config": {
      "apiToken": "samsara_api_XXXXXXXXXXXXXXXXXXXX",
      "orgId": "org_12345"
    },
    "syncIntervalMinutes": 15
  }'

JavaScript (fetch):

const response = await fetch(
  "https://sally-api.apps.appshore.in/api/v1/integrations",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.SALLY_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      vendor: "samsara",
      name: "Samsara ELD - Production",
      config: {
        apiToken: process.env.SAMSARA_API_TOKEN,
        orgId: "org_12345",
      },
      syncIntervalMinutes: 15,
    }),
  }
);
 
const integration = await response.json();
console.log("Integration ID:", integration.id);

Response:

{
  "id": "int_s1a2m3s4",
  "vendor": "samsara",
  "category": "ELD",
  "name": "Samsara ELD - Production",
  "status": "CONFIGURED",
  "syncIntervalMinutes": 15,
  "createdAt": "2026-02-10T10:00:00Z"
}

Configuration Fields

Step 3: Test the Connection

Verify that SALLY can reach Samsara with your credentials:

curl -X POST https://sally-api.apps.appshore.in/api/v1/integrations/int_s1a2m3s4/test \
  -H "X-API-Key: $SALLY_API_KEY"

Response (success):

{
  "id": "int_s1a2m3s4",
  "testResult": "SUCCESS",
  "message": "Successfully connected to Samsara API. Found 12 vehicles and 8 drivers.",
  "details": {
    "vehiclesFound": 12,
    "driversFound": 8,
    "hosDataAvailable": true,
    "gpsDataAvailable": true,
    "diagnosticsAvailable": true,
    "apiVersion": "v1",
    "latency": "245ms"
  },
  "testedAt": "2026-02-10T10:01:00Z"
}

A successful test automatically activates the integration and triggers the first data sync.

Step 4: Verify Data Sync

After the first sync completes, check that HOS data is flowing by querying a driver’s HOS endpoint:

curl https://sally-api.apps.appshore.in/api/v1/drivers/drv_a1b2c3d4/hos \
  -H "X-API-Key: $SALLY_API_KEY"

Response:

{
  "driverId": "drv_a1b2c3d4",
  "driverName": "Mike Johnson",
  "currentHoursDriven": 3.5,
  "currentOnDutyTime": 6.2,
  "currentCycleUsed": 45.5,
  "hoursSinceLastBreak": 3.5,
  "lastRestartDate": "2026-02-09T06:00:00Z",
  "driveTimeRemaining": 7.5,
  "dutyTimeRemaining": 7.8,
  "cycleTimeRemaining": 24.5,
  "breakRequired": false,
  "breakRequiredWithin": 4.5,
  "currentDutyStatus": "ON_DUTY_DRIVING",
  "lastStatusChange": "2026-02-10T10:30:00Z",
  "source": "SAMSARA",
  "lastSyncedAt": "2026-02-10T10:05:00Z"
}

Notice the source field shows SAMSARA, confirming data is coming from the integration.

How SALLY Uses Samsara Data

Route Planning

When a Samsara integration is active, you no longer need to provide the driverState field in route planning requests. SALLY automatically fetches the latest HOS data from the last sync:

# Without Samsara -- you must provide driverState
curl -X POST https://sally-api.apps.appshore.in/api/v1/routes/plan \
  -H "X-API-Key: $SALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "driverId": "drv_a1b2c3d4",
    "vehicleId": "veh_e5f6g7h8",
    "driverState": {
      "hoursDriven": 3.5,
      "onDutyTime": 6.2,
      "hoursSinceBreak": 3.5
    },
    "stops": [...]
  }'

# With Samsara -- driverState is optional (auto-populated from ELD)
curl -X POST https://sally-api.apps.appshore.in/api/v1/routes/plan \
  -H "X-API-Key: $SALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "driverId": "drv_a1b2c3d4",
    "vehicleId": "veh_e5f6g7h8",
    "stops": [...]
  }'

If you provide driverState explicitly, it overrides the Samsara data for that specific request. This is useful for “what-if” planning scenarios.

Continuous Monitoring

With Samsara connected, SALLY’s monitoring service uses real-time HOS data to:

• Detect when a driver is approaching HOS limits and generate proactive alerts
• Compare the driver’s actual position against the planned route for deviation detection
• Read diagnostic trouble codes and generate mechanical alerts

Driver Matching

SALLY matches Samsara drivers to SALLY driver records using the following logic:

1. License number match (primary) — If the CDL number in Samsara matches a SALLY driver
2. Name match (secondary) — If first and last name match exactly
3. Manual override — You can manually link a Samsara driver ID to a SALLY driver

Unmatched Samsara drivers appear in the integration dashboard for manual review.

Sync Interval Recommendations

Adjust the sync interval at any time:

curl -X PATCH https://sally-api.apps.appshore.in/api/v1/integrations/int_s1a2m3s4 \
  -H "X-API-Key: $SALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "syncIntervalMinutes": 5
  }'

Troubleshooting

Test Fails with “Authentication Failed”

• Verify your Samsara API token has not been revoked
• Confirm the token has the required permissions (Fleet Read, Safety Read, Diagnostics Read)
• Check that the orgId matches your Samsara organization

Drivers Not Matching

• Verify that driver license numbers in SALLY match those in Samsara
• Check for formatting differences (dashes, spaces)
• Use the integration dashboard to manually link unmatched drivers

HOS Data Appears Stale

• Check the lastSyncedAt timestamp on the HOS response
• Verify the integration status is ACTIVE (not ERROR or DISABLED)
• Trigger a manual sync: POST /api/v1/integrations/int_s1a2m3s4/sync

Sync Errors

If a sync fails, the integration moves to ERROR status. Check the error details:

curl https://sally-api.apps.appshore.in/api/v1/integrations/int_s1a2m3s4 \
  -H "X-API-Key: $SALLY_API_KEY"

Common sync errors:

Next Steps

• Drivers API — View synced HOS data
• TMS Integration — Connect McLeod or Project44
• Error Handling — Handle integration errors
• Integrations Overview — All supported vendors