Driversnote

Update one or many trips in a single call: classify them as business or personal (set the trip type and workplace/organisation), change vehicle, set a tag or comment, and/or mark them as reviewed. This is the efficient way to classify trips — one request instead of one per trip. Example — classify last week's pending trips as business at a workplace, based on the user's calendar: { "ids": ["<trip ids from list_trips>"], "tripType": "business", "organisationId": "<workplace id from list_organisations>", "markAsReviewed": true } Example — mark trips as personal: { "ids": ["..."], "tripType": "private", "markAsReviewed": true } Notes: - All listed trips receive the SAME values. To give trips different classifications, group them and make one call per group. - Find trip IDs (and their current classification / reviewStatus) with list_trips first. - `markAsReviewed: true` sets reviewStatus to 'done', which removes the trips from the user's 'needs review' list. - Only one tag can be applied per bulk call (`tagId`, requires `tagOrganisationId`); attach multiple tags per trip at creation with create_trip instead.

classify_trips

Create and save a mileage report for a period, vehicle and workplace. The report collects every matching trip, calculates distance and reimbursement at the workplace's rates, and appears in the user's report list with PDF and spreadsheet downloads. Use it when the user actually wants a report to keep, download or submit to their team — for 'what would it total?' questions use preview_report instead, which saves nothing. Recommended flow: preview_report with the same arguments first → check `warnings` → create_report → (team members) submit_report_to_team. Example: { "vehicleId": "<id>", "organisationId": "<id>", "startDate": "2026-03-01", "endDate": "2026-03-31" } Notes: - vehicleId/organisationId come from get_account_context; the inputs are identical to preview_report. - Check list_reports first if there is a risk the period is already reported: creating a second report over the same trips flags them as double-reported. - The returned `pdfUrl` is often null right after creation because the PDF is generated in the background — fetch it a little later with get_report_download_links. `excelUrl` is available immediately but requires a signed-in browser. - On the free plan the API refuses to create a report once the monthly trip limit is passed (preview_report's `warnings.hasPassedMonthlyLimit`). - Each call creates one report and costs one request of the 2,000/month quota.

create_report

Create a single trip (mileage record) — ideal for importing past trips from a spreadsheet, calendar or another system. Call once per trip. Example — import one spreadsheet row: { "startAt": "2026-03-04T08:30:00+01:00", "stopAt": "2026-03-04T09:05:00+01:00", "distance": 23400, "startLocationPlaceholder": "Home, Copenhagen", "stopLocationPlaceholder": "Client HQ, Roskilde", "tripType": "business", "vehicleId": "<id from list_vehicles>", "organisationId": "<id from list_organisations>", "comment": "Imported from March spreadsheet" } Notes: - `distance` is an integer in the vehicle's local base unit: meters in km countries (23400 = 23.4 km), miles in mile countries. Check via get_account_context first. - `vehicleId`, `organisationId` and `tripType` are required — look up vehicleId/organisationId with get_account_context, list_vehicles and list_organisations before importing. - The reimbursement amount is calculated automatically from the workplace's rates. - Each of start/stop location is required: pass either the saved-location ID (startLocationId/stopLocationId, see list_locations) or a free-text placeholder (startLocationPlaceholder/stopLocationPlaceholder) — ID preferred when a saved location matches. - Each call costs one request of the 2,000/month quota, so confirm the mapping on 1-2 trips before importing a large batch.

create_trip

Bootstrap tool: fetch a compact overview of the account behind the API key in ONE request — vehicles (with country, distance unit km/mi, and currency), organisations (what the end user calls "workplaces"), teams the user belongs to (with their own role and name on each team), and the available reimbursement methods. Call this FIRST in a session. It gives you every ID you need for the other tools (vehicleId, organisationId, teamId, countryId, vehicleTypeId) plus the units and currency to interpret distances and amounts — while spending only one request of the monthly quota. Returns flat arrays: `vehicles`, `organisations` (call these "workplaces" when talking to the user), `teams` and `reimbursementMethods`. Notes: - The API key impersonates one user; each team's `currentMemberRole` (e.g. 'admin', 'manager' or 'member') is the closest the public API gets to 'who am I'. - If a list may exceed the built-in page sizes (25 vehicles/organisations, 10 teams), follow up with the dedicated list tools.

get_account_context

Get the PDF and spreadsheet (XLSX) download links for one of the user's mileage reports — either by `reportId`, or by searching the user's reports when the ID is not at hand (by period and/or a text match on the report title, vehicle or workplace). Examples: - Known ID: { "reportId": "<id from list_reports or create_report>" } - 'Send me my March report as PDF': { "startDate": "2026-03-01", "endDate": "2026-03-31" } - 'The Q2 report for the van': { "startDate": "2026-04-01", "endDate": "2026-06-30", "search": "van" } How to use the links: - `report.pdfUrl` is a direct download link that works without signing in — share it as-is. It is null while the PDF is still being generated (typically right after create_report); wait a moment and call again. - `report.excelUrl` (the XLSX spreadsheet, https://www.driversnote.com/reports/<id>.xlsx) only works in a browser where the user is signed in to Driversnote, so tell the user to open it rather than trying to fetch it. Search behaviour: - A report matches when its period overlaps the given startDate–endDate and (if `search` is given) its title, name, vehicle name, license plate or workplace name contains the text (case-insensitive). - Exactly one match → returned as `report`. Several matches → `report` is null and up to 20 `candidates` are returned (each with its own links) so you can pick or ask the user. No match → an error; use list_reports to browse or create_report to make one. - The search scans newest reports first, at most 500 reports (5 requests of the monthly quota). Fetching by ID costs one request. - For a team member's report (as a manager), use list_team_reports — its rows carry `report.pdfUrl`.

get_report_download_links

One-request overview of how a team is doing in a period — for managers/admins. Answers 'how is my team doing this month?', 'who hasn't submitted their mileage report?', 'who has stopped tracking?', 'how much mileage has the team reported for Q1?' — all from a single call. Example: { "startDate": "2026-03-01", "endDate": "2026-03-31" } (teamId optional; defaults to the user's default team, see get_account_context) Prefer passing the teamId from get_account_context: the API's fallback 'default team' can differ from the teams listed there. What comes back: - `members`: counts by role plus `trackingSincePeriodStart` / `notTracking`. The API only exposes each member's latest trip date, so 'tracking' means the member created a trip on or after `startDate` (their latest trip date is not before it); 'not tracking' means their latest trip is older than the period or they never tracked. - `reports`: team reports whose period overlaps the range, counted by state (pending = awaiting approval, approved, processed = paid out, rejected, unsubmitted = withdrawn draft), plus `notSubmitted` = drivers (role 'member') without a submitted report for the period. - `submittedTotals`: distance and amount across pending/approved/processed reports, grouped by currency + distance unit (rejected and unsubmitted reports are excluded). Distance is in `distanceUnit` (km or mi), amount in `currency`. - `missingReports`: the drivers who have not submitted for the period — name and email for follow-up. - `memberActivity`: one row per member with latest trip date, tracking flag, reports submitted in the period, their distance/amount and whether a report is missing. - `complete` is false when the team has more than 100 members or reports in the period; totals then cover only the first 100 — use summarize_team_reports (pages everything) and list_team_members for exact figures. Notes: - Requires the API key's owner to be a manager or admin of the team; members only see their own row. - Managers/admins are not expected to submit reports, so they never appear in `missingReports`. - For the money view alone (per-member payout totals with every report listed) use summarize_team_reports; for the raw report rows use list_team_reports.

get_team_activity

List the user's organisations — what the end user and the Driversnote app call "workplaces". Returns name, address, whether reimbursement is calculated, and the reimbursement method in use. An organisation/workplace is what a business trip is driven FOR — assigning one to a trip is what classifies it as business for that employer/client. Use this to find the `organisationId` needed by create_trip, classify_trips, list_trips and create-report flows. When talking to the end user, call these "workplaces", not "organisations" — that's the term they know. Set `isArchived: false` to only list active organisations (default returns all). Each row flattens the reimbursement method into `reimbursementMethodId`/`reimbursementMethodName`/`reimbursementMethodDescription`.

list_organisations

List the user's own mileage reports (documents that collect trips for a period, used for reimbursement or tax documentation), newest data included: period, total distance and amount, currency, state, workplace, vehicle, and download URLs for PDF/Excel. Use this to answer 'what did my March report total?', to find a report's PDF link, or to check which periods already have a report before creating new ones. Notes: - These are the user's personal reports. For reports submitted by team members to a team the user manages, use list_team_reports instead. - `state` is one of: not_created, created, unsubmitted, pending, approved, rejected, processed (states beyond 'created' reflect team submission). - `totalDistance` is in the report's `distanceUnit`; `totalAmount` is in `currency`. - `pagination.total` is the number of reports across all pages; paginate with `first`/`after` using `pagination.nextCursor`.

list_reports

List the user's saved locations (named places like 'Home', 'Office', 'Client HQ' used on trips), with address and coordinates. Use this to find `startLocationId`/`stopLocationId` values for create_trip and classify_trips — linking trips to saved locations is better than free-text placeholders. Filter with `searchPhrase` to match a name or address substring.

list_locations

List the members of a team the user belongs to — name, email, role (member, manager or admin), license status and the date of each member's latest tracked trip. This is the tool for 'who is on my team?', for finding a member's `memberId` to filter list_team_reports / summarize_team_reports, or a manager's ID to use as `reviewerId` in submit_report_to_team. Notes: - `teamId` is optional and defaults to the user's default (first) team; find team IDs with get_account_context. The team itself is returned as `team`. Prefer passing the teamId from get_account_context: the API's fallback 'default team' can differ from the teams listed there. - Filter by `role`: 'member' (drivers who submit reports), 'manager' or 'admin' (who approve them). - Email, license and activity fields (`userEmail`, `userHasLicense`, `userHasTeamLicense`, `userLatestTripCreatedAt`, `userHasPassedMonthlyLimit`) are only returned when the API key's owner is a manager/admin of the team (or for the owner's own row); otherwise they are null. - `userLatestTripCreatedAt` is the best available activity signal: null means the member has never tracked a trip. - For a period-based activity overview (who tracked, who has not submitted a report) use get_team_activity instead. - `pagination.total` is the member count across all pages; paginate with `first`/`after` using `pagination.nextCursor`.

list_team_members