public-api-docs

Operations API Tasks, Damages, And Issues Guide

Overview

Tasks, damages, and issues are the main Operations API surfaces for operational work queues and support cases. Use these endpoints when building fleet operations tools, service-agent task boards, damage review workflows, issue/case handling, maintenance planning, or customer charge workflows related to fines, repairs, missing parts, or vehicle problems.

These concepts overlap but are not the same:

Concept	Use it for
Task	A work item assigned to a branch, user, role, vehicle, issue, damage, vehicle category, or customer.
Damage	A vehicle condition report with part, severity, state, photos/files, reporter, caused-by user, and related rental context.
Issue	A support or operational case that can link a booking, rental, vehicle, account, cost center, comments, files, damages, deposit, and invoice.

A common flow is:

1. A vehicle needs work, such as relocation, cleaning, inspection, or damage review.
2. An operator creates a task and assigns it to a category that describes the work area.
3. If the task or damage identifies a chargeable customer case, an issue is created.
4. The issue is used to document the case and, when appropriate, create and bill an invoice line item such as a speeding penalty, damage charge, fine, toll, or correction.

Related reference: Operations API

Operations API Guide

Vehicle Guide

Rental Guide

Customers And Groups Guide

Payments And Invoices Guide

Error Codes

---

Core Concepts

Tasks

Tasks are operational work items. A task has task data and a task object:

Part	Meaning
taskData	Title, description, priority, state, branch, assignment, category, files, timestamps, and tags/annotations.
taskObject	The entity the task is about, such as vehicle, issue, damage, vehicle category, or user.

Task states:

State	Meaning
NEW	Task exists and has not been started.
IN_PROGRESS	Someone is actively working on the task.
RECURRING	Task is part of a recurring task workflow.
COMPLETED	Task is finished.

Task priorities are LOW, NORMAL, HIGH, and SEVERE.

Custom task categories are managed through /task-categories. They are fully flexible and are one of the most important parts of the task model because they define the operator’s own work areas. For example, an operator can create categories such as relocation, cleaning, charging, inspection, repair, customer support, or damage review.

Task categories are also useful for operational reporting. A relocation task, for example, can be counted as work in the relocation area. createdAt shows when the work was created, updatedAt together with taskState shows when it was completed or last changed, and the category identifies which operational area the work belongs to.

The legacy category enum is deprecated; use categoryId for new tooling. If both legacy category and categoryId are provided, categoryId takes precedence.

Task Templates And Recurring Tasks

Task templates define reusable task setup. Recurring tasks create repeated work based on recurrence criteria such as time, kilometers, or rental count.

Use task templates and recurring tasks as the task automation layer. A template defines what should be created; a recurring task defines when or under which recurrence criteria the work should be created again.

Use recurring tasks for planned operational routines such as inspection, cleaning, charging, relocation checks, or maintenance cycles. Use one-time tasks for ad hoc work created from support, fleet, or damage workflows.

For automated task creation, keep the generated task category meaningful. The category is what later lets operators understand how much work was created and completed in each operational area.

Maintenance Service Context

Some operators also use the Wunder Mobility Maintenance Service for field-service execution. It is separate from the Operations API task endpoints, but it belongs to the same operational domain:

Surface	Role in the workflow
Operations API tasks	Operator-defined work queue, task categories, task templates, recurring tasks, and links to vehicles, damages, issues, users, and vehicle categories.
Maintenance Service	Tracks service-worker activity in the field, maintenance routes, service vehicles, route stops, stop items, and maintenance event metrics.

Maintenance Service records service-worker actions that originate from Core and the Service App. These events are useful for understanding what work happened in the field after tasks or routes were assigned.

Maintenance event types include:

Event	Meaning
APPROACH	Service worker starts working on a rental vehicle.
DEPLOY	Maintenance is complete and the vehicle is returned to the rental fleet.
CLOSE	Maintenance session ended but the vehicle was not returned to service.
VEHICLE_COMMAND	Service worker issued a vehicle command, such as unlock or open tailbox.
SERVICE_STATE_CHANGE	Service worker changed the vehicle service state.
BATTERY_SWAP	System detected a battery swap.

