OpenAPI Specification
openapi: 3.0.0
info:
description: Welcome to the MaintainX API documentation!<br/><br/>You can use the MaintainX API to programmatically interact with all the entities in MaintainX. Use it to retrieve and manage data of Work Orders, Work Requests, Assets, and more!<br/><br/>To get started, in your MaintainX account go to <a href="https://app.getmaintainx.com/settings/integrations/apiKeys">"Settings > Integrations"</a> and click "+ New Key" button to generate a new Rest API key.<br/><br/><b>Missing something?</b><br/>Don't hesitate to reach out <a href="mailto:support@getmaintainx.com">support@getmaintainx.com</a><br/><br/>
version: '1'
title: MaintainX Asset Criticalities Work Orders API
contact:
url: https://www.getmaintainx.com/
name: Support
email: support@getmaintainx.com
x-logo:
url: https://maintainx-static.s3-us-west-2.amazonaws.com/img/default-org-logo.png
backgroundColor: '#FFFFFF'
altText: MaintainX logo
servers:
- url: https://api.getmaintainx.com/v1
description: Endpoint
security:
- Bearer: []
tags:
- name: Work Orders
description: Operations on Work Orders
x-traitTag: false
paths:
/workorders:
post:
summary: Create new work order
requestBody:
description: Work order to create
required: true
content:
application/json:
schema:
type: object
required:
- title
properties:
assetId:
nullable: true
type: integer
assignees:
type: array
description: Either the teamId, the userId or the user email address
items:
type: object
title: assignees
required:
- type
- id
properties:
type:
type: string
example: USER
enum:
- USER
- TEAM
id:
oneOf:
- type: integer
- type: string
estimatedTime:
type: integer
nullable: true
description: The estimated time taken in seconds to complete the work order
example: 3600
requesterId:
oneOf:
- type: integer
nullable: true
- type: string
description: ID or email of the user who requested the work order
workRequestId:
nullable: true
type: integer
description: ID of the Work Request that will be approved by the creation of this work order
workOrderTemplateId:
type: integer
nullable: true
description: 'ID of the Work Order Template that will be used to create this work order. Note that data from the payload will overwrite the Template data. Also, restrictions defined by the Template (EG: Required/Hidden/Read-Only fields) will apply.'
categories:
type: array
description: List of categories that identify the work order
items:
type: string
example: Cleaning
uniqueItems: true
description:
nullable: true
type: string
example: A work order sample description
dueDate:
type: string
format: date-time
nullable: true
description: Date & time at which the work order is due
example: '2022-01-01T00:00:00.000Z'
externalData:
description: Extra data that can be attached to the work order, for example to help reference to a matching record in an external system.
nullable: true
oneOf:
- type: object
example:
popularErpSolutionId: asd732da
- type: number
example: 732
- type: string
example: asd732da
isParent:
type: boolean
nullable: true
description: 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**
startDate:
type: string
format: date-time
nullable: true
description: Date & time at which the work order will show up in the inbox</br>Only valid when <b>dueDate</b> is set
example: '2022-01-01T00:00:00.000Z'
locationId:
nullable: true
type: integer
description: Global ID of the location assigned to the work order
priority:
type: string
example: MEDIUM
enum:
- NONE
- LOW
- MEDIUM
- HIGH
procedure:
type: object
nullable: true
required:
- title
- fields
properties:
id:
type: number
example: 1234
deprecated: true
description: You should favor 'procedureTemplateId' to attach a procedure template.
title:
type: string
description: Title of the procedure
example: Control dashboard audit
fields:
type: array
items:
type: object
required:
- type
- label
properties:
label:
type: string
example: 'Metal Parts: broken, loose, dented, rusty, missing'
type:
type: string
example: INSPECTION_CHECK
enum:
- NUMBER
- AMOUNT
- TEXT
- UNSUPPORTED
- HEADING
- FILE
- SIGNATURE
- MULTIPLE_CHOICE
- INSPECTION_CHECK
- YES_NO_NA
- CHECKBOX
- CHECKLIST
- METER
- DATE
- CYCLE_COUNT
description:
type: string
nullable: true
choices:
type: array
items:
example: Partially
type: string
urls:
type: array
items:
type: object
required:
- link
properties:
label:
type: string
description: Label of the url
example: MaintainX Website
link:
type: string
description: Link
example: www.getmaintainx.com
meterId:
type: number
example: 1
nullable: true
description: Id of the meter
isDateAndTime:
type: boolean
default: false
description: Indicate if a DATE field also contains the time
example: false
index:
type: number
example: 1
description: Order which the row is displayed
description: Steps of a procedure
procedureTemplateId:
type: number
nullable: true
description: ID of the procedure template to attach
repeatability:
type: object
nullable: true
example:
type: WEEKLY
interval: 3
days:
- MONDAY
- WEDNESDAY
- FRIDAY
oneOf:
- type: object
title: Daily
nullable: true
required:
- type
properties:
type:
type: string
pattern: DAILY
enum:
- DAILY
automationMeterTrigger:
type: object
description: Automation meter trigger configuration
properties:
automationTriggerInput:
type: object
properties:
conditions:
type: array
description: Conditions to trigger automation
items:
type: object
properties:
operator:
type: string
enum:
- increasedBy
- decreasedBy
description: Operator for the condition
value:
type: number
description: Value for the condition
required:
- operator
- value
meterId:
type: integer
description: ID of the meter to trigger the automation
required:
- meterId
- conditions
lastTriggerValue:
type: number
description: Last trigger value for the meter
newDueDateOffsetSeconds:
type: integer
description: Offset in seconds for new due date. If you want to set the due date to 2 days from now set this to 172800 - (24 * 60 * 60 * 2)
example: 86400
nullable: true
- type: object
title: Weekly
required:
- type
- days
nullable: true
properties:
type:
type: string
pattern: WEEKLY
enum:
- WEEKLY
interval:
type: integer
description: Number of weeks between events
minimum: 1
maximum: 52
default: 1
days:
type: array
description: Days of the week the event will occur
items:
type: string
enum:
- SUNDAY
- MONDAY
- TUESDAY
- WEDNESDAY
- THURSDAY
- FRIDAY
- SATURDAY
automationMeterTrigger:
type: object
description: Automation meter trigger configuration
properties:
automationTriggerInput:
type: object
properties:
conditions:
type: array
description: Conditions to trigger automation
items:
type: object
properties:
operator:
type: string
enum:
- increasedBy
- decreasedBy
description: Operator for the condition
value:
type: number
description: Value for the condition
required:
- operator
- value
meterId:
type: integer
description: ID of the meter to trigger the automation
required:
- meterId
- conditions
lastTriggerValue:
type: number
description: Last trigger value for the meter
newDueDateOffsetSeconds:
type: integer
description: Offset in seconds for new due date. If you want to set the due date to 2 days from now set this to 172800 - (24 * 60 * 60 * 2)
example: 86400
nullable: true
- type: object
title: Monthly
required:
- type
- day
nullable: true
properties:
type:
type: string
pattern: MONTHLY
enum:
- MONTHLY
interval:
type: integer
description: Number of months between events
minimum: 1
maximum: 24
default: 1
day:
type: integer
minimum: 1
maximum: 31
description: Day of the month the event will occur
automationMeterTrigger:
type: object
description: Automation meter trigger configuration
properties:
automationTriggerInput:
type: object
properties:
conditions:
type: array
description: Conditions to trigger automation
items:
type: object
properties:
operator:
type: string
enum:
- increasedBy
- decreasedBy
description: Operator for the condition
value:
type: number
description: Value for the condition
required:
- operator
- value
meterId:
type: integer
description: ID of the meter to trigger the automation
required:
- meterId
- conditions
lastTriggerValue:
type: number
description: Last trigger value for the meter
newDueDateOffsetSeconds:
type: integer
description: Offset in seconds for new due date. If you want to set the due date to 2 days from now set this to 172800 - (24 * 60 * 60 * 2)
example: 86400
nullable: true
- type: object
title: Yearly
required:
- type
nullable: true
properties:
type:
type: string
pattern: YEARLY
enum:
- YEARLY
interval:
type: integer
description: Number of years between events
minimum: 1
maximum: 1000
default: 1
automationMeterTrigger:
type: object
description: Automation meter trigger configuration
properties:
automationTriggerInput:
type: object
properties:
conditions:
type: array
description: Conditions to trigger automation
items:
type: object
properties:
operator:
type: string
enum:
- increasedBy
- decreasedBy
description: Operator for the condition
value:
type: number
description: Value for the condition
required:
- operator
- value
meterId:
type: integer
description: ID of the meter to trigger the automation
required:
- meterId
- conditions
lastTriggerValue:
type: number
description: Last trigger value for the meter
newDueDateOffsetSeconds:
type: integer
description: Offset in seconds for new due date. If you want to set the due date to 2 days from now set this to 172800 - (24 * 60 * 60 * 2)
example: 86400
nullable: true
- type: object
title: Periodically
required:
- type
nullable: true
properties:
type:
type: string
pattern: PERIODICALLY
enum:
- PERIODICALLY
interval:
type: integer
description: Number of seconds between events
minimum: 0
automationMeterTrigger:
type: object
description: Automation meter trigger configuration
properties:
automationTriggerInput:
type: object
properties:
conditions:
type: array
description: Conditions to trigger automation
items:
type: object
properties:
operator:
type: string
enum:
- increasedBy
- decreasedBy
description: Operator for the condition
value:
type: number
description: Value for the condition
required:
- operator
- value
meterId:
type: integer
description: ID of the meter to trigger the automation
required:
- meterId
- conditions
lastTriggerValue:
type: number
description: Last trigger value for the meter
newDueDateOffsetSeconds:
type: integer
description: Offset in seconds for new due date. If you want to set the due date to 2 days from now set this to 172800 - (24 * 60 * 60 * 2)
example: 86400
nullable: true
skipRestHook:
type: boolean
deprecated: true
description: When work order is created, will not trigger any rest hook that is subscribed
title:
type: string
type:
type: string
enum:
- OTHER
- REACTIVE
- PREVENTIVE
description: Valid types of Work Orders.
extraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Estimated Time Allotted")'
additionalProperties:
type: string
example:
Estimated Time Allotted: 24 Hours
vendorIds:
type: array
description: Vendor IDs
items:
type: number
example: 1
partsUsed:
type: array
description: Parts IDs and quantities used in this work order
items:
type: object
required:
- partId
- quantityUsed
properties:
partId:
type: integer
example: 963
description: Global ID of the part
quantityUsed:
type: integer
description: Quantity used in the work order.
example: 120
locationId:
type: integer
nullable: true
description: Global ID of the location of the part
example: 852
copyOnRecurring:
type: string
description: Indicates if the parts will be copied to the next work order in the chain (if applicable).
default: Default
enum:
- NoCopy
- Copy
- Default
parentId:
type: number
nullable: true
description: 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**
parameters:
- name: skipWebhook
in: query
schema:
type: boolean
description: Set skipWebhook=true to skip all webhooks upon successful work order creation.
- schema:
type: boolean
description: Set `skipWebhook=true`, `skipWebhook=1` or `skipWebhook=yes` to skip all webhooks upon successful operation on the endpoint. [Learn more about webhooks](#tag/Subscriptions-and-Webhooks)
name: skipWebhook
in: query
required: false
- schema:
type: integer
description: Required if using a multi organizations token
name: x-organization-id
in: header
required: false
example: '1'
responses:
'200':
description: Successfully created work order
content:
application/json:
schema:
type: object
required:
- id
properties:
id:
type: number
example: 159
'400':
description: OrganizationId was not provided
content:
application/json:
schema:
type: object
required:
- errors
example:
errors:
- error: Missing x-organization-id header.
properties:
errors:
type: array
items:
type: object
required:
- error
properties:
error:
type: string
fieldPath:
nullable: true
type: string
fieldValue:
nullable: true
oneOf:
- type: string
- type: number
- type: boolean
'401':
$ref: '#/components/responses/UnauthorizedError'
tags:
- Work Orders
get:
summary: List work orders
description: Endpoint used to list work order resources
parameters:
- name: cursor
in: query
schema:
description: Last pagination reference
type: string
- name: limit
in: query
schema:
description: max number of Work Orders returned
type: integer
minimum: 1
maximum: 200
default: 100
- name: title
schema:
type: string
description: To filter work orders by title
in: query
- name: assets
schema:
type: array
title: asset ID filters
description: 'To filter by multiple asset IDs: `assets=630&assets=634`'
items:
type: integer
in: query
- name: notAssets
schema:
type: array
title: asset ID filters
description: 'Filter work orders that have none of the provided assets.
To filter by multiple asset IDs: `notAssets=630¬Assets=634`'
items:
type: integer
in: query
- name: locations
schema:
type: array
title: location ID filters
description: 'To filter by multiple location IDs: `locations=193&locations=194&locations=195`'
items:
type: integer
in: query
- name: notLocations
schema:
type: array
title: location ID filters
description: 'Filter work orders that have none of the provided locations.
To filter by multiple location IDs: `notLocations=193¬Locations=194¬Locations=195`'
items:
type: integer
in: query
- name: parts
schema:
type: array
title: part ID filters
description: 'To filter by multiple part IDs: `parts=14677&parts=14687`'
items:
type: integer
in: query
- name: notParts
schema:
type: array
title: part ID filters
description: 'Filter work orders that have none of the provided parts.
To filter by multiple part IDs: `notParts=14677¬Parts=14687`'
items:
type: integer
in: query
- name: vendors
schema:
type: array
title: vendor ID filters
description: 'To filter by multiple vendor IDs: `vendors=7123&vendors=2234`'
items:
type: integer
in: query
- name: notVendors
schema:
type: array
title: vendor ID filters
description: 'Filter work orders that have none of the provided vendors.
To filter by multiple vendor IDs: `notVendors=7123¬Vendors=2234`'
items:
type: integer
in: query
- name: assignees
schema:
type: array
title: assignee ID filters
description: 'To filter by multiple assignee IDs: `assignees=23494&assignees=79808`'
items:
type: integer
in: query
- name: teams
schema:
type: array
title: team ID filters
description: 'To filter by multiple team IDs: `teams=112&teams=243`'
items:
type: integer
in: query
- name: categories
schema:
type: array
title: categories filters
description: 'To filter by multiple categories: `categories=123456&categories=Damage`'
items:
oneOf:
- type: string
description: Label of the category
example: Damage
- type: integer
description: Global ID of the category
example: 123
in: query
- name: notCategories
schema:
type: array
title: categories filters
description: 'Filter work orders that have none of the provided categories.
To filter by multiple categories: `notCategories=123456¬Categories=Damage`'
items:
oneOf:
- type: string
description: Label of the category
example: Damage
- type: integer
description: Global ID of the category
# --- truncated at 32 KB (616 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/maintainx/refs/heads/main/openapi/maintainx-work-orders-api-openapi.yml