Vehicles API

The Vehicles API lets you register trucks in your fleet and maintain their specifications. Vehicle data — especially fuel tank capacity and fuel efficiency — directly impacts how SALLY plans routes and determines when fuel stops are needed.

Why Vehicle Data Matters

When SALLY plans a route, it uses the vehicle’s fuelTankCapacity and mpg to simulate fuel consumption along each segment. If the vehicle will run low before the next stop, SALLY automatically inserts a fuel stop at the most cost-effective station along the route.

A vehicle with a 150-gallon tank at 6.2 MPG has a range of approximately 930 miles on a full tank. SALLY factors in the current fuel level and plans fuel stops before the tank drops below a safe reserve threshold.

Create a Vehicle

curl -X POST https://sally-api.apps.appshore.in/api/v1/vehicles \
  -H "X-API-Key: $SALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "unitNumber": "TRK-2205",
    "make": "Kenworth",
    "model": "T680",
    "year": 2024,
    "vin": "1XKYD49X8RJ947623",
    "licensePlate": "TX-COM-2205",
    "fuelTankCapacity": 150,
    "mpg": 6.8,
    "status": "ACTIVE"
  }'

JavaScript (fetch):

const response = await fetch(
  "https://sally-api.apps.appshore.in/api/v1/vehicles",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.SALLY_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      unitNumber: "TRK-2205",
      make: "Kenworth",
      model: "T680",
      year: 2024,
      vin: "1XKYD49X8RJ947623",
      licensePlate: "TX-COM-2205",
      fuelTankCapacity: 150,
      mpg: 6.8,
      status: "ACTIVE",
    }),
  }
);
 
const vehicle = await response.json();

Response:

{
  "id": "veh_k3l4m5n6",
  "unitNumber": "TRK-2205",
  "make": "Kenworth",
  "model": "T680",
  "year": 2024,
  "vin": "1XKYD49X8RJ947623",
  "licensePlate": "TX-COM-2205",
  "fuelTankCapacity": 150,
  "mpg": 6.8,
  "status": "ACTIVE",
  "createdAt": "2026-02-10T10:00:00Z",
  "updatedAt": "2026-02-10T10:00:00Z"
}

Required Fields

Field	Type	Description
`unitNumber`	string	Fleet-assigned unit number (must be unique within your tenant)

Optional Fields

Field	Type	Description
`make`	string	Manufacturer (Freightliner, Kenworth, Peterbilt, Volvo, etc.)
`model`	string	Model name (Cascadia, T680, 579, VNL, etc.)
`year`	number	Model year
`vin`	string	17-character Vehicle Identification Number
`licensePlate`	string	License plate number
`fuelTankCapacity`	number	Total fuel capacity in gallons
`mpg`	number	Average miles per gallon
`status`	string	Initial status: `ACTIVE` (default) or `INACTIVE`

List Vehicles

curl "https://sally-api.apps.appshore.in/api/v1/vehicles?status=ACTIVE&page=1&pageSize=25" \
  -H "X-API-Key: $SALLY_API_KEY"

JavaScript (fetch):

const params = new URLSearchParams({
  status: "ACTIVE",
  page: "1",
  pageSize: "25",
});
 
const response = await fetch(
  `https://sally-api.apps.appshore.in/api/v1/vehicles?${params}`,
  {
    headers: { "X-API-Key": process.env.SALLY_API_KEY },
  }
);
 
const { data, total } = await response.json();

Response:

{
  "data": [
    {
      "id": "veh_e5f6g7h8",
      "unitNumber": "TRK-4821",
      "make": "Freightliner",
      "model": "Cascadia",
      "year": 2023,
      "fuelTankCapacity": 150,
      "mpg": 6.2,
      "status": "ACTIVE"
    },
    {
      "id": "veh_k3l4m5n6",
      "unitNumber": "TRK-2205",
      "make": "Kenworth",
      "model": "T680",
      "year": 2024,
      "fuelTankCapacity": 150,
      "mpg": 6.8,
      "status": "ACTIVE"
    }
  ],
  "total": 2,
  "page": 1,
  "pageSize": 25
}

Filter Parameters

Parameter	Type	Description
`status`	string	Filter by `ACTIVE` or `INACTIVE`
`search`	string	Search by unit number, make, model, or VIN
`page`	number	Page number (default: 1)
`pageSize`	number	Results per page (default: 20, max: 100)

Get a Single Vehicle

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

JavaScript (fetch):

