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 Locations 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: Locations
description: Operations on Locations
x-traitTag: false
paths:
/locations:
post:
summary: Create new location
requestBody:
description: Location to create
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
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
barcode:
type: string
nullable: true
example: BWFPBNRHAW54CG
description: String encoded barcode
parentId:
type: integer
nullable: true
example: 852
description: ID of the parent location
extraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Department")'
additionalProperties:
type: string
example:
Department: Electrical
vendorIds:
type: array
description: Vendor IDs
items:
type: number
example: 2
responses:
'200':
description: Successfully created location
content:
application/json:
schema:
type: object
required:
- id
properties:
id:
type: integer
example: 963
description: Global ID of the location
'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:
- Locations
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 locations
description: Endpoint used to list location resources
parameters:
- name: cursor
in: query
schema:
description: Last pagination reference
type: string
- name: limit
in: query
schema:
description: max number of Locations returned
type: integer
minimum: 1
maximum: 200
default: 100
- name: name
schema:
type: string
description: Will only show locations that have a name starting with this.
in: query
- name: customFieldName
schema:
type: array
items:
type: string
description: "Filter locations 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 \"/locations?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>/locations?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>/locations?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
description: 'To expand multiple fields: `expand=extra_fields&expand=team_ids`'
type: array
items:
type: string
enum:
- extra_fields
- team_ids
- vendor_ids
- barcode
- schema:
type: integer
description: Required if using a multi organizations token
name: x-organization-id
in: header
required: false
example: '1'
- schema:
type: string
description: Required if using a multi organizations token and doing an operation on resources from multiple organizations. This is mutually exclusive with the x-organization-id header (use one or the other).
name: x-organization-ids
in: header
required: false
example: 1,2,3
responses:
'200':
description: Successfully fetched Locations list
content:
application/json:
schema:
type: object
required:
- locations
properties:
locations:
type: array
items:
type: object
required:
- id
- name
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'
organizationId:
type: integer
example: 1
description: ID of the organization that owns this resource
extraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Department") (expand with query parameter)'
additionalProperties:
type: string
example:
Department: Electrical
nullable: false
teamIds:
type: array
description: Team IDs (expand with query parameter)
items:
type: number
example: 2
nullable: false
vendorIds:
type: array
description: Vendor IDs (expand with query parameter)
items:
type: number
example: 2
nullable: false
barcode:
type: string
nullable: false
example: BWFPBNRHAW54CG
description: String encoded barcode (expand with query parameter)
nextCursor:
description: The cursor to retrieve the next page of Locations.
type: string
nullable: true
nextPageUrl:
description: Path with query parameters that can be used to retrieve the next page of Locations.
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:
- Locations
/locations/{id}:
get:
summary: Get location
parameters:
- schema:
type: integer
name: id
in: path
required: true
description: ID of the location
example: '1'
responses:
'200':
description: Successfully retrieved location's information
content:
application/json:
schema:
type: object
required:
- location
properties:
location:
type: object
required:
- id
- name
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
barcode:
type: string
nullable: true
example: BWFPBNRHAW54CG
description: String encoded barcode
parentId:
type: integer
nullable: true
example: 852
description: ID of the parent location
childrenIds:
type: array
nullable: true
items:
type: number
example:
- 342
- 521
description: IDs of the location's children
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 location
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
extraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Department")'
additionalProperties:
type: string
example:
Department: Electrical
teamIds:
type: array
description: Team IDs
items:
type: number
example: 2
vendorIds:
type: array
description: Vendor IDs
items:
type: number
example: 2
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'
deletedAt:
type: string
nullable: true
description: Date at which the location was deleted
format: date-time
'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 location or the user cannot access it.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
example: Not Found.
tags:
- Locations
patch:
summary: Update location
parameters:
- schema:
type: integer
name: id
in: path
required: true
description: ID of the location
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: Location to update
required: true
content:
application/json:
schema:
type: object
properties:
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
barcode:
type: string
nullable: true
example: BWFPBNRHAW54CG
description: String encoded barcode
parentId:
type: integer
nullable: true
example: 852
description: ID of the parent location
extraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Department")'
additionalProperties:
type: string
example:
Department: Electrical
vendorIds:
type: array
description: Vendor IDs
items:
type: number
example: 2
responses:
'200':
description: Successfully edited location
content:
application/json:
schema:
type: object
required:
- location
properties:
location:
type: object
required:
- id
- name
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
barcode:
type: string
nullable: true
example: BWFPBNRHAW54CG
description: String encoded barcode
parentId:
type: integer
nullable: true
example: 852
description: ID of the parent location
childrenIds:
type: array
nullable: true
items:
type: number
example:
- 342
- 521
description: IDs of the location's children
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 location
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
extraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Department")'
additionalProperties:
type: string
example:
Department: Electrical
teamIds:
type: array
description: Team IDs
items:
type: number
example: 2
vendorIds:
type: array
description: Vendor IDs
items:
type: number
example: 2
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'
deletedAt:
type: string
nullable: true
description: Date at which the location was deleted
format: date-time
'400':
description: Failed to edit the location
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 location.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
example: location Not Found
tags:
- Locations
delete:
summary: Delete location
parameters:
- schema:
type: integer
name: id
in: path
required: true
description: ID of the location
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 location
'401':
$ref: '#/components/responses/UnauthorizedError
# --- truncated at 32 KB (244 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/maintainx/refs/heads/main/openapi/maintainx-locations-api-openapi.yml