Drivers

GET /v1/analytics/drivers

Returns performance metrics for a specific driver or for every driver in your fleet. When driverID is omitted, returns a roster ordered by driverRank ascending (unranked drivers last).

Requires an API key sent as a Bearer token in the Authorization header.

Request

Query Parameters

Parameter	Type	Required	Description
driverID	string	Optional	Returns metrics for a single driver. Omit to return metrics for every driver in the fleet.

Example Request — single driver

curl "https://api.core.doorstep.ai/v1/analytics/drivers?driverID=drv_8812a" \
  -H "Authorization: Bearer $API_KEY"

Example Request — full fleet

curl "https://api.core.doorstep.ai/v1/analytics/drivers" \
  -H "Authorization: Bearer $API_KEY"

Response

200

Performance metrics for the requested driver or fleet.

Response Body — single driver

Field	Type	Description
driverID	string	Driver identifier.
sessionCount	integer	Distinct delivery sessions the driver has completed.
deliveryTypes	object	Count of completed sessions per delivery type, e.g. { "doorstep": 12, "curbside": 3 }.
timeMetrics	object	Fleet-wide percentile score (0–100, higher is better) for each timing metric. See Scoring methodology. Keys: totalTime, walkingTime, inBuildingTime, handoverTime, activeTime, idleTime. Any key is null if the driver has no comparable sessions for that metric.
onTimeRate	number or null	Fraction (0–1) of the driver's sessions with a handoverTime faster than the 75th percentile of other drivers at the same building. null if no comparable sessions.
driverScore	number or null	Overall performance score, 0–100. Equal to timeMetrics.handoverTime.
driverRank	integer or null	Driver's rank within the fleet by activeTime performance, 1 = best. null if the driver has no comparable activeTime sessions.
fleetSize	integer	Total number of distinct drivers with sessions on record.
regions	array of strings	CBSA (metro/micro area) names the driver has made dropoffs in.

Response Body — fleet (no driverID)

Returns a drivers array where each entry matches the single-driver shape above, ordered by driverRank ascending (drivers with a null rank are sorted last).

Field	Type	Description
drivers	array of objects	One entry per driver. Each entry matches the single-driver response shape.

Scoring methodology

A driver's raw session values are compared against other drivers' sessions at the same building to get a per-session percentile rank (a session is only comparable if at least one other driver has a session at that same building). Those percentile ranks are averaged, flipped so lower time = higher score, and shrunk toward a neutral 50 when the driver has few comparable sessions — so a couple of lucky/unlucky sessions can't swing the score as much as a large sample would. timeMetrics is then this shrunk score re-expressed as a percentile against every other driver in the fleet, so 100 means best-in-fleet for that metric and 50 means average.

onTimeRate and driverRank are computed the same way: against building peers for on-time rate, and fleet-wide by activeTime score for rank.

Example Response — single driver

{
  "driverID": "drv_8812a",
  "sessionCount": 47,
  "deliveryTypes": {
    "doorstep": 39,
    "curbside": 8
  },
  "timeMetrics": {
    "totalTime": 68,
    "walkingTime": 71,
    "inBuildingTime": 65,
    "handoverTime": 74,
    "activeTime": 69,
    "idleTime": null
  },
  "onTimeRate": 0.83,
  "driverScore": 74,
  "driverRank": 3,
  "fleetSize": 18,
  "regions": ["San Francisco-Oakland-Fremont, CA"]
}

Example Response — fleet

{
  "drivers": [
    {
      "driverID": "drv_2201c",
      "sessionCount": 61,
      "deliveryTypes": { "doorstep": 50, "curbside": 11 },
      "timeMetrics": {
        "totalTime": 82,
        "walkingTime": 79,
        "inBuildingTime": 84,
        "handoverTime": 88,
        "activeTime": 91,
        "idleTime": null
      },
      "onTimeRate": 0.92,
      "driverScore": 88,
      "driverRank": 1,
      "fleetSize": 18,
      "regions": ["San Francisco-Oakland-Fremont, CA"]
    },
    {
      "driverID": "drv_8812a",
      "sessionCount": 47,
      "deliveryTypes": { "doorstep": 39, "curbside": 8 },
      "timeMetrics": {
        "totalTime": 68,
        "walkingTime": 71,
        "inBuildingTime": 65,
        "handoverTime": 74,
        "activeTime": 69,
        "idleTime": null
      },
      "onTimeRate": 0.83,
      "driverScore": 74,
      "driverRank": 3,
      "fleetSize": 18,
      "regions": ["San Francisco-Oakland-Fremont, CA"]
    }
  ]
}

401

The API key is missing or invalid.

{
  "status": 401,
  "code": "unauthorized",
  "message": "Token Invalid"
}

404

No driver was found for the requested driverID, or the driver does not belong to your organization.

{
  "status": 404,
  "code": "not_found",
  "message": "Driver not found"
}

500

Something went wrong on our end. Try the request again later.

{
  "status": 500,
  "code": "internal_server_error",
  "message": "Internal Server Error"
}

Notes

• Driver data is scoped to your organization. You cannot query drivers belonging to another client.
• A metric is null whenever there isn't at least one other driver's session at the same building to compare against — small fleets or buildings visited by a single driver will see more null metrics.
• driverRank has no minimum fleet-size gate — with very few drivers, ranks are still returned but are less meaningful.

Common Applications

• Daily driver scorecards for operations managers
• Compare driver performance on equivalent routes
• Identify productivity gaps between top and bottom quartile drivers
• Flag drivers whose on-time rate is falling behind their peers at the same buildings