SAsamsara
Work Orders

Updates a work order.

Updates a work order.

<b>Rate limit:</b> 100 requests/min (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).

To use this endpoint, select Write Work Orders under the Work Orders category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>

Submit Feedback: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.

patch/maintenance/work-orders

Request

  • Base URL
    https://api.samsara.com
  • Auth
    HTTP bearer

Request body

archivedAtTimestring 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.

assignedUserIdstring

The ID of the assigned mechanic.

categorystring

The category of the work order

closingNotesstring

Notes on the work order.

completedAtTimestring 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.

descriptionstring

A description of what needs to be fixed.

dueAtTimestring date-time

The due date of the work order in RFC 3339 format.

engineHoursinteger

The engine hours at the time of the work order. Will default to current asset reading if unset.

idstring required

The unique id of the work order.

invoiceNumberstring

The invoice number for the work order.

odometerMetersinteger

The odometer reading at the time of the work order. Will default to current asset reading if unset.

placeExternalIdstring

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.

placeIdstring

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.

poNumberstring

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

startedAtTimestring 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

vendorUuidstring

The vendor location UUID for the work order. Resolve the location via GET /fleet/maintenance/vendor-locations.

Example request

{
  "archivedAtTime": "2019-06-13T19:08:25Z",
  "assignedUserId": "1234",
  "attributes": [
    {
      "dateValues": [
        "2024-01-15",
        "2024-12-31"
      ],
      "id": "494123",
      "name": "Compliance/ELD",
      "numberValues": [
        867,
        5309
      ],
      "stringValues": [
        "HQ",
        "Leased"
      ]
    }
  ],
  "category": "PREVENTIVE",
  "closingNotes": "Everything was fixed without issues.",
  "completedAtTime": "2019-06-13T19:08:25Z",
  "description": "The vehicle is not starting.",
  "discount": {
    "basisPoints": 500,
    "money": {
      "amount": "94.01",
      "currency": "usd"
    }
  },
  "dueAtTime": "2019-06-13T19:08:25Z",
  "engineHours": 91823,
  "id": "5",
  "invoiceNumber": "123456",
  "items": [
    {
      "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
      "type": "ISSUE"
    }
  ],
  "odometerMeters": 91823,
  "placeExternalId": "erpId:STORE-442",
  "placeId": "123456",
  "poNumber": "123456",
  "priority": "HIGH",
  "serviceTaskInstances": [
    {
      "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
      "laborHourlyCost": {
        "amount": "94.01",
        "currency": "usd"
      },
      "laborTimeMinutes": 60,
      "notes": "Replaced gasket; will revisit next service.",
      "parts": [
        {
          "costCentsOverride": 1000,
          "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
          "partId": "P0077",
          "quantity": 2.5
        }
      ],
      "partsCost": {
        "amount": "94.01",
        "currency": "usd"
      },
      "serviceTaskId": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
      "status": "Unknown"
    }
  ],
  "startedAtTime": "2019-06-13T19:08:25Z",
  "status": "OPEN",
  "tax": {
    "basisPoints": 700,
    "money": {
      "amount": "94.01",
      "currency": "usd"
    }
  },
  "vendorUuid": "5523a39f-42ef-4820-83d0-dfe73dbe7853"
}

Response

OK response.

Example response

{
  "data": {
    "archivedAtTime": "2019-06-13T19:08:25Z",
    "assetId": "12443",
    "assignedUserId": "1234",
    "assignees": [
      {
        "userId": "67890"
      }
    ],
    "attachments": [
      {
        "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
        "processingStatus": "processing",
        "url": "https://samsara-forms-submission-media-uploads.s3.us-west-2.amazonaws.com/123456",
        "urlExpiresAt": "2019-06-13T19:08:25Z"
      }
    ],
    "attributes": [
      {
        "dateValues": [
          "2024-01-15",
          "2024-12-31"
        ],
        "id": "494123",
        "name": "Compliance/ELD",
        "numberValues": [
          867,
          5309
        ],
        "stringValues": [
          "HQ",
          "Leased"
        ]
      }
    ],
    "category": "PREVENTIVE",
    "closingNotes": "Everything was fixed without issues.",
    "completedAtTime": "2019-06-13T19:08:25Z",
    "createdAtTime": "2019-06-13T19:08:25Z",
    "createdByUserId": "1234",
    "description": "The vehicle is not starting.",
    "discount": {
      "basisPoints": 500,
      "money": {
        "amount": "94.01",
        "currency": "usd"
      }
    },
    "dueAtTime": "2019-06-13T19:08:25Z",
    "engineHours": 91823,
    "id": "5",
    "invoiceNumber": "123456",
    "items": [
      {
        "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
        "type": "ISSUE"
      }
    ],
    "maintenanceSite": {
      "name": "LAX Service Bay 3",
      "placeExternalIds": {
        "Blanditiis laborum.": "Quis nesciunt excepturi voluptatem.",
        "Occaecati repellendus.": "Adipisci velit nihil.",
        "Placeat id.": "Totam ipsum quaerat."
      },
      "placeId": "123456"
    },
    "odometerMeters": 91823,
    "poNumber": "123456",
    "priority": "HIGH",
    "serviceTaskInstances": [
      {
        "assignees": [
          {
            "userId": "67890"
          }
        ],
        "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
        "laborHourlyCost": {
          "amount": "94.01",
          "currency": "usd"
        },
        "laborTimeMinutes": 60,
        "notes": "Replaced gasket; will revisit next service.",
        "parts": [
          {
            "costCentsOverride": 1000,
            "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
            "partId": "P0077",
            "quantity": 2.5
          }
        ],
        "partsCost": {
          "amount": "94.01",
          "currency": "usd"
        },
        "serviceTaskId": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
        "status": "Unknown",
        "subtasks": [
          {
            "form": {
              "formSubmissionUuid": "5523a39f-42ef-4820-83d0-dfe73dbe7853"
            },
            "procedure": {
              "name": "Inspect brakes"
            }
          }
        ]
      }
    ],
    "startedAtTime": "2019-06-13T19:08:25Z",
    "status": "OPEN",
    "tax": {
      "basisPoints": 700,
      "money": {
        "amount": "94.01",
        "currency": "usd"
      }
    },
    "unallocatedLabor": {
      "cost": {
        "amount": "94.01",
        "currency": "usd"
      },
      "timeMinutes": 60
    },
    "updatedAtTime": "2019-06-13T19:08:25Z",
    "vendorUuid": "5523a39f-42ef-4820-83d0-dfe73dbe7853",
    "workOrderTemplateIds": [
      "5523a39f-42ef-4820-83d0-dfe73dbe7853",
      "5523a39f-42ef-4820-83d0-dfe73dbe7853",
      "5523a39f-42ef-4820-83d0-dfe73dbe7853"
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.