GEgetmaintainx
Work Orders

Create or update work order by external ID

Changed on

Idempotent upsert keyed on the external ID in the path. If a work order has this external ID, it will be updated (and undeleted, if the work order was previously deleted). Otherwise, a new work order will be created with this external ID.

patch/workorders/external/{externalId}

Request

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

Path parameters

externalIdstring required

External ID of the work order

Query parameters

expandstring[]

To expand multiple fields: expand=assignees&expand=asset

skipWebhookboolean

Set skipWebhook=true, skipWebhook=1 or skipWebhook=yes to skip all webhooks upon successful operation on the endpoint. Learn more about webhooks

Headers

x-organization-idinteger

Required if using a multi organizations token

Request body

assetIdinteger nullable
categoriesstring[]

List of categories that identify the work order

descriptionstring nullable
dueDatestring date-time nullable

Date & time at which the work order is due

estimatedTimeinteger nullable

The estimated time taken in seconds to complete the work order

startDatestring date-time nullable

Date & time at which the work order will show up in the inbox<br />Only valid when <b>dueDate</b> is set

locationIdinteger nullable

Global ID of the location assigned to the work order

priority'NONE' | 'LOW' | 'MEDIUM' | 'HIGH'
procedureTemplateIdnumber nullable

ID of the procedure template to attach

titlestring
type'OTHER' | 'REACTIVE' | 'PREVENTIVE'

Valid types of Work Orders.

extraFieldsobject

Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Estimated Time Allotted")

vendorIdsnumber[]

Vendor IDs

isParentboolean

Whether the work order is a parent work order. A parent work order has only a subset of the standard work order fields. It also has fields that aren't included in a standard work order. <a href='https://help.getmaintainx.com/multi-asset-work-orders?utm_source=mx-api-docs&utm_medium=web&utm_campaign=multi-asset-work-orders&utm_id=maintainx' target='_blank'>Learn more</a><br />Mutually exclusive with parentId<br />Only applied when the work order is created. When updating an existing work order, the value must match the work order's current value.

parentIdinteger nullable

ID of the parent work order. If provided, the work order will be created as a sub-work order under this parent work order. Sub-work orders inherit most of their fields from the parent work order. <a href='https://help.getmaintainx.com/create-and-manage-sub-work-orders?utm_source=mx-api-docs&utm_medium=web&utm_campaign=create-and-manage-sub-work-orders&utm_id=maintainx' target='_blank'>Learn more</a><br />Mutually exclusive with isParent<br />Only applied when the work order is created. When updating an existing work order, the value must match the work order's current value.

Example request

{
  "assignees": [
    {
      "type": "USER"
    }
  ],
  "categories": [
    "Cleaning"
  ],
  "description": "A work order sample description",
  "dueDate": "2022-01-01T00:00:00.000Z",
  "estimatedTime": 3600,
  "externalData": {
    "popularErpSolutionId": "asd732da"
  },
  "startDate": "2022-01-01T00:00:00.000Z",
  "priority": "MEDIUM",
  "procedure": {
    "id": 1234,
    "title": "Control dashboard audit",
    "fields": [
      {
        "label": "Metal Parts: broken, loose, dented, rusty, missing",
        "type": "INSPECTION_CHECK",
        "choices": [
          "Partially"
        ],
        "urls": [
          {
            "label": "MaintainX Website",
            "link": "www.getmaintainx.com"
          }
        ],
        "meterId": 1,
        "index": 1
      }
    ]
  },
  "recurrenceInfo": {
    "automationMeterTrigger": {
      "newDueDateOffsetSeconds": 86400
    }
  },
  "extraFields": {
    "Estimated Time Allotted": "24 Hours"
  },
  "vendorIds": [
    1
  ],
  "partsUsed": [
    {
      "partId": 963,
      "quantityUsed": 120,
      "locationId": 852
    }
  ]
}

Response

Successfully updated work order

Example response

{
  "workOrder": {
    "assetId": 42,
    "attachments": [
      {
        "id": 12345,
        "mimeType": "image/png",
        "fileName": "image.png",
        "url": "http://example.com/image.png",
        "createdAt": "2022-01-01T00:00:00.000Z",
        "width": 220,
        "height": 100
      }
    ],
    "categories": [
      "Cleaning"
    ],
    "completedAt": "2022-01-01T00:00:00.000Z",
    "createdAt": "2022-01-01T00:00:00.000Z",
    "deletedAt": "2022-01-01T00:00:00.000Z",
    "description": "A work order sample description",
    "dueDate": "2022-01-01T00:00:00.000Z",
    "estimatedTime": 3600,
    "externalData": {
      "popularErpSolutionId": "asd732da"
    },
    "lastMessageSentAt": "2022-01-01T00:00:00.000Z",
    "startDate": "2022-01-01T00:00:00.000Z",
    "locationId": 611,
    "priority": "MEDIUM",
    "recurrenceInfo": {
      "automationMeterTrigger": {
        "newDueDateOffsetSeconds": 86400
      }
    },
    "thumbnail": {
      "id": 12345,
      "mimeType": "image/png",
      "fileName": "image.png",
      "url": "http://example.com/image.png",
      "createdAt": "2022-01-01T00:00:00.000Z",
      "width": 220,
      "height": 100
    },
    "updatedAt": "2022-01-01T00:00:00.000Z",
    "extraFields": {
      "Estimated Time Allotted": "24 Hours"
    },
    "vendorIds": [
      1
    ],
    "customerId": 128,
    "procedure": {
      "id": 1234,
      "templateIds": [
        1234,
        1235
      ],
      "title": "Control dashboard audit",
      "maxScore": 2,
      "score": 1,
      "fields": [
        {
          "id": 1234,
          "parentId": 1233,
          "procedureTemplateId": 1234,
          "procedureTemplateFieldId": 5678,
          "description": "Number of green lights",
          "type": "NUMBER",
          "label": "Number of green lights",
          "maxScore": 2,
          "score": 1,
          "value": {
            "text": "12",
            "attachment": {
              "id": 12345,
              "mimeType": "image/png",
              "fileName": "image.png",
              "url": "http://example.com/image.png",
              "createdAt": "2022-01-01T00:00:00.000Z",
              "width": 220,
              "height": 100
            },
            "attachments": [
              {
                "id": 12345,
                "mimeType": "image/png",
                "fileName": "image.png",
                "url": "http://example.com/image.png",
                "createdAt": "2022-01-01T00:00:00.000Z",
                "width": 220,
                "height": 100
              }
            ],
            "notes": {
              "text": "1 light bulb is burned out."
            }
          },
          "meter": {
            "id": 123
          }
        }
      ]
    },
    "externalId": "ext-workorder-001",
    "progress": {
      "openCount": 1,
      "inProgressCount": 1,
      "onHoldCount": 1,
      "doneCount": 1
    },
    "workOrderSummary": {
      "content": "Replaced the motor bearings and aligned the shaft.",
      "summary": "Motor bearing replacement and shaft alignment completed.",
      "authorId": 963
    }
  }
}

Changes