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 Vendors 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: Vendors
description: Operations on Vendors
x-traitTag: false
paths:
/vendors:
post:
summary: Create new vendor
requestBody:
description: Vendor to create
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
example: Acme Corp
description:
type: string
nullable: true
example: Provider of Acme service
extraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Qualifications")'
additionalProperties:
type: string
example:
Qualifications: ISO 000
emails:
type: array
items:
type: string
example:
- vendor@example.com
description: List of email address
deprecated: true
phoneNumbers:
type: array
items:
type: string
example:
- 415-555-0100
description: List of phone number
deprecated: true
responses:
'201':
description: Successfully created vendor
content:
application/json:
schema:
type: object
required:
- id
properties:
id:
type: integer
example: 963
description: Global ID of the vendor
'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:
- Vendors
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 vendors
description: Endpoint used to list vendor resources
parameters:
- name: cursor
in: query
schema:
description: Last pagination reference
type: string
- name: limit
in: query
schema:
description: max number of Vendors returned
type: integer
minimum: 1
maximum: 200
default: 100
- name: customFieldName
schema:
type: array
items:
type: string
description: "Filter vendors 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 \"/vendors?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>/vendors?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</code>, etc, you can add <code>__c</code> to your custom field filtering (ie: To filter by a custom field named <code>limit</code> with the value <code>ten</code>, you would do this <code>/vendors?limit__c=ten</code>).\n <br><br>Note that your custom field needs to be created beforehand. Only number and single line text custom field types are supported."
in: query
- in: query
name: expand
schema:
title: Expand specific fields in the request
type: array
items:
type: string
enum:
- 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 Vendors list
content:
application/json:
schema:
type: object
required:
- vendors
properties:
vendors:
type: array
items:
type: object
required:
- id
- name
properties:
id:
type: integer
example: 963
description: Global ID of the vendor
name:
type: string
example: Acme Corp
extraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Qualifications") (expand with query parameter)'
additionalProperties:
type: string
example:
Qualifications: ISO 000
nullable: false
nextCursor:
description: The cursor to retrieve the next page of Vendors.
type: string
nullable: true
nextPageUrl:
description: Path with query parameters that can be used to retrieve the next page of Vendors.
type: string
nullable: true
'400':
description: Error with query
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
description: Description of error
type: string
'401':
$ref: '#/components/responses/UnauthorizedError'
tags:
- Vendors
/vendors/{id}:
get:
summary: Get vendor
parameters:
- schema:
type: integer
name: id
in: path
required: true
description: ID of the vendor
example: '1'
responses:
'200':
description: Successfully retrieved vendor's information
content:
application/json:
schema:
type: object
required:
- vendor
properties:
vendor:
type: object
required:
- id
- name
properties:
id:
type: integer
example: 963
description: Global ID of the vendor
name:
type: string
example: Acme Corp
emails:
type: array
items:
type: string
example:
- vendor@example.com
description: List of email address
deprecated: true
phoneNumbers:
type: array
items:
type: string
example:
- 415-555-0100
description: List of phone number
deprecated: true
description:
type: string
nullable: true
example: Provider of Acme service
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 vendor
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
contactIds:
type: array
items:
type: integer
example:
- 1
- 4
- 13
description: List of contact IDs
deletedAt:
type: string
format: date-time
description: Date that the vendor was deleted
example: '2022-01-01T00:00:00.000Z'
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: "Qualifications")'
additionalProperties:
type: string
example:
Qualifications: ISO 000
'400':
description: Error with query
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
description: Description of error
type: string
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
description: Could not find the specified vendor or the user cannot access it.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
example: Not Found.
tags:
- Vendors
patch:
summary: Update vendor
parameters:
- schema:
type: integer
name: id
in: path
required: true
description: ID of the vendor
example: '1'
- 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
requestBody:
description: Vendor to update
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: Acme Corp
description:
type: string
nullable: true
example: Provider of Acme service
extraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Qualifications")'
additionalProperties:
type: string
example:
Qualifications: ISO 000
responses:
'200':
description: Successfully edited vendor
content:
application/json:
schema:
type: object
required:
- vendor
properties:
vendor:
type: object
required:
- id
- name
properties:
id:
type: integer
example: 963
description: Global ID of the vendor
name:
type: string
example: Acme Corp
emails:
type: array
items:
type: string
example:
- vendor@example.com
description: List of email address
deprecated: true
phoneNumbers:
type: array
items:
type: string
example:
- 415-555-0100
description: List of phone number
deprecated: true
description:
type: string
nullable: true
example: Provider of Acme service
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 vendor
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
contactIds:
type: array
items:
type: integer
example:
- 1
- 4
- 13
description: List of contact IDs
deletedAt:
type: string
format: date-time
description: Date that the vendor was deleted
example: '2022-01-01T00:00:00.000Z'
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: "Qualifications")'
additionalProperties:
type: string
example:
Qualifications: ISO 000
'400':
description: Failed to edit the vendor
content:
application/json:
schema:
type: object
required:
- errors
example:
errors:
- error: parentId is not valid
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'
'404':
description: Could not find the specified vendor.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
example: vendor Not Found
tags:
- Vendors
delete:
summary: Delete vendor
parameters:
- schema:
type: integer
name: id
in: path
required: true
description: ID of the vendor
example: '1'
- 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
responses:
'204':
description: Successfully deleted the vendor
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
description: Could not find the specified vendor.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
example: vendor Not Found
'500':
description: Internal server error.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
example: Internal server error.
tags:
- Vendors
/vendors/{id}/attachments/{filename}:
put:
summary: Update vendor attachment
parameters:
- schema:
type: integer
name: id
in: path
required: true
description: ID of the vendor.
example: '1'
- schema:
type: string
name: filename
in: path
required: true
description: Name of the attachment, including the extension.
example: datasheet.pdf
- 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
requestBody:
description: Content type should be `application/octet-stream` and payload should use binary format for the attachment.
required: true
content:
application/octet-stream:
schema:
type: object
format: binary
image/jpeg:
schema:
type: object
format: binary
image/png:
schema:
type: object
format: binary
image/gif:
schema:
type: object
format: binary
image/webp:
schema:
type: object
format: binary
image/flif:
schema:
type: object
format: binary
image/x-xcf:
schema:
type: object
format: binary
image/x-canon-cr2:
schema:
type: object
format: binary
image/x-canon-cr3:
schema:
type: object
format: binary
image/tiff:
schema:
type: object
format: binary
image/bmp:
schema:
type: object
format: binary
image/vnd.ms-photo:
schema:
type: object
format: binary
image/vnd.adobe.photoshop:
schema:
type: object
format: binary
application/x-indesign:
schema:
type: object
format: binary
application/epub+zip:
schema:
type: object
format: binary
application/x-xpinstall:
schema:
type: object
format: binary
application/vnd.ms-powerpoint.slideshow.macroenabled.12:
schema:
type: object
format: binary
application/vnd.oasis.opendocument.text:
schema:
type: object
format: binary
application/vnd.oasis.opendocument.spreadsheet:
schema:
type: object
format: binary
application/vnd.oasis.opendocument.presentation:
schema:
type: object
format: binary
application/vnd.openxmlformats-officedocument.wordprocessingml.document:
schema:
type: object
format: binary
application/vnd.openxmlformats-officedocument.presentationml.presentation:
schema:
type: object
format: binary
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
schema:
type: object
format: binary
application/vnd.openxmlformats-officedocument.presentationml.slideshow:
schema:
type: object
format: binary
application/zip:
schema:
type: object
format: binary
application/x-tar:
schema:
type: object
format: binary
application/x-rar-compressed:
schema:
type: object
format: binary
application/gzip:
schema:
type: object
format: binary
application/x-bzip2:
schema:
type: object
format: binary
application/x-7z-compressed:
schema:
type: object
format: binary
application/x-apple-diskimage:
schema:
type: object
format: binary
application/vnd.apache.arrow.file:
schema:
type: object
format: binary
video/mp4:
schema:
type: object
format: binary
audio/midi:
schema:
type: object
format: binary
video/matroska:
schema:
type: object
format: binary
video/webm:
schema:
type: object
format: binary
video/quicktime:
schema:
type: object
format: binary
video/vnd.avi:
schema:
type: object
format: binary
audio/wav:
schema:
type: object
# --- truncated at 32 KB (258 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/maintainx/refs/heads/main/openapi/maintainx-vendors-api-openapi.yml