SAsamsara
Work Orders

Creates a work order.

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

post/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 is Closed or Cancelled and this field is not provided.

assetIdstring required

The ID of the asset. Either a Samsara ID or an external ID in key:value form, for example vin:1HGCM82633A004352.

assignedUserIdstring

The ID of the assigned mechanic.

categorystring

The category of the work order

completedAtTimestring date-time

The historical time the work order was completed, in RFC 3339 format. Is automatically set when the status is Closed or Completed and this field is not provided.

createdByUserIdstring

ID of the dashboard user to attribute as the work order creator for display and creator notifications. Does not change who is recorded as the API actor in the activity log. Must be a user in the organization. When omitted, defaults to the API token owner. Accepted only when the organization has the create-created-by feature enabled.

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.

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; the resolved Place must be linked to a maintenance site. 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. 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 is 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 initial user-selectable status of the work order. Defaults to Open when not provided. Estimate workflow statuses are system-managed and cannot be set directly. 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",
  "assetId": "12443",
  "assignedUserId": "1234",
  "attributes": [
    {
      "dateValues": [
        "2024-01-15",
        "2024-12-31"
      ],
      "id": "494123",
      "name": "Compliance/ELD",
      "numberValues": [
        867,
        5309
      ],
      "stringValues": [
        "HQ",
        "Leased"
      ]
    }
  ],
  "category": "PREVENTIVE",
  "completedAtTime": "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,
  "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.