Carpool Services

Carpool is Cartrack's shared vehicle booking system: drivers request a pool vehicle for a scheduled time window, a manager approves or declines the request, and the vehicle's actual pickup and return are tracked against that window. This page explains the read-only Carpool endpoints, with a focus on the booking lifecycle and the booking_status values on GET /carpool/bookings.

Which Endpoint Should I Use?

Use this mapping based on what you want to accomplish:

Goal	Endpoint
Search or list bookings by vehicle, driver, date range, or status	Get All Carpool Bookings
Get full detail for a single booking	Get Carpool Booking by Booking ID
List vehicles enabled for carpool use, their category, and setup completeness	Get All Carpool Enabled Vehicles
List the vehicle categories available for booking	Get All Carpool Vehicle Categories
List drivers registered for carpool use and their booking eligibility	Get All Registered Carpool Drivers

Booking Status Values

booking_status on a booking record is not something the requester or approver sets directly for most of its values. Most transitions are computed automatically by a backend process that re-evaluates every booking every couple of minutes against the current time and the vehicle's telemetry (ignition state, geofence entry/exit). A few values are set manually by a fleet manager acting in Fleetweb, not by that automatic process.

Value	Meaning
BOOKING_STATUS_FREE	Reserved value in the schema. No booking record returned by GET /carpool/bookings carries this status — it does not represent a state a real booking passes through.
BOOKING_STATUS_REQUESTED	A driver has submitted a booking request. Awaiting a manager's approval or decline decision.
BOOKING_STATUS_APPROVED	The booking is confirmed for its scheduled window — every department required to sign off has approved. This includes bookings approved automatically under a client's "Automatically approve new request" carpool setting: is_approved is true in that case too, but approved_by stays null because no manager actually took an approval action.
BOOKING_STATUS_DECLINED	A manager declined the request. Unlike approval, decline doesn't need consensus — a single department manager declining is enough to move the whole booking to DECLINED, even if other departments haven't responded yet.
BOOKING_STATUS_CANCELLED	The booking was cancelled — manually by the driver (only while still REQUESTED or APPROVED, not once picked up) or a manager (from any status), or automatically because the vehicle was never picked up. A REQUESTED, EXPIRING_APPROVAL, or APPROVED booking that passes its start_ts without being picked up is auto-cancelled once its client-configured grace period elapses (30 minutes after start_ts by default; some clients configure this relative to end_ts instead).
BOOKING_STATUS_ACTIVE	The vehicle has been picked up and the booking is in progress, before its scheduled end_ts. What counts as "picked up" is configurable per client — ignition on, leaving a pickup geofence, key collection from a smart locker, or a manual action in Fleetweb.
BOOKING_STATUS_ACTIVE_ALMOST_LATE	An early-warning state for an in-progress booking whose scheduled end_ts is approaching. Sits between ACTIVE and ACTIVE_LATE in the lifecycle — handle it as a valid value, but don't assume every booking passes through it before going late.
BOOKING_STATUS_ACTIVE_LATE	The scheduled end_ts has passed and the vehicle has not yet been returned.
BOOKING_STATUS_RETURNED	The vehicle was returned at or before the scheduled end_ts.
BOOKING_STATUS_RETURNED_LATE	The vehicle was returned after the scheduled end_ts.
BOOKING_STATUS_EXPIRING_APPROVAL	The booking is still awaiting a manager's decision (REQUESTED) and its scheduled start_ts is now less than one hour away. If no decision is made before start_ts, the booking is auto-cancelled.
BOOKING_STATUS_FORCE_TERMINATED	A fleet manager manually ended the booking from Fleetweb — only possible while the booking is ACTIVE, ACTIVE_ALMOST_LATE, or ACTIVE_LATE (the vehicle must currently be checked out). This is not an automatic transition; Fleetweb's own confirmation prompt frames it for cases like an accident, breakdown, or the vehicle being towed, not routine returns.

Developer Considerations

• The ACTIVE → ACTIVE_ALMOST_LATE → ACTIVE_LATE progression is graduated, not guaranteed — don't treat a booking going straight from ACTIVE to ACTIVE_LATE as unexpected or an error.
• Don't recompute lateness yourself by comparing returned_at to end_ts. The API's returned_at prefers a site-location (geofence) timestamp over the ignition timestamp when both exist, and it can differ slightly from the timestamp actually used to decide RETURNED vs RETURNED_LATE. Trust the booking_status value for that determination.

Setup Status: Vehicles and Drivers

Both GET /carpool/vehicles and GET /carpool/drivers return a setup_status field, but the two use different enums (SETUP_INCOMPLETE / READY for vehicles, SETUP_INCOMPLETE / ACTIVE_CARPOOL for drivers) and different completeness rules — don't assume they're interchangeable.

For vehicles, SETUP_INCOMPLETE means the vehicle is missing a department, category, default location, or license class. Which of those four are actually required is configurable per client: an account may not require all of them, so a vehicle can be READY without, for example, a department assigned, if that client hasn't turned department scoping on.

For drivers, ACTIVE_CARPOOL requires the driver to be enabled for carpool booking (can_book_carpool) and to have at least one of allow_system_auto_booking or allow_specific_vehicle_booking enabled, plus any department/license requirements the client has turned on. A driver with can_book_carpool: true but both booking methods disabled still shows as SETUP_INCOMPLETE.

Approval Fields: is_approved, approved_by, declined_by

approved_by and declined_by are null whenever no manager has taken an approval action on the booking — including auto-approved bookings. Use is_approved and booking_status to determine the booking's approval state; use approved_by/declined_by only to find out whether a manager was the one who decided it.