Driver profiles

Every driver is a person with a driver profile. You will be able to attach licence and medical documents to the person, record pay figures, follow an advance balance, settle it when the driver leaves and understand how the on-shift flag controls tracking.

Before you start #

• You are an owner, a manager or a dispatcher (the fleet-manager group). Add the person first (see Steps, number 1).
• For documents, set your country preset so the licence and medical types exist. See documents-and-expiry.
• Fleet writes need the dispatch_fleet licence flag.

People and driver profiles #

A person holds the basic details: name, phone, email, employee number and notes. A driver profile adds the working details: whether the driver is active, the pay setup, the current asset and the on-shift flag. Several roles can sit on one person.

Steps #

1. Add a person with POST /people. Send name and, for a driver, a driver block with pay_mode (none, hourly, per_call or percent), pay_value (hundredths of a percent for percent, minor units of money for the others) and current_asset_id, the usual vehicle. Change them later with PATCH /people/<id>. A manager can also switch the shift with driver.on_shift; a shift needs a usual vehicle.
2. Add a licence or medical document to the person with POST /fleet/documents. Send person_id, a doc_type such as driver_licence, driving_licence or medical_card, and the dates. The document types listed for your country name the options.
3. Check which are expiring with GET /fleet/documents?person_id=<id>. Each shows an expiry state. The nightly job writes reminders at expiring and expired. See reminders-email-and-whatsapp.
4. Record a pay figure with POST /fleet/driver-pay. Send person_id, period_start, period_end (YYYY-MM-DD) and amount_cents, with optional currency and note. The currency defaults to the business currency. The answer gives the new record id.
5. Issue an advance with POST /fleet/advances and person_id, amount_cents and optionally kind, currency and recorded_on. Record repayments with kind: "repayment" and corrections with kind: "adjustment".
6. Read the ledger with GET /fleet/advances?person_id=<id>. The answer lists each entry, the balances by currency, needs_settlement and any warnings.
7. Before a driver leaves, call GET /people/<id>/leaving-check. It lists what stops it (a shift in progress, an open call) and any open advance. Then settle with POST /fleet/advances/settle and the person_id. One settlement entry per currency brings each balance to zero.

Leaving #

Sending active: false to PATCH /people/<id> runs the leaving check. A shift in progress or an open call stops it with leaving_check (409), and they cannot be confirmed away: end the shift and finish or reassign the call first. An open advance also stops it until you send confirm_leaving: true, which carries the balance knowingly and writes that to the audit log. When it goes through, the person and the driver profile become inactive and the person's sign-in ends. Nobody can switch off their own account.

Pay figures #

/fleet/driver-pay records the figure for one person and one period. Pop Dispatch holds the figure and sends it to your books as a driver pay event. Pop Dispatch records the amount you type and moves no money. Each person and period pair takes one figure.

Advance balance and the leaving warning #

The balance is the sum of the person's ledger entries: money handed over that is still unaccounted for. An advance adds. A repayment or an expense charged to the driver reduces it. Mistakes are corrected with an adjustment, since entries are never edited.

When a balance stays open, the ledger shows a warning in the form "<name> still holds an open advance of <amount>. Settle it before they leave." Settling records the closing of the balance. Settlement moves no money, so pay out or collect through your normal channel.

The on-shift flag and tracking #

The on-shift flag says the driver is working. Position tracking runs while the driver is on shift or a trip is active, and Pop Dispatch declines fixes uploaded outside both. The driver starts and ends a shift in the driver app. Starting a shift also records the truck the driver is using. See live-map-consent-and-gaps.

If something goes wrong #

• not_found (404): no such person.
• validation_failed (422) with fields: ["amount"]: an advance needs a positive amount and a repayment reduces the balance.
• validation_failed (422) with fields: ["period_end"]: the end cannot come before the start.
• validation_failed (422) with fields: ["kind"]: use advance, repayment or adjustment.
• conflict (409): a pay figure for that person and period exists already, or there is no open balance to settle.
• invalid_date (422): write dates as YYYY-MM-DD.
• feature_not_licensed (403) or licence_read_only (403): see fleet-overview-and-setup.