Use Operations API task categories to define what type of work was planned, such as relocation, charging, inspection, or damage review. Use Maintenance Service activity and metrics to understand what service workers actually did, when they approached or deployed vehicles, and how much maintenance activity happened per branch or service worker.

Damages

Damages are vehicle condition records. A damage can include the affected vehicle part, severity, state, files, vehicle/user position, branch, vehicle, previous/current rental, reporter, caused-by user, repair code, and linked issue.

Damage states:

State	Meaning
NEW	Damage was reported and still needs review.
APPROVED	Damage was reviewed and accepted as valid.
UNDER_REPAIR	Repair is in progress.
REPAIRED	Damage was repaired.
IGNORED	Damage report was ignored or dismissed.

Damage severity is MINOR, MEDIUM, HIGH, or CRITICAL. Severity must be set before approving a damage report.

Issues

Issues are support or operational cases. They are useful when the case needs a lifecycle, comments, files, related customer/group, vehicle, booking/rental, damages, deposit, or invoice.

Issue states:

State	Meaning
CREATED	Issue was opened.
WAITING	Issue is waiting for input, external action, or follow-up.
IN_REPAIR	Issue is being repaired or handled operationally.
CLOSED	Issue is resolved.

Issue categories include fines, accidents, missing vehicle parts, service/inspection needs, damaged vehicles, communication problems, parking problems, purchases, tolls, insurance, delivery, and corrections.

Use issues when a case has customer communication, files, comments, chargeable line items, or needs to be billed. Use tasks when the main need is assigning work. Use damages when the main record is the vehicle condition itself.

Issues are the object used when the operational case should become chargeable. For example, if a damage report or inspection task identifies a customer-caused damage, or if a speeding/parking/fine case needs to be charged to the user, create an issue and use the issue invoice endpoints to create and bill the charge.

Files And Evidence

Tasks can link files through taskData.files. Files must be uploaded first and the operator must have access to them. Issues can attach files to comments. Damages can also include files.

For tools, show file names and download links from the response, and handle missing file permissions separately from validation errors.

---

Common Operator Workflows

Build A Task Queue

Use GET /tasks.

Useful filters:

Filter	Use it for
branchId	Required branch scope.
includeChildBranches	Include child branch tasks.
assignedTo.firstLastName	Filter by assignee name.
searchText	Search task text.

For vehicle-specific task lists, use GET /vehicles/{id}/tasks.

For operational overview counts, use GET /kpis and KPI types such as VEHICLES_WITH_OPEN_TASK, VEHICLES_WITH_OPEN_DAMAGE, and VEHICLES_WITH_CRITICAL_NEW_DAMAGE.

Create Or Update Tasks

Use these endpoints:

Task	Endpoint
Create task	POST /tasks
Get task	GET /tasks/{id}
Update task	PATCH /tasks/{id}
Delete task	DELETE /tasks/{id}
Complete tasks in bulk	PATCH /tasks/complete
Update task tags	PUT /tasks/{id}/tags

When creating or updating tasks:

• Provide a branchId through taskData.
• Use categoryId for custom categories instead of the deprecated legacy category enum.
• Link the task to the relevant object through taskObject, such as vehicleId, issueId, damageId, guserId, or vehicleCategoryId.
• Pre-upload files and pass file IDs in taskData.files.
• Re-fetch the task after updates because linked file and category information is returned in enriched form.

Create Tasks For Vehicles In Bulk

Use POST /vehicles/tasks/bulk-create for creating the same task across multiple vehicles.

The response includes successes and failures per vehicle and may return partial success. Tools should show which vehicles received the task and which failed.

Avoid the deprecated POST /tasks?forAllVehiclesByBranch=true endpoint for new tooling.

Manage Task Categories

Use task categories for operator-specific work classification and operational analytics. Categories are flexible, so operators can define the work areas that matter to their operations. Common examples are relocation, charging, cleaning, inspection, repair, damage review, or customer support.

Task	Endpoint
List categories	GET /task-categories
Create category	POST /task-categories
Get category	GET /task-categories/{id}
Update category	PATCH /task-categories/{id}
Delete category	DELETE /task-categories/{id}

