Plan a Route

This is the core of SALLY — give it a driver, a truck, and a set of stops. SALLY gives you back a fully optimized, HOS-compliant route with rest stops and fuel stops inserted automatically.

Prerequisites

• An API key (get one here)
• A driver and vehicle in your tenant (see Manage Your Fleet if you haven't created these yet)

Set your environment variables:

export SALLY_API_KEY="sk_staging_your_key_here"
export SALLY_BASE="https://sally-api-staging.appshore.in/api/v1"

The scenario

Driver: Mike Johnson — CDL holder, 2 hours already driven today, 4 hours on duty.

Truck: Freightliner Cascadia — 150-gallon tank, currently at 60% fuel, 6.2 MPG.

Route: Chicago warehouse → Indianapolis customer → Columbus terminal.

The challenge: Mike has limited remaining drive time today. SALLY will figure out if he needs a rest stop and where to fuel up.

Plan the route

curl -X POST $SALLY_BASE/routes/plan \
  -H "Authorization: Bearer $SALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "driverId": "drv_a1b2c3d4",
    "vehicleId": "veh_e5f6g7h8",
    "driverState": {
      "currentDriveMinutes": 120,
      "currentOnDutyMinutes": 240,
      "currentCycleMinutes": 2400,
      "lastRestartAt": "2026-02-09T22:00:00Z"
    },
    "vehicleState": {
      "currentFuelGallons": 90,
      "currentLocation": {
        "lat": 41.8423,
        "lon": -87.6845
      }
    },
    "stops": [
      {
        "type": "PICKUP",
        "address": "2800 S Western Ave, Chicago, IL 60608",
        "lat": 41.8423,
        "lon": -87.6845,
        "scheduledArrival": "2026-02-10T09:00:00Z",
        "estimatedDwellMinutes": 30
      },
      {
        "type": "DELIVERY",
        "address": "5900 W Raymond St, Indianapolis, IN 46241",
        "lat": 39.7355,
        "lon": -86.2388,
        "scheduledArrival": "2026-02-10T15:00:00Z",
        "estimatedDwellMinutes": 45
      },
      {
        "type": "DELIVERY",
        "address": "4100 Groves Rd, Columbus, OH 43232",
        "lat": 39.9171,
        "lon": -82.8834,
        "scheduledArrival": "2026-02-10T21:00:00Z",
        "estimatedDwellMinutes": 30
      }
    ]
  }'

Understanding the response

SALLY returns a route plan broken into segments. Each segment is either a drive, a rest stop, a fuel stop, or time at a stop (dwell).

{
  "planId": "rte_f8e7d6c5",
  "status": "PLANNED",
  "hosCompliant": true,
  "totalDistanceMiles": 362,
  "totalDurationHours": 9.5,
  "segments": [
    {
      "type": "DRIVE",
      "from": "Chicago, IL",
      "to": "Indianapolis, IN",
      "distanceMiles": 181,
      "durationMinutes": 180,
      "hosAfter": {
        "driveMinutesUsed": 300,
        "driveMinutesRemaining": 360,
        "onDutyMinutesUsed": 420,
        "onDutyMinutesRemaining": 420
      }
    },
    {
      "type": "STOP",
      "location": "Indianapolis, IN",
      "purpose": "DELIVERY",
      "dwellMinutes": 45
    },
    {
      "type": "REST",
      "location": "Near Richmond, IN",
      "restType": "FULL_REST",
      "durationMinutes": 600,
      "reason": "Driver will exceed 11-hour drive limit before reaching Columbus without rest"
    },
    {
      "type": "DRIVE",
      "from": "Richmond, IN",
      "to": "Columbus, OH",
      "distanceMiles": 181,
      "durationMinutes": 170,
      "hosAfter": {
        "driveMinutesUsed": 170,
        "driveMinutesRemaining": 490,
        "onDutyMinutesUsed": 170,
        "onDutyMinutesRemaining": 670
      }
    },
    {
      "type": "STOP",
      "location": "Columbus, OH",
      "purpose": "DELIVERY",
      "dwellMinutes": 30
    }
  ]
}

What SALLY figured out

1. HOS validation — Mike has 2 hours already driven. After the 3-hour drive to Indianapolis, he'll be at 5 hours. After dock time and driving toward Columbus, he'd exceed the 11-hour drive limit. SALLY inserted a 10-hour rest stop near Richmond, IN.

2. Stop sequence — SALLY confirmed Chicago → Indianapolis → Columbus is optimal (no reordering needed for this route, but for complex multi-stop routes SALLY will optimize the sequence).

3. Compliance guarantee — hosCompliant: true means every segment respects federal HOS rules. No violations.

Activate the route

Once you're satisfied with the plan, activate it to start monitoring:

curl -X POST $SALLY_BASE/routes/rte_f8e7d6c5/activate \
  -H "Authorization: Bearer $SALLY_API_KEY"

Once activated, SALLY monitors the route 24/7 and sends alerts if anything changes — driver delays, dock hold-ups, HOS warnings, weather events.

Check for alerts

After activation, poll for alerts or set up webhooks to receive them in real time:

curl "$SALLY_BASE/alerts?routePlanId=rte_f8e7d6c5&status=ACTIVE" \
  -H "Authorization: Bearer $SALLY_API_KEY"

What's next