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 Requests 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 Requests
description: Operations on Work Requests
x-traitTag: false
paths:
/workrequests:
post:
summary: Create work request
requestBody:
description: Work request to create
required: true
content:
application/json:
schema:
type: object
required:
- title
properties:
description:
type: string
example: A forklift that needs to be reviewed for any potential problems
nullable: true
priority:
type: string
example: MEDIUM
enum:
- NONE
- LOW
- MEDIUM
- HIGH
title:
type: string
example: Forklift Preventive Maintenance Form
assetId:
type: number
format: integer
example: 843
nullable: true
locationId:
type: number
format: integer
example: 852
nullable: true
extraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Request Type")'
additionalProperties:
type: string
example:
Request Type: Water Leak
approverTeamId:
type: number
format: integer
example: 254
nullable: true
description: ID of the team that is reponsible for approving the request.
creatorContactInfo:
type: string
nullable: true
example: james@example.com
description: The creator's contact information associated with this work order request. Possible types are `EMAIL`, `PHONE`, and `OTHER`, which will be inferred from the string provided
responses:
'200':
description: Successfully created work request
content:
application/json:
schema:
type: object
required:
- id
properties:
id:
type: number
example: 963
description: Global ID of the work request
'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 Requests
parameters:
- 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'
get:
summary: List work requests
description: Endpoint used to list work request resources
parameters:
- name: cursor
in: query
schema:
description: Last pagination reference
type: string
- name: limit
in: query
schema:
description: max number of Work Requests returned
type: integer
minimum: 1
maximum: 200
default: 100
- name: title
schema:
type: string
description: To filter work orders by title or sequential ID
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: 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: priorities
schema:
type: array
title: priorities filters
description: 'To filter by multiple priorities: `priorities=LOW&priorities=MEDIUM`'
items:
type: string
example: MEDIUM
enum:
- NONE
- LOW
- MEDIUM
- HIGH
in: query
- name: statuses
schema:
type: array
title: statuses filters
description: 'To filter by multiple statuses: `statuses=APPROVED&statuses=DONE`'
items:
type: string
example: APPROVED
enum:
- PENDING
- REJECTED
- APPROVED
- DONE
in: query
- in: query
name: expand
schema:
title: Expand specific fields in the request
description: 'To expand multiple fields: `expand=asset&expand=location`'
type: array
items:
type: string
enum:
- asset
- location
- work_order
- extra_fields
- 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 fetched Work Requests list
content:
application/json:
schema:
type: object
required:
- workRequests
properties:
workRequests:
type: array
items:
type: object
required:
- id
- priority
- title
- requestStatus
properties:
id:
type: number
example: 963
description: Global ID of the work request
title:
type: string
example: Forklift Preventive Maintenance Form
attachments:
type: array
title: attachment
description: List of attachments linked to the Work Request
items:
type: object
title: attachment
required:
- id
- mimeType
- fileName
- url
- createdAt
properties:
id:
type: number
description: Global ID of the attachment
example: 12345
mimeType:
type: string
description: MIME type of the file
example: image/png
fileName:
type: string
description: Attachment's file name
example: image.png
url:
type: string
description: Url of the file. Valid for 60 minutes.
example: http://example.com/image.png
createdAt:
type: string
format: date-time
description: Date & time at which the attachment was uploaded
example: '2022-01-01T00:00:00.000Z'
width:
type: number
description: Width if the file is an image
nullable: true
example: 220
height:
type: number
description: Height if the file is an image
nullable: true
example: 100
thumbnail:
type: object
title: attachment
required:
- id
- mimeType
- fileName
- url
- createdAt
properties:
id:
type: number
description: Global ID of the attachment
example: 12345
mimeType:
type: string
description: MIME type of the file
example: image/png
fileName:
type: string
description: Attachment's file name
example: image.png
url:
type: string
description: Url of the file. Valid for 60 minutes.
example: http://example.com/image.png
createdAt:
type: string
format: date-time
description: Date & time at which the attachment was uploaded
example: '2022-01-01T00:00:00.000Z'
width:
type: number
description: Width if the file is an image
nullable: true
example: 220
height:
type: number
description: Height if the file is an image
nullable: true
example: 100
nullable: true
priority:
type: string
example: MEDIUM
enum:
- NONE
- LOW
- MEDIUM
- HIGH
description:
type: string
example: A forklift that needs to be reviewed for any potential problems
nullable: true
requestStatus:
type: string
enum:
- PENDING
- REJECTED
- APPROVED
- DONE
example: PENDING
assetId:
type: number
format: integer
example: 843
nullable: true
locationId:
type: number
format: integer
example: 852
nullable: true
workOrderId:
type: number
format: integer
example: 254
nullable: true
description: Global ID of the work order attached to the work request. A work order is created once a work request is approved.
sendEmailNotification:
type: boolean
example: true
extraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Request Type") (expand with query parameter)'
additionalProperties:
type: string
example:
Request Type: Water Leak
nullable: false
approverTeamId:
type: number
format: integer
example: 254
nullable: true
description: ID of the team that is reponsible for approving the request.
creatorContactInfo:
type: object
nullable: true
description: The creator's contact information associated with this work order request
properties:
type:
type: string
example: EMAIL
enum:
- PHONE
- EMAIL
- OTHER
value:
type: string
example: james@example.com
createdAt:
type: string
format: date-time
description: Date & time at which the work request was created
example: '2022-01-01T00:00:00.000Z'
updatedAt:
type: string
format: date-time
description: Date & time at which the work request was last updated
example: '2022-01-01T00:00:00.000Z'
asset:
type: object
required:
- id
- name
- description
- parentId
- criticalityId
- locationId
- serialNumber
- createdAt
- updatedAt
- creatorId
description: Asset linked to the element (expand with query parameter)
properties:
id:
type: integer
example: 963
description: Global ID of the asset
name:
type: string
example: Forklift
description:
type: string
nullable: true
example: Forklift that is used to to move heavy equipments around the warehouse
parentId:
type: integer
nullable: true
example: 852
description: ID of the parent asset
criticalityId:
type: integer
nullable: true
example: 150
description: ID of the criticality of the asset
locationId:
type: integer
nullable: true
example: 852
description: ID of the location where the asset is located
serialNumber:
type: string
nullable: true
description: Serial number of the asset
example: 000123ABC
createdAt:
type: string
format: date-time
description: Date & time at which the asset was created
example: '2022-01-01T00:00:00.000Z'
updatedAt:
type: string
format: date-time
description: Date & time at which the asset was last updated. This doesn't include comments
example: '2022-01-01T00:00:00.000Z'
creatorId:
type: integer
nullable: true
example: 851
description: ID of the asset creator
nullable: false
location:
type: object
required:
- id
- name
description: Location linked to the element (expand with query parameter)
properties:
id:
type: integer
example: 963
description: Global ID of the location
name:
type: string
example: Warehouses
description:
type: string
nullable: true
example: The warehouse where we store the forklifts
address:
type: string
nullable: true
example: 1090 main street, Franklin
description: Postal address of the location
parentId:
type: integer
nullable: true
example: 852
description: ID of the parent location
createdAt:
type: string
format: date-time
description: Date & time at which the location was created
example: '2022-01-01T00:00:00.000Z'
updatedAt:
type: string
format: date-time
description: Date & time at which the location was last updated. This doesn't include comments
example: '2022-01-01T00:00:00.000Z'
nullable: false
workOrder:
type: object
required:
- updatedAt
- status
- title
- createdAt
- creatorId
- id
- sequentialId
- organizationId
description: Work Order linked to the element (expand with query parameter)
properties:
id:
type: integer
description: Global ID of the work order
sequentialId:
type: integer
description: Organization specific ID of the work order
assetId:
nullable: true
type: integer
example: 42
attachments:
type: array
title: attachment
description: List of attachments linked to the work order
items:
type: object
title: attachment
required:
- id
- mimeType
- fileName
- url
- createdAt
properties:
id:
type: number
description: Global ID of the attachment
example: 12345
mimeType:
type: string
description: MIME type of the file
example: image/png
fileName:
type: string
description: Attachment's file name
example: image.png
url:
type: string
description: Url of the file. Valid for 60 minutes.
example: http://example.com/image.png
createdAt:
type: string
format: date-time
description: Date & time at which the attachment was uploaded
example: '2022-01-01T00:00:00.000Z'
width:
type: number
description: Width if the file is an image
nullable: true
example: 220
height:
type: number
description: Height if the file is an image
nullable: true
example: 100
categories:
type: array
description: List of categories that identify the work order
items:
type: string
example: Cleaning
uniqueItems: true
completedAt:
nullable: true
type: string
format: date-time
description: Date & time at which the work order was last marked as DONE
example: '2022-01-01T00:00:00.000Z'
completerId:
nullable: true
type: integer
description: ID of the user who completed the work order
createdAt:
type: string
format: date-time
description: Date & time at which the work order was created
example: '2022-01-01T00:00:00.000Z'
creatorId:
nullable: true
type: integer
description: ID of the user who created the work order
deletedAt:
nullable: true
type: string
format: date-time
description: Date & time at which the work order was deleted
example: '2022-01-01T00:00:00.000Z'
description:
nullable: true
type: string
example: A work order sample description
dueDateIsFullDay:
nullable: true
type: boolean
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'
estimatedTime:
type: integer
nullable: true
description: The estimated time taken in seconds to complete the work order
example: 3600
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:
nullable: true
type: boolean
description: If this is a parent work order
lastMessageSentAt:
nullable: true
type: string
format: date-time
description: Date & time at which the last comment was added to the work order
example: '2022-01-01T00:00:00.000Z'
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
example: 611
nextId:
nullable: true
type: integer
organizationId:
type: number
parentId:
nullable: true
type: integer
description: The ID of the parent work order
partsAvailability:
type: string
enum:
- PARTS_AVAILABLE
- PARTS_UNAVAILABLE
- PARTIAL_PARTS
- PARTS_AVAILABLE_BUT_OVERCOMMITTED
description: Computed parts availability for this work order based on current inventory levels.
partStatus:
type: string
enum:
- NO_PARTS
- ASSIGNED
- RESERVED
- KITTED
- STAGED
- ISSUED
description: Part stage indicates the current readiness state of parts for this work order.
previousId:
nullable: true
type: integer
priority:
type: string
example: MEDIUM
enum:
- NONE
- LOW
- MEDIUM
- HIGH
recurrenceInfo:
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:
# --- truncated at 32 KB (355 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/maintainx/refs/heads/main/openapi/maintainx-work-requests-api-openapi.yml