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 Purchase 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: Purchase Orders
description: Operations on Purchase Orders
x-traitTag: false
paths:
/purchaseorders:
post:
summary: Create new purchase order
requestBody:
description: Purchase Order to create
required: true
content:
application/json:
schema:
type: object
required:
- vendorId
- items
properties:
note:
type: string
nullable: true
description: Notes left for Purchase Orders
example: Please deliver during business hours
dueDate:
type: string
example: '2022-01-01T00:00:00.000Z'
description: Due date of Purchase Order
nullable: true
vendorId:
type: number
example: 432
description: ID of vendor that this Purchase Order is associated with
nullable: true
overrideNumber:
type: string
example: A123
nullable: true
description: Custom number/identifier for Purchase Order
deletedAt:
type: string
example: '2022-01-01T00:00:00.000Z'
format: date-time
description: Date at which the Purchase Order was deleted
nullable: true
vendorContactIds:
type: array
description: List of vendor contact IDs in the Purchase Order
example:
- 12
- 34
- 56
items:
type: number
example: 12
shippingAddress:
type: object
description: Shipping address in the Purchase Order
required:
- city
- country
- postalCode
- state
- street
properties:
city:
type: string
example: Montreal
country:
type: string
example: Canada
postalCode:
type: string
example: H4B 5G0
state:
type: string
example: Quebec
street:
type: string
example: 1909 Avenue des Canadiens-de-Montréal
label:
type: string
description: A string to specify how the address will be displayed - Defaults to Street, City, Province/State, Postal Code, Country
example: '1909 Avenue des Canadiens-de-Montréal, Montreal, H4B 5G0, QC, CA '
nullable: true
nullable: true
shippingAddressId:
type: number
description: Shipping address Id in the Purchase Order
nullable: true
billingAddress:
type: object
description: Billing address in the Purchase Order
required:
- city
- country
- postalCode
- state
- street
properties:
city:
type: string
example: Montreal
country:
type: string
example: Canada
postalCode:
type: string
example: H4B 5G0
state:
type: string
example: Quebec
street:
type: string
example: 1909 Avenue des Canadiens-de-Montréal
label:
type: string
description: A string to specify how the address will be displayed - Defaults to Street, City, Province/State, Postal Code, Country
example: '1909 Avenue des Canadiens-de-Montréal, Montreal, H4B 5G0, QC, CA '
nullable: true
nullable: true
billingAddressId:
type: number
description: Billing address Id in the Purchase Order
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: "Ordered Date")'
additionalProperties:
type: string
example:
Ordered Date: '2023-01-01'
items:
type: array
description: List of items in the Purchase Order
items:
type: object
required:
- quantityOrdered
properties:
partId:
type: number
example: 43
description: ID of the part this item is related to
nullable: true
name:
type: string
nullable: true
partNumber:
type: string
nullable: true
price:
type: number
example: 25000
nullable: true
description: Total price of items in cents
quantityOrdered:
type: number
example: 4
description: Represent the amount of units for this item that were ordered in the purchase order.
quantityReceived:
type: number
example: 3
nullable: true
description: Represents the total amount of this specific item that has been received to date.
unitCost:
type: number
example: 125000
nullable: true
description: Price of a single item in cents
extraFields:
type: object
additionalProperties:
type: string
description: 'Custom Fields on the entity. Deprecated: Use `lineExtraFields` instead.'
deprecated: true
lineExtraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Ordered Date")'
additionalProperties:
type: string
example:
Ordered Date: '2023-01-01'
costs:
type: array
description: List of costs in the Purchase Order
items:
type: object
required:
- name
- type
- amount
properties:
name:
type: string
example: Sales Tax
description: Description of the cost
type:
type: string
enum:
- AMOUNT_NON_TAXABLE
- AMOUNT_TAXABLE
- PERCENT_TAXABLE
example: AMOUNT_TAXABLE
description: Type of cost in either cents or percent. Accepted types in cents are AMOUNT_TAXABLE and AMOUNT_NON_TAXABLE. For percentage use PERCENT_TAXABLE
amount:
type: number
example: 125000
title:
type: string
nullable: true
description: Title of the Purchase Order. Will be ignored if organization setting for custom purchase order titles is disabled.
example: Office Supplies Order
responses:
'201':
description: Successfully created Purchase Order
content:
application/json:
schema:
type: object
required:
- id
- status
- items
properties:
id:
type: number
example: 135
description: Global ID of the Purchase Order
note:
type: string
nullable: true
description: Notes left for Purchase Orders
example: Please deliver during business hours
title:
type: string
nullable: true
description: Title of the Purchase Order.
example: Office Supplies Order
reviewNote:
type: string
nullable: true
description: Notes to be left for changes to be made when sending a Purchase Order for revision
example: Please adjust quantities and resubmit
status:
type: string
nullable: true
example: APPROVED
description: Status of the Purchase Order. Supported values are APPROVED, CANCELED, COMPLETED, DECLINED, PARTIALLY_FULFILLED, PENDING, REQUESTED
dueDate:
type: string
example: '2022-01-01T00:00:00.000Z'
description: Due date of Purchase Order
nullable: true
creatorId:
type: number
example: 432
description: ID of the user that created this Purchase Order
vendorId:
type: number
example: 432
description: ID of vendor that this Purchase Order is associated with
nullable: true
autoGeneratedNumber:
type: number
example: 987
nullable: true
description: Autogenerated Purchase Order number
overrideNumber:
type: string
example: A123
nullable: true
description: Custom number/identifier for Purchase Order
approverId:
type: number
example: 135
description: ID of the user who approved the Purchase Order
nullable: true
approvalDate:
type: string
example: '2022-01-01T00:00:00.000Z'
description: Date the Purchase Order was approved
nullable: true
createdAt:
type: string
example: '2022-01-01T00:00:00.000Z'
format: date-time
description: Date the Purchase Order was created
nullable: true
updatedAt:
type: string
example: '2022-01-01T00:00:00.000Z'
description: Date the Purchase Order was last updated
nullable: true
deletedAt:
type: string
example: '2022-01-01T00:00:00.000Z'
format: date-time
description: Date at which the Purchase Order was deleted
nullable: true
items:
type: array
description: List of items in the Purchase Order
items:
type: object
required:
- id
- quantityOrdered
properties:
id:
type: number
example: 23
description: ID of the item
partId:
type: number
example: 43
description: ID of the part this item is related to
nullable: true
name:
type: string
nullable: true
partNumber:
type: string
nullable: true
price:
type: number
example: 25000
nullable: true
description: Total price of items in cents
priceDecimal:
type: string
example: '250.000000'
nullable: true
description: Total price of items as a decimal value
quantityOrdered:
type: number
example: 4
description: Represent the amount of units for this item that were ordered in the purchase order.
quantityReceived:
type: number
example: 3
nullable: true
description: Represents the total amount of this specific item that has been received to date.
unitCost:
type: number
example: 125000
nullable: true
description: Price of a single item in cents
unitCostDecimal:
type: string
example: '1250.000000'
nullable: true
description: Price of a single item as a decimal value
fulfillments:
type: array
items:
type: object
properties:
id:
type: number
example: 23
description: ID of the item fulfillment
locationId:
type: number
example: 852
nullable: true
description: ID of the location where the item was fulfilled
quantityReceived:
type: string
example: '3.000000'
description: Quantity of the item fulfilled to this location
isLegacy:
type: boolean
description: Indicates the location is a legacy location. This is used to determine if this fulfillment was done before enablement of the multi-location parts feature.
example: true
description: Fulfillment information for the item's fulfillment locations.
extraFields:
type: object
additionalProperties:
type: string
description: 'Custom Fields on the entity. Deprecated: Use `lineExtraFields` instead.'
deprecated: true
lineExtraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Ordered Date")'
additionalProperties:
type: string
example:
Ordered Date: '2023-01-01'
partExtraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Part Number")'
additionalProperties:
type: string
example:
Part Number: '321'
costs:
type: array
description: List of costs in the Purchase Order
items:
type: object
required:
- name
- type
- amount
properties:
id:
type: number
example: 123
description: ID of the cost
name:
type: string
example: Sales Tax
description: Description of the cost
type:
type: string
enum:
- AMOUNT_NON_TAXABLE
- AMOUNT_TAXABLE
- PERCENT_TAXABLE
example: AMOUNT_TAXABLE
description: Type of cost in either cents or percent. Accepted types in cents are AMOUNT_TAXABLE and AMOUNT_NON_TAXABLE. For percentage use PERCENT_TAXABLE
amount:
type: number
example: 125000
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
attachments:
type: array
title: attachment
description: List of attachments linked to the Purchase 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
vendorContactIds:
type: array
description: List of vendor contact IDs in the Purchase Order
example:
- 12
- 34
- 56
items:
type: number
example: 12
shippingAddress:
type: object
description: Shipping address in the Purchase Order
required:
- city
- country
- postalCode
- state
- street
properties:
city:
type: string
example: Montreal
country:
type: string
example: Canada
postalCode:
type: string
example: H4B 5G0
state:
type: string
example: Quebec
street:
type: string
example: 1909 Avenue des Canadiens-de-Montréal
label:
type: string
description: A string to specify how the address will be displayed - Defaults to Street, City, Province/State, Postal Code, Country
example: '1909 Avenue des Canadiens-de-Montréal, Montreal, H4B 5G0, QC, CA '
nullable: true
nullable: true
billingAddress:
type: object
description: Billing address in the Purchase Order
required:
- city
- country
- postalCode
- state
- street
properties:
city:
type: string
example: Montreal
country:
type: string
example: Canada
postalCode:
type: string
example: H4B 5G0
state:
type: string
example: Quebec
street:
type: string
example: 1909 Avenue des Canadiens-de-Montréal
label:
type: string
description: A string to specify how the address will be displayed - Defaults to Street, City, Province/State, Postal Code, Country
example: '1909 Avenue des Canadiens-de-Montréal, Montreal, H4B 5G0, QC, CA '
nullable: true
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: "Ordered Date")'
additionalProperties:
type: string
example:
Ordered Date: '2023-01-01'
'400':
description: Failed to create the Purchase Order
content:
application/json:
schema:
type: object
required:
- errors
example:
errors:
- error: errors with request
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'
'403':
description: Failed to create the Purchase Order
content:
application/json:
schema:
type: object
required:
- errors
example:
errors:
- error: User doesn't have the right permissions
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
'404':
description: Could not find the specified Purchase Order.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
example: Purchase Order Not Found
'429':
description: Too many requests. Please retry in 10 seconds
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
example: Too many requests. Please retry in 10 seconds
tags:
- Purchase Orders
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 purchase orders
description: Endpoint used to list purchase order resources
parameters:
- name: cursor
in: query
schema:
description: Last pagination reference
type: string
- name: limit
in: query
schema:
description: max number of Purchase Orders returned
type: integer
minimum: 1
maximum: 200
default: 100
- name: updatedAt[gte]
schema:
type: string
format: date-time
description: Return records whose updatedAt is at or after this ISO 8601 date-time (UTC).
example: '2024-01-01T00:00:00.000Z'
in: query
- name: updatedAt[lte]
schema:
type: string
format: date-time
description: Return records whose updatedAt is at or before this ISO 8601 date-time (UTC).
example: '2024-12-31T23:59:59.999Z'
in: query
- name: createdAt[gte]
schema:
type: string
format: date-time
description: Return records whose createdAt is at or after this ISO 8601 date-time (UTC).
example: '2024-01-01T00:00:00.000Z'
in: query
- name: createdAt[lte]
schema:
type: string
format: date-time
description: Return records whose createdAt is at or before this ISO 8601 date-time (UTC).
example: '2024-12-31T23:59:59.999Z'
in: query
- name: customFieldName
schema:
type: array
items:
type: string
description: "Filter purchase orders by custom field value. Your query parameter should be your custom field name. (ie: To filter by a custom field named \"Industry\" with the value \"Construction\", you would do this \"/purchaseorders?Industry=Construction\").\n <br><br>Adding multiple instance of the same custom field act as an <code>OR</code> and adding a different custom field act as an <code>AND</code>. (ie: To filter by a custom field named <code>Industry</code> with the value <code>Construction</code> OR <code>Transportation</code> AND the custom field <code>Manufacturer</code> with the value <code>ACME</code>, you would do this <code>/purchaseorders?Industry=Construction&Industry=Transportation&Manufacturer=ACME</code>).\n <br><br>If your custom field label is the same as a reserved query parameter such as <code>limit</code>, <code>sort</code>, <code>expand<
# --- truncated at 32 KB (354 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/maintainx/refs/heads/main/openapi/maintainx-purchase-orders-api-openapi.yml