Categories cannot be deleted while they are in use by tasks or recurring tasks. Category names must contain only letters, numbers, and spaces, with at least one letter or number.

For reporting, combine category, state, and timestamps:

Field	Use it for
categoryId / categoryInfo	Identify the operational work area.
createdAt	Measure when work entered the queue.
updatedAt	Measure the last state change, including completion when the task is completed.
taskState	Distinguish open, in-progress, recurring, and completed work.
assignedTo	Attribute work to an operator or service agent.
branchId	Attribute work to a branch or region.

For example, to understand relocation work, create and use a relocation task category, then count tasks in that category by creation time and completion time.

Manage Task Templates And Recurring Tasks

Use these endpoints:

Task	Endpoint
List task templates	GET /tasks/templates
Create task template	POST /tasks/templates
Get task template	GET /tasks/templates/{id}
Update task template	PATCH /tasks/templates/{id}
Delete task template	DELETE /tasks/templates/{id}
List recurring tasks	GET /tasks/recurring
Create recurring task	POST /tasks/recurring
Get recurring task	GET /tasks/recurring/{id}
Update recurring task	PATCH /tasks/recurring/{id}
Delete recurring task	DELETE /tasks/recurring/{id}

Recurring task updates and deletes can affect child tasks. Use closeChildren, closeRecurringChildren, children, and includeRecurringChildren deliberately and show the impact before submitting changes.

Use Maintenance Service For Field Execution Context

Use Maintenance Service when the tool needs service-worker execution data rather than task configuration.

Maintenance Service endpoints are separate from the Operations API reference. They are commonly used by Dashboard/Fleet Manager and Service App workflows:

Workflow	Maintenance Service endpoint
Branch maintenance metrics	GET /api/vehicle-maintenance-log/branch/{branchId}
Branch battery-swap metrics	GET /api/vehicle-maintenance-log/branch/{branchId}/battery-swaps
Service-worker maintenance metrics	GET /api/vehicle-maintenance-log/user/{userAuthId}
Service-worker event details	GET /api/vehicle-maintenance-log/user/{userAuthId}/details
Service-worker battery-swap metrics	GET /api/vehicle-maintenance-log/user/{userAuthId}/battery-swaps
Latest active service workers in branch	GET /api/vehicle-maintenance-log/branch/{branchId}/latest-activities
Vehicle currently approached by service worker	GET /api/vehicle-maintenance-log/user/{userAuthId}/approached-vehicle
Route management	GET/POST/PATCH /api/routes and GET /api/routes/my
Route actions	POST /api/routes/{routeId}/action, /stop-action, /stop-item-action
Service vehicles	GET/POST/PATCH/DELETE /api/vehicles

Maintenance metrics endpoints use a time range and interval, similar to task completion metrics:

Parameter	Meaning
startDate / endDate	Time window for the metric.
interval	Bucket size such as hour/day/week/month, depending on the endpoint enum.
userTimezone	Optional timezone for grouping results. Defaults to UTC when omitted or invalid.

Use this data together with Operations API tasks when a tool needs to answer questions such as:

• Which relocation tasks were created and completed?
• Which service worker approached or deployed vehicles in that branch?
• How many battery swaps happened in the same period?
• Did a service worker leave a vehicle in an active approach state?
• Which route or service vehicle was used for field work?

Review Completed Task Metrics

Use:

Metric	Endpoint
Completed tasks by branch	GET /tasks/branch/{branchId}/completed-tasks
Completed tasks by user	GET /tasks/user/{userAuthId}/completed-tasks

Both endpoints require startDate, endDate, and interval. The interval can be HOUR, DAY, WEEK, or MONTH. Use userTimezone to align buckets with the operator’s reporting timezone.

Review And Manage Damages

Use these endpoints:

Task	Endpoint
List damages	GET /damages
Create damage	POST /damages
Get damage	GET /damages/{id}
Update damage	PATCH /damages/{id}
List damages for vehicle	GET /vehicles/{id}/damages

Useful list filters:

Filter	Use it for
branchId	Required branch scope.
includeChildBranches	Include child branch damages. Defaults to true.
activeFirst	Prioritize active/open damages.
createdBySearchText	Search who created the report.
reportedBySearchText	Search who reported the damage.
causedBySearchText	Search who caused the damage.
searchText	General damage search.