const response = await fetch(
  "https://sally-api.apps.appshore.in/api/v1/vehicles/veh_e5f6g7h8",
  {
    headers: { "X-API-Key": process.env.SALLY_API_KEY },
  }
);
 
const vehicle = await response.json();

Response:

{
  "id": "veh_e5f6g7h8",
  "unitNumber": "TRK-4821",
  "make": "Freightliner",
  "model": "Cascadia",
  "year": 2023,
  "vin": "3AKJHHDR7PSLA9274",
  "licensePlate": "IL-CDL-4821",
  "fuelTankCapacity": 150,
  "mpg": 6.2,
  "status": "ACTIVE",
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-02-08T14:30:00Z"
}

Update a Vehicle

Update vehicle specifications. This is particularly useful when fuel efficiency changes over time or the vehicle undergoes modifications.

curl -X PUT https://sally-api.apps.appshore.in/api/v1/vehicles/veh_e5f6g7h8 \
  -H "X-API-Key: $SALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mpg": 6.0,
    "licensePlate": "IL-CDL-4821-R"
  }'

JavaScript (fetch):

const response = await fetch(
  "https://sally-api.apps.appshore.in/api/v1/vehicles/veh_e5f6g7h8",
  {
    method: "PUT",
    headers: {
      "X-API-Key": process.env.SALLY_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      mpg: 6.0,
      licensePlate: "IL-CDL-4821-R",
    }),
  }
);
 
const updated = await response.json();

Response:

{
  "id": "veh_e5f6g7h8",
  "unitNumber": "TRK-4821",
  "make": "Freightliner",
  "model": "Cascadia",
  "year": 2023,
  "vin": "3AKJHHDR7PSLA9274",
  "licensePlate": "IL-CDL-4821-R",
  "fuelTankCapacity": 150,
  "mpg": 6.0,
  "status": "ACTIVE",
  "updatedAt": "2026-02-10T15:00:00Z"
}

Delete (Deactivate) a Vehicle

Removing a vehicle sets its status to INACTIVE. It cannot be assigned to new routes but remains in the system for historical records.

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

JavaScript (fetch):

const response = await fetch(
  "https://sally-api.apps.appshore.in/api/v1/vehicles/veh_e5f6g7h8",
  {
    method: "DELETE",
    headers: { "X-API-Key": process.env.SALLY_API_KEY },
  }
);

Response:

{
  "id": "veh_e5f6g7h8",
  "unitNumber": "TRK-4821",
  "status": "INACTIVE",
  "deactivatedAt": "2026-02-10T16:00:00Z"
}

Vehicle Assignment to Routes

When planning a route, you reference the vehicle by its ID. SALLY reads the vehicle’s fuel specifications to determine:

Fuel range: Based on fuelTankCapacity and mpg
Fuel stop timing: When current fuel level (provided in route planning request) drops below a safe threshold
Fuel cost estimates: Based on gallons needed and current fuel prices along the route

Example route planning request that references a vehicle:

{
  "driverId": "drv_a1b2c3d4",
  "vehicleId": "veh_e5f6g7h8",
  "vehicleState": {
    "currentFuelGallons": 75,
    "fuelTankCapacity": 150,
    "mpg": 6.2
  },
  "stops": [...]
}

In this example, the vehicle has 75 gallons (50% full), giving it approximately 465 miles of range. If the route exceeds that distance, SALLY inserts a fuel stop.

Keeping MPG Accurate

Fuel efficiency varies based on load weight, terrain, weather, and driving style. Update the mpg value periodically to reflect real-world performance:

New vehicle: Use the manufacturer’s rated MPG as a starting point
After 10,000 miles: Calculate actual MPG from fuel receipts and odometer readings
Seasonal adjustment: Fuel efficiency may drop 5-10% in winter due to cold weather and road conditions
Loaded vs. empty: A loaded truck averaging 6.2 MPG may achieve 7.0+ MPG when running empty

More accurate MPG values lead to better fuel stop placement and more reliable route cost estimates.

Error Responses

404 Not Found

{
  "statusCode": 404,
  "message": "Vehicle with ID veh_invalid not found",
  "error": "Not Found"
}

400 Bad Request — Duplicate Unit Number

{
  "statusCode": 400,
  "message": "A vehicle with unit number TRK-4821 already exists",
  "error": "Bad Request"
}

Next Steps

Drivers API — Manage driver profiles
Loads API — Create shipment loads for route planning
Your First Route — Combine drivers, vehicles, and loads into a route