--- title: "Updates a work order." method: PATCH path: "/maintenance/work-orders" tags: ["Work Orders"] --- # Updates a work order. `PATCH /maintenance/work-orders` ## Request - Base URL: `https://api.samsara.com` - URL: `https://api.samsara.com/maintenance/work-orders` - Auth: HTTP bearer Updates a work order. Rate limit: 100 requests/min (learn more about rate limits here). To use this endpoint, select **Write Work Orders** under the Work Orders category when creating or editing an API token. Learn More. **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our API feedback form. If you encountered an issue or noticed inaccuracies in the API documentation, please submit a case to our support team. ## Request body - WorkOrdersPatchWorkOrdersRequestBody: Work Order Request. - `archivedAtTime` string, date-time: The historical time the work order was archived (closed or cancelled), in RFC 3339 format. Is automatically set when the status changes to Closed or Cancelled and this field is not provided. - `assignedUserId` string: The ID of the assigned mechanic. - `attributes` GoaAttributeTinyRequestBody[]: A list of custom fields (attributes) to assign to the work order. If provided, this replaces the work order's entire set of attribute associations with exactly this list; omit this field to leave existing attribute associations unchanged, or pass an empty array to clear them. Each entry requires the attribute `id`. Use `stringValues` for text, single-select, and multi-select attributes, `numberValues` for number attributes, and `dateValues` (YYYY-MM-DD) for date attributes. For single-select and multi-select attributes, send the text of a defined option. The request is rejected if any attribute or value is invalid. Only available for organizations with work order custom fields enabled. - `dateValues` string[]: List of date values associated with the attribute (RFC 3339 full-date format: YYYY-MM-DD). - `id` string: Id of the attribute - `name` string: Name of the attribute - `numberValues` number[]: List of number values associated with the attribute - `stringValues` string[]: List of string values associated with the attribute. - `category` string: The category of the work order - `closingNotes` string: Notes on the work order. - `completedAtTime` string, date-time: The time the work order was completed in RFC 3339 format. Is automatically set when the status changes and this field is not provided. - `description` string: A description of what needs to be fixed. - `discount` WorkOrderDiscountObjectRequestBody: How much a work order is discounted. Either money or basisPoints are specified. - `basisPoints` integer: The discount in basis points. 100 basis points = 1%. - `money` WorkOrderMoneyObjectRequestBody: A specified amount of money. - `amount` string, required: Amount of the currency. - `currency` 'usd', required: Type of the currency. We currently only support usd. Valid values: `usd` - `dueAtTime` string, date-time: The due date of the work order in RFC 3339 format. - `engineHours` integer: The engine hours at the time of the work order. Will default to current asset reading if unset. - `id` string, required: The unique id of the work order. - `invoiceNumber` string: The invoice number for the work order. - `items` WorkOrderItemObjectRequestBody[]: Items related to the work order. - `id` string, required: ID of the item. - `type` 'DVIR' | 'FAULT' | 'FORM' | 'ISSUE' | 'ITEM_TYPE_UNSPECIFIED' | 'MAINTENANCE_PREDICTION_EVENT' | 'SCHEDULED_MAINTENANCE', required: The type of item. Valid values: `DVIR`, `FAULT`, `FORM`, `ISSUE`, `ITEM_TYPE_UNSPECIFIED`, `MAINTENANCE_PREDICTION_EVENT`, `SCHEDULED_MAINTENANCE` - `odometerMeters` integer: The odometer reading at the time of the work order. Will default to current asset reading if unset. - `placeExternalId` string: External ID (`key:value`) of the Place where the work is performed. Resolved against the organization's external IDs for places. Send an empty string to clear the maintenance site on the work order. Mutually exclusive with `placeId`. - `placeId` string: ID of the Place where the work is performed. Must reference a Place returned by the Places API that is linked to a maintenance site in the organization. Send an empty string to clear the maintenance site on the work order. Mutually exclusive with `placeExternalId`. - `poNumber` string: The purchase order number for the work order. - `priority` 'High' | 'Low' | 'Medium' | 'Urgent': The priority of the work order Valid values: `High`, `Low`, `Medium`, `Urgent` - `serviceTaskInstances` ServiceTaskInstanceInputObjectRequestBody[]: Service Tasks for the work order. - `id` string: ID of the service task instance. Only set if updating an existing service task instance. - `laborHourlyCost` WorkOrderMoneyObjectRequestBody: A specified amount of money. - `amount` string, required: Amount of the currency. - `currency` 'usd', required: Type of the currency. We currently only support usd. Valid values: `usd` - `laborTimeMinutes` integer: The time of labor needed - `notes` string: Free-form technician notes for the service task. - `parts` PartInstanceInputObjectRequestBody[]: Parts for the service task. - `costCentsOverride` integer: The cost of one unit of the part in cents. If not provided, the part defined cost will be used. - `id` string: ID of the part instance. Only set if updating an existing part instance. - `partId` string, required: ID of the part definition. - `quantity` number, double, required: The quantity of the part in the parts pre defined unit of measure. - `partsCost` WorkOrderMoneyObjectRequestBody: A specified amount of money. - `amount` string, required: Amount of the currency. - `currency` 'usd', required: Type of the currency. We currently only support usd. Valid values: `usd` - `serviceTaskId` string, required: ID of the service task. - `status` 'Unknown' | 'Open' | 'In Progress' | 'On Hold' | 'Completed', required: The status of the service task. Valid values: `Unknown`, `Open`, `In Progress`, `On Hold`, `Completed` - `startedAtTime` string, date-time: The historical time work started on the work order, in RFC 3339 format. Is automatically set when the status changes to an in-progress status and this field is not provided. - `status` 'Assigned' | 'Cancelled' | 'Closed' | 'Completed' | 'Estimate' | 'In Progress' | 'On Hold' | 'Open' | 'Pending Approval' | 'Pending Parts' | 'Planning': The user-selectable status of the work order. Estimate workflow statuses are system-managed; use the estimate API for approval and award actions. Valid values: `Assigned`, `Cancelled`, `Closed`, `Completed`, `Estimate`, `In Progress`, `On Hold`, `Open`, `Pending Approval`, `Pending Parts`, `Planning` - `tax` WorkOrderTaxObjectRequestBody: How much tax is applied to a work order. Either money or basisPoints are specified. - `basisPoints` integer: The tax in basis points. 100 basis points = 1%. - `money` WorkOrderMoneyObjectRequestBody: A specified amount of money. - `amount` string, required: Amount of the currency. - `currency` 'usd', required: Type of the currency. We currently only support usd. Valid values: `usd` - `vendorUuid` string: The vendor location UUID for the work order. Resolve the location via GET /fleet/maintenance/vendor-locations. ## Response `200` OK response. - WorkOrdersPatchWorkOrdersResponseBody - `data` WorkOrderObjectResponseBody, required: A work order object. - `archivedAtTime` string, date-time: The time the work order was archived in RFC 3339 format. - `assetId` string, required: The ID of the asset. - `assignedUserId` string: The ID of the assigned mechanic. - `assignees` WorkOrderAssigneeObjectResponseBody[]: Dashboard users assigned to the work order. Only returned for organizations with multiple work order assignees enabled. Technicians backed only by a driver are not represented. - `userId` string, required: Samsara dashboard user ID of the assigned technician. Joinable against the public users API. - `attachments` WorkOrderAttachmentObjectResponseBody[]: Files attached to the work order. - `id` string, required: ID of the media record. - `processingStatus` 'unknown' | 'processing' | 'finished', required: Status of the media record. Valid values: `unknown`, `processing`, `finished` - `url` string, uri: URL containing a link to associated media content. Included if 'processingStatus' is 'finished'. - `urlExpiresAt` string, date-time: Expiration time of the media record 'url'. UTC timestamp in RFC 3339 format. - `attributes` GoaAttributeTinyResponseBody[]: Custom fields (attributes) set on the work order. Only returned when the request includes attributes. - `dateValues` string[]: List of date values associated with the attribute (RFC 3339 full-date format: YYYY-MM-DD). - `id` string: Id of the attribute - `name` string: Name of the attribute - `numberValues` number[]: List of number values associated with the attribute - `stringValues` string[]: List of string values associated with the attribute. - `category` string: The category of the work order - `closingNotes` string: Notes on the work order. - `completedAtTime` string, date-time: The time the work order was completed in RFC 3339 format. - `createdAtTime` string, date-time, required: The time the work order was created in RFC 3339 format. - `createdByUserId` string: The ID of the creator of the work order. On create, integrations may optionally set this to attribute Created-by UI and creator notifications to a dashboard user; the activity log still records the API token owner as the create actor when that override is used. - `description` string: A description of what needs to be fixed. - `discount` WorkOrderDiscountObjectResponseBody: How much a work order is discounted. Either money or basisPoints are specified. - `basisPoints` integer: The discount in basis points. 100 basis points = 1%. - `money` WorkOrderMoneyObjectResponseBody: A specified amount of money. - `amount` string, required: Amount of the currency. - `currency` 'usd', required: Type of the currency. We currently only support usd. Valid values: `usd` - `dueAtTime` string, date-time: The due date of the work order in RFC 3339 format. - `engineHours` integer: The engine hours at the time of the work order. - `id` string, required: The unique id of the work order. - `invoiceNumber` string: The invoice number for the work order. - `items` WorkOrderItemObjectResponseBody[]: Items related to the work order. - `id` string, required: ID of the item. - `type` 'DVIR' | 'FAULT' | 'FORM' | 'ISSUE' | 'ITEM_TYPE_UNSPECIFIED' | 'MAINTENANCE_PREDICTION_EVENT' | 'SCHEDULED_MAINTENANCE', required: The type of item. Valid values: `DVIR`, `FAULT`, `FORM`, `ISSUE`, `ITEM_TYPE_UNSPECIFIED`, `MAINTENANCE_PREDICTION_EVENT`, `SCHEDULED_MAINTENANCE` - `maintenanceSite` WorkOrderMaintenanceSiteObjectResponseBody: The maintenance site (inventory location) where the work is performed. - `name` string: Display name of the maintenance site. - `placeExternalIds` object: External identifiers for the linked Place. Populated only when the request sets `includeExternalIds=true`. - `placeId` string: ID of the Place linked to this maintenance site. Joinable against the Places API. Omitted if the maintenance site is not linked to a place. - `odometerMeters` integer: The odometer reading at the time of the work order. - `poNumber` string: The purchase order number for the work order. - `priority` 'High' | 'Low' | 'Medium' | 'Urgent': The priority of the work order Valid values: `High`, `Low`, `Medium`, `Urgent` - `serviceTaskInstances` ServiceTaskInstanceObjectResponseBody[]: Service Tasks for the work order. - `assignees` ServiceTaskAssigneeObjectResponseBody[]: Dashboard users assigned to the service task. Only returned for organizations with service task assignees enabled. Technicians backed only by a driver are not represented. - `userId` string, required: Samsara dashboard user ID of the assigned technician. Joinable against the public users API. - `id` string, required: ID of the service task instance. - `laborHourlyCost` WorkOrderMoneyObjectResponseBody: A specified amount of money. - `amount` string, required: Amount of the currency. - `currency` 'usd', required: Type of the currency. We currently only support usd. Valid values: `usd` - `laborTimeMinutes` integer: The time of labor needed - `notes` string: Free-form technician notes for the service task. - `parts` PartInstanceObjectResponseBody[]: Parts for the service task. - `costCentsOverride` integer: The cost of one unit of the part in cents. If not provided, the part defined cost will be used. - `id` string, required: ID of the part instance. - `partId` string, required: ID of the part definition. - `quantity` number, double, required: The quantity of the part in the parts pre defined unit of measure. - `partsCost` WorkOrderMoneyObjectResponseBody: A specified amount of money. - `amount` string, required: Amount of the currency. - `currency` 'usd', required: Type of the currency. We currently only support usd. Valid values: `usd` - `serviceTaskId` string, required: ID of the service task. - `status` 'Unknown' | 'Open' | 'In Progress' | 'On Hold' | 'Completed', required: The status of the service task. Valid values: `Unknown`, `Open`, `In Progress`, `On Hold`, `Completed` - `subtasks` ServiceTaskSubtaskObjectResponseBody[]: Subtasks for the service task. - `form` ServiceTaskFormSubtaskObjectResponseBody: A form subtask. - `formSubmissionUuid` string, required: The UUID of the form submission. - `procedure` ServiceTaskProcedureSubtaskObjectResponseBody: A procedure subtask. - `isCompleted` boolean, required: Whether the procedure is complete. - `name` string, required: The name of the procedure. - `startedAtTime` string, date-time: The time work started on the work order, in RFC 3339 format. - `status` 'Assigned' | 'Awaiting estimate approval' | 'Awaiting estimates' | 'Cancelled' | 'Closed' | 'Completed' | 'Estimate' | 'Estimate approval denied' | 'Estimate approved' | 'Estimates ready' | 'In Progress' | 'Needs Vendor Selection' | 'On Hold' | 'Open' | 'Pending Approval' | 'Pending Parts' | 'Planning', required: The status of the work order, including system-managed estimate workflow statuses. Valid values: `Assigned`, `Awaiting estimate approval`, `Awaiting estimates`, `Cancelled`, `Closed`, `Completed`, `Estimate`, `Estimate approval denied`, `Estimate approved`, `Estimates ready`, `In Progress`, `Needs Vendor Selection`, `On Hold`, `Open`, `Pending Approval`, `Pending Parts`, `Planning` - `tax` WorkOrderTaxObjectResponseBody: How much tax is applied to a work order. Either money or basisPoints are specified. - `basisPoints` integer: The tax in basis points. 100 basis points = 1%. - `money` WorkOrderMoneyObjectResponseBody: A specified amount of money. - `amount` string, required: Amount of the currency. - `currency` 'usd', required: Type of the currency. We currently only support usd. Valid values: `usd` - `unallocatedLabor` WorkOrderUnallocatedLaborObjectResponseBody: Unallocated labor from time entries not associated with any service task. - `cost` WorkOrderMoneyObjectResponseBody, required: A specified amount of money. - `amount` string, required: Amount of the currency. - `currency` 'usd', required: Type of the currency. We currently only support usd. Valid values: `usd` - `timeMinutes` integer, required: The total unallocated labor time in minutes. - `updatedAtTime` string, date-time, required: The time the work order was last updated in RFC 3339 format. - `vendorUuid` string: The vendor location UUID for the work order. Resolve the location via GET /fleet/maintenance/vendor-locations. - `workOrderTemplateIds` string[]: IDs of the work order template(s) this work order was created from. May include templates that have since been deleted. ## Other responses - `401`: Unauthorized response. - `404`: Not Found response. - `405`: Method Not Allowed response. - `413`: Content Too Large response. - `429`: Too Many Requests response. - `500`: Internal Server Error response. - `501`: Not Implemented response. - `502`: Bad Gateway response. - `503`: Service Unavailable response. - `504`: Gateway Timeout response. - `default`: Bad Request response. --- [API](https://skmtc.dev/samsara/apis/samsara-api.md) - [All operations](https://skmtc.dev/samsara/apis/samsara-api/llms.txt) - [OpenAPI document](https://skmtc.dev/samsara/apis/samsara-api/revisions/a9e35d4999be?raw)