For review workflows, show reporter, caused-by user, previous/current rental, severity, files, linked issue, and vehicle details together. If approving a damage, require severity first.

For operator UI workflows, the Dashboard Health Scanner is the main review surface for vehicle damages. Core notification flows can deep-link operators to the Health Scanner damage view, typically under /v2/health-scanner/damages, with the active branch, vehicle, and damage context encoded in the URL. This is not a separate public Operations API endpoint; it is the Dashboard review interface that sits on top of the damage and vehicle data.

If a damage needs follow-up work, create a task linked to the damage via taskObject.damageId. If the damage should be charged to a user or business account, create an issue linked to the relevant rental, booking, vehicle, account, and damage context, then use the issue invoice workflow.

Build An Issue Queue

Use GET /issues.

Useful filters:

Filter	Use it for
branchId	Required branch scope.
includeChildBranches	Include child branch issues.
searchText	Search issue ID, title, or category name.

Use GET /issues/{id} for the issue detail view, including comments, linked invoice, linked damages, affected user/group, vehicle, rental, deposit, owner, and creator/updater metadata.

Create Or Update Issues

Use these endpoints:

Task	Endpoint
Create issue	POST /issues
Get issue	GET /issues/{id}
Update issue	PATCH /issues/{id}
Add comment	POST /issues/{id}/comments
Add file to comment	POST /issues/comments/{commentId}/file
Get files for comment	GET /issues/comments/{entityId}/files

When creating an issue:

• Use bookingId when the issue is related to a booking; do not combine it with rentalId.
• Use rentalId when the issue is related to a rental; do not combine it with bookingId.
• If bookingId or rentalId is set, vehicleId, branchId, accountId, and costCenterId are derived/ignored where applicable.
• Use vehicleId plus optional accountId when the case is about a vehicle and a specific customer or business account.
• Use accountId plus branchId when the case is about a customer or business account without a vehicle.
• Use costCenterId only with accountId.

Invoice A Charge From An Issue

Use issue invoice endpoints when an issue creates a customer or business-account charge, such as a fine, toll, repair cost, missing part, or correction.

Task	Endpoint
Create issue invoice	POST /issues/{id}/create-invoice
Add invoice line item	POST /issues/{id}/invoice/add
Bill issue invoice	POST /issues/{id}/invoice/bill

These endpoints connect issue handling to invoice workflows. This is the recommended path for turning an operational case into a customer charge, such as a damage charge or speeding penalty. For general invoice handling and refunds, see the Payments And Invoices Guide.

---

Most Relevant APIs

Area	Endpoint
Tasks	GET/POST /tasks, GET/PATCH/DELETE /tasks/{id}
Bulk complete tasks	PATCH /tasks/complete
Vehicle tasks	GET /vehicles/{id}/tasks, POST /vehicles/tasks/bulk-create
Task tags	PUT /tasks/{id}/tags
Task templates	GET/POST /tasks/templates, GET/PATCH/DELETE /tasks/templates/{id}
Recurring tasks	GET/POST /tasks/recurring, GET/PATCH/DELETE /tasks/recurring/{id}
Task categories	GET/POST /task-categories, GET/PATCH/DELETE /task-categories/{id}
Task metrics	GET /tasks/branch/{branchId}/completed-tasks, GET /tasks/user/{userAuthId}/completed-tasks
Maintenance Service metrics	GET /api/vehicle-maintenance-log/... on Maintenance Service
Maintenance routes/service vehicles	GET/POST/PATCH /api/routes, route action endpoints, GET/POST/PATCH/DELETE /api/vehicles on Maintenance Service
Damages	GET/POST /damages, GET/PATCH /damages/{id}
Vehicle damages	GET /vehicles/{id}/damages
Health Scanner damage review	Dashboard UI: /v2/health-scanner/damages
Issues	GET/POST /issues, GET/PATCH /issues/{id}
Issue comments/files	POST /issues/{id}/comments, POST /issues/comments/{commentId}/file, GET /issues/comments/{entityId}/files
Issue invoicing	POST /issues/{id}/create-invoice, POST /issues/{id}/invoice/add, POST /issues/{id}/invoice/bill

