Creates a work order.

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

POST /maintenance/work-orders

Creates a work order.

cURL

curl --request POST \
  --url https://api.samsara.com/maintenance/work-orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "assetId": "12443",
  "assignedUserId": "1234",
  "category": "PREVENTIVE",
  "description": "The vehicle is not starting.",
  "discount": {
    "basisPoints": 500
  },
  "dueAtTime": "2019-06-13T19:08:25Z",
  "engineHours": 91823,
  "invoiceNumber": "123456",
  "items": [
    {
      "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
      "type": "ISSUE"
    }
  ],
  "odometerMeters": 91823,
  "poNumber": "123456",
  "priority": "HIGH",
  "serviceTaskInstances": [
    {
      "serviceTaskId": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
      "status": "Unknown",
      "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
      "laborTimeMinutes": 60,
      "parts": [
        {
          "partId": "P0077",
          "quantity": 2.5,
          "costCentsOverride": 1000,
          "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7"
        }
      ]
    }
  ],
  "tax": {
    "basisPoints": 700
  },
  "vendorUuid": "5523a39f-42ef-4820-83d0-dfe73dbe7853"
}
'

200

{
  "data": {
    "assetId": "12443",
    "createdAtTime": "2019-06-13T19:08:25Z",
    "id": "5",
    "status": "OPEN",
    "updatedAtTime": "2019-06-13T19:08:25Z",
    "archivedAtTime": "2019-06-13T19:08:25Z",
    "assignedUserId": "1234",
    "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"
      }
    ],
    "category": "PREVENTIVE",
    "closingNotes": "Everything was fixed without issues.",
    "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,
    "poNumber": "123456",
    "priority": "HIGH",
    "serviceTaskInstances": [
      {
        "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
        "serviceTaskId": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
        "status": "Unknown",
        "laborHourlyCost": {
          "amount": "94.01",
          "currency": "usd"
        },
        "laborTimeMinutes": 60,
        "parts": [
          {
            "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
            "partId": "P0077",
            "quantity": 2.5,
            "costCentsOverride": 1000
          }
        ],
        "partsCost": {
          "amount": "94.01",
          "currency": "usd"
        }
      }
    ],
    "tax": {
      "basisPoints": 700,
      "money": {
        "amount": "94.01",
        "currency": "usd"
      }
    },
    "unallocatedLabor": {
      "cost": {
        "amount": "94.01",
        "currency": "usd"
      },
      "timeMinutes": 60
    },
    "vendorUuid": "5523a39f-42ef-4820-83d0-dfe73dbe7853"
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Work Order Request

assetId · string · required

The ID of the asset.

Example:

"12443"

assignedUserId · string

The ID of the assigned mechanic.

Example:

"1234"

category · string

The category of the work order

Example:

"PREVENTIVE"

description · string

A description of what needs to be fixed.

Example:

"The vehicle is not starting."

discount · object

How much a work order is discounted. Either money or basisPoints are specified.

Show child attributes

dueAtTime · string<date-time>

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

Example:

"2019-06-13T19:08:25Z"

engineHours · integer<int64>

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

Example:

91823

invoiceNumber · string

The invoice number for the work order.

Example:

"123456"

items · object[]

Items related to the work order.

Show child attributes

odometerMeters · integer<int64>

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

Example:

91823

poNumber · string

The purchase order number for the work order.

Example:

"123456"

priority · enum<string>

The priority of the work order Valid values: High, Low, Medium, Urgent

Available options: High, Low, Medium, Urgent

Example:

"HIGH"

serviceTaskInstances · object[]

Service Tasks for the work order.

Show child attributes

tax · object

How much tax is applied to a work order. Either money or basisPoints are specified. If not provided, the default tax rate will be used.

Show child attributes

vendorUuid · string

The vendor UUID for the work order.

Example:

"5523a39f-42ef-4820-83d0-dfe73dbe7853"

Response

200

application/json

OK response.

data · object · required

A work order object.

Show child attributes