---

Permissions And Settings

Tasks, damages, and issues are permission-gated and branch-scoped. A user may be able to view vehicles but not create tasks, approve damages, view issue invoices, or bill an issue.

Common permission considerations:

Workflow	Permission consideration
Task list	TASK_LIST and branch access.
Task create/update/delete	TASK_CREATE, TASK_UPDATE, or TASK_DELETE.
Task file linking	Task permission plus file access permission.
Task categories/templates/recurring tasks	Task administration permissions.
Task analytics by category	Task list/metrics permissions and branch access.
Damage review	Damage read/write permissions plus branch/vehicle access.
Issue queue	Issue read permission for the branch.
Issue comments/files	Issue update/comment permission plus file access.
Issue invoicing	Issue permission plus invoice/finance permissions.
KPI queues	KPI/analytics visibility for task and damage KPI types.

Settings and configuration that can affect this domain include:

Area	Why it matters
Task category setup	Controls which categories are available for custom task workflows.
Maintenance Service roles	Maintenance Service uses roles such as maintenance:fleet-manager and maintenance:service-worker for route, user, service vehicle, and activity workflows.
Vehicle category settings	Can influence maintenance actions, task creation patterns, and vehicle operational behavior.
Damage configuration	Can influence severity workflows and whether damage states affect fleet availability.
Issue/invoice settings	Control whether issue charges can be invoiced and how line items are created/billed.
Role and branch configuration	Controls who can see or modify work queues in each branch.

Use GET /settings only when your tool knows the relevant DASHBOARD or SHARED setting keys. Use /settings-management for administrative settings discovery and configuration.

---

Implementation Notes For Custom Tools

• Choose the right object: task for assigned work, damage for vehicle condition, issue for support/case lifecycle.
• Use categoryId for task categories in new tooling; treat legacy category as backwards compatibility.
• Treat task categories as the operator’s work-area taxonomy and preserve them carefully because they drive operational reporting.
• For work reporting, combine task category with createdAt, updatedAt, taskState, assignee, and branch.
• Use Maintenance Service metrics and event details when you need proof of field execution, service-worker activity, route progress, or battery-swap activity.
• Keep the distinction clear: Operations API tasks describe planned or assigned work; Maintenance Service events describe maintenance actions that happened in the field.
• Link damage follow-up work to tasks through taskObject.damageId.
• Reference the Dashboard Health Scanner for operator damage review experiences; use the Operations API damage endpoints for programmatic access.
• Use issues, not tasks alone, when the case should result in a charge to the user or business account.
• Handle partial success from vehicle bulk task creation.
• Pre-upload files before linking them to tasks or issue comments.
• Show branch, vehicle, assignee, priority, state, category, and linked object in task lists.
• Require severity before allowing damage approval.
• Re-fetch vehicles after high-severity damage or open-task updates if vehicle availability or service state may change.
• Show issue links to booking, rental, vehicle, account, cost center, deposit, damages, and invoice in one detail view.
• Treat issue invoice actions as finance actions and require confirmation before billing.
• Avoid deprecated POST /tasks?forAllVehiclesByBranch=true in new tooling.
• Use Data Exports or the data warehouse for recurring analytical reporting instead of polling tasks/damages/issues at scale.

---

Review Notes

The following product decisions are reflected in this guide:

• Tasks, damages, and issues are documented as separate but connected operational concepts.
• Custom task categories are preferred over the deprecated legacy task category enum.
• Task categories are documented as a flexible operator-defined taxonomy for measuring work by operational area.
• Maintenance Service is documented as the field-execution and service-worker activity context that can be used alongside Operations API tasks.
• Maintenance Service route, service vehicle, and maintenance log endpoints are referenced separately from the Operations API reference.
• Dashboard Health Scanner is referenced as the operator damage-review UI rather than as a public API endpoint.
• Damage-to-task-to-issue workflows are documented for follow-up work and customer charges.
• Damage severity is documented as required before approval.
• Issues are documented as the case object for comments, files, chargeable line items, penalties, damage charges, and invoice workflows.
• Vehicle bulk task creation is preferred over the deprecated branch-wide task creation endpoint.