MP Web API Documentation
Maintenance Pro Web API Documentation
Maintenance Pro Web (MPW) provides a JSON-based REST API (MPW-API) to allow our Enterprise clients to integrate MPW data with other applications. Initial focus for API development has been facilitating inventory integration with accounting and ERP systems.
Shortcuts:
Authentication
The first step to use MPW-API is to obtain a JSON Web Token (JWT) via https POST to
https://www.mtcproweb.com/api/v1/mpw/authentication
passing your user email address and password as parameters.
Here is an example authentication call using CURL:
curl -X POST -F 'email=user@example.com' -F 'password=welcome' https://www.mtcproweb.com/api/v1/mpw/authentication
Note that the user account used for API access will determine the scope of data available to subsequent API calls. For example, if a non-admin user is used with only access to certain Warehouses in MPW, API results will be limited to the Warehouses to which that user has access.
A successful authentication call will respond with a JSON object with an access_token
attribute. This token will be in subsequent calls to the API in the Authorization header. Tokens are valid for 24 hours, so feel free to store and reuse this token for the current session’s requests. You will receive an Unauthorized error if you attempt to access the API with an expired token. In this case, simply request a new one. Here is an example of how an authentication token is used in a subsequent request:
curl -H 'Accept: application/json' -H "Authorization: Bearer 1yJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxNTkxNywiZXhwIjoxNjAxMjYwODYxfQ.gyg5Vz85VlkKI7dEBfOseldyJixof6A4TNLaF87ohw" https://www.mtcproweb.com/api/v1/mpw/issuances?date=2020-09-01
Issuances - GET
The /issuances API returns an array of JSON objects describing inventory Issuances within MPW via a GET request to the following endpoint:
https://www.mtcproweb.com/api/v1/mpw/issuances
The following parameters are supported:
Parameter | Required | Format |
---|---|---|
date |
Yes | ISO YYYY-MM-DD format |
warehouse_name |
No | Must be an exact match of the name of an existing Warehouse |
Here’s an example of a GET /issuances
request, along with the response:
curl -H 'Accept: application/json' -H "Authorization: Bearer (access token) " https://www.mtcproweb.com/api/v1/mpw/issuances?date=2020-09-28
Response:
[ {"id":43381, "part_number":"091843", “inventory_name”:”part name”, "created_on":"2020-09-28", "quantity":1.0, "unit_cost":9.99, "overdraft":false, "description":”issuance description field content”, "warehouse_name":"Warehouse #1"} ]
New Issuances may be removed stock within MPW via a POST to the /issuances
endpoint. The parameters posted must be a JSON object as follows, with required fields.
Endpoint:
https://www.mtcproweb.com/api/v1/mpw/issuances
The following parameters are supported in the POST JSON object:
Parameter | Required | Format |
---|---|---|
part_number |
Yes | String |
warehouse_name |
Yes |
String - Must be an exact match |
quantity |
Yes | Integer |
created_on |
Yes |
String ISO YYYY-MM-DD |
api_key |
Yes | String - required unless date is provided. The api_key is a unique key that you must provide to uniquely identify any Issuances that you create via MPW-API |
equipment_unit_number |
No |
String - this may only be used if you are NOT defining a Work Order and Task Name combination to issue the part to. |
description |
No | String |
work_order_sequential_id |
No | Integer - this is the Work Order Number you are posting the issuance to. Must be used in combination with a task_name |
task_name |
No | String - must be an exact match - this is the name of the task on the Work Order which the issuance is applied to. Must be used in combination with work_order_sequential_id |
Parameter Notes: The warehouse_name
parameter must refer to a Warehouse that contains the specified Inventory. Issuances cannot be edited via multiple POST requests. If an issuance with an existing api_key
is found, an error will be returned. Existing issuances must be deleted if a change is necessary.
Just as with MPW’s Web interface, there is a subtle difference between creating an Issuance with and without an associated Equipment: Issuances without an associated Equipment cannot exceed the quantity present in the current Receipt. An error will be returned with a message indicating the maximum quantity available for the Issuance creation request. If an Equipment is not specified, a successful post will return a JSON object with the newly-created Issuance. Issuance with an associated Equipment will automatically split a request exceeding the current Receipt quantity into multiple Issuances across multiple Receipts. Therefore, a successful post returns an array of Issuances identified by the submitted api_key
.
The same principle applies to posting an Issuance to a work order number and task name combination. An array of issuances may occur when quantities posted to the work order and task name combination exceed what is available on the current receipt.
A successful post will return a JSON object with the newly-created or updated Issuance. Here’s an example of an /issuances
POST to a work order and task name combination, and the response:
curl -v \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer KtGUKteF4PYtR7wSqbs" \ -d '{"issuance": { "part_number":"000global", "quantity":1.00, "created_on":"2023-07-26", "warehouse_name":"WH2", "work_order_sequential_id":1234567996, "task_name":"repair3", "api_key":"001" } }' \ https://www.mtcproweb.com/api/v1/mpw/issuances
Response:
[{"id":44135, "inventory_id":279796, "part_number":"000global", "inventory_name":"Global part", "organization_id":3305, "warehouse_id":6713, "created_on":"2023-07-26", "quantity":1.0, "unit_cost":50.0, "overdraft":false, "description":null, "api_key":"001", "warehouse_name":"WH2", "equipment_unit_number":null, "equipment_type":null, "custom_fields":{}}, {"id":44136, "inventory_id":279796, "part_number":"000global", "inventory_name":"Global part", "organization_id":3305, "warehouse_id":6713, "created_on":"2023-07-26", "quantity":1.0, "unit_cost":50.0, "overdraft":false, "description":null, "api_key":"001", "warehouse_name":"WH2", "equipment_unit_number":"001", "equipment_type":"4-Gas Monitor", "custom_fields":{}}]
-The upper section of the response will be defined if you created an issuance directly to an equipment.
-The lower section is defined if you created an issuance to a work order number and task name combination.
-If you define BOTH an equipment_unit_number
as well as a work_order_sequential_id and task_name combination, the issuance to the equipment_unit_number takes precedence and no issuance will be created to the work order / task name combination
Issuances can be deleted via a DELETE request to the /issuance/api_key
endpoint, where “api_key” is replaced by the api_key
of the Issuance to be deleted. A single DELETE request is sufficient to delete all Issuances associated with that api_key
if multiple Issuances were created across different receipts.
Endpoint:
https://www.mtcproweb.com/api/v1/mpw/issuance/api_key
Here’s an example of a DELETE /issuance
request, along with the response:
curl -X https://www.mtcproweb.com/api/v1/mpw/issuance/12ABC -H "Authorization: Bearer (access token)"
Response:
{"api_key":"12ABC"}
Receipts - GET
The /receipts API returns an array of JSON objects describing inventory Receipts within MPW via a GET request to the following endpoint:
https://www.mtcproweb.com/api/v1/mpw/receipts
The following parameters are supported in the GET JSON object:
Parameter | Required | Format |
---|---|---|
date |
Yes | String ISO YYYY-MM-DD |
api_key |
Yes | String - required unless date is provided. The api_key is a unique key that you must provide to uniquely identify any Receipts that you create via MPW-API |
vendor_name |
No | String - must be an exact match of an existing Vendor |
vendor_number |
No | String - must be an exact match of an existing Vendor |
part_number |
No | String - must be an exact match of an existing Part in the Inventory |
Here’s an example of a GET /receipts
request, along with the response:
curl -H 'Accept: application/json' -H "Authorization: Bearer (access token) " https://www.mtcproweb.com/api/v1/mpw/receipts?date=2020-09-28
Response:
[ {"id":236252, "part_number":"51503", “inventory_name”:”part name”, "created_on":"2020-09-28", "invoice_number":null, "quantity_received":1.0, "quantity_remaining":1.0, "unit_cost":11.3, "description":”receipt description field content”, "vendor_name":null, "vendor_number":null, "api_key":null, "purchase_order_number":1000, "purchase_order_prefix_number":"1000", "warehouse_name":"Warehouse #1"} ]
New Inventory may be added to stock within MPW via a POST to the /receipts
endpoint. The parameters posted must be a JSON object as follows, with required fields.
Endpoint:
https://www.mtcproweb.com/api/v1/mpw/receipts
The following parameters are supported in the POST JSON object:
Parameter | Required | Format |
---|---|---|
part_number |
Yes | String |
quantity_received |
Yes | Integer or Float |
unit_cost |
Yes | Integer or Float |
created_on |
Yes | String ISO YYYY-MM-DD |
api_key |
Yes | String |
warehouse_name |
Yes | String - Must be an exact match |
vendor_name |
No | String |
tax_rate_one |
No | Integer or Float |
tax_rate_two |
No | Integer or Float |
invoice_number |
No | String |
inventory_api_key |
No | String |
Parameter Notes:
- The
warehouse_name
parameter must refer to a Warehouse that contains the specified Inventory. - Either
vendor_name
orvendor_number
may be used to identify a Vendor for a new Receipt. - Pay attention to parameter types; quoted strings above should be sent as strings, while numeric values should not be quoted and should be sent as integer or floating point values
- You're able to insert a NEW parts inventory item at the same time you create the initial receipt for it. If the
warehouse_name
andpart_number
combination passed along do not match an existing inventory item, we will create a NEW parts inventory item and use theinventory_api_key
An existing Receipt will be identified and updated based upon the supplied api_key
. If no existing Receipt exists for the supplied api_key
, a new Receipt will be created. The api_key
is a value generated and assigned to the receipt you post, and it can be used to post an update to an existing receipt - for instance, if you added a receipt but had the wrong quantity, you could use the api_key
and in this instance you would be altering the receipt instead of inserting a new one. This can only be done when no quantity from the receipt has been used on a work order yet. For instance, if I posted a receipt with a quantity of 10 but it should have been 9, I can re-post with that api_key
I had created and update the receipt quantity to 9. If you try to do this and something has already been used off of the receipt in MP Web, you get a message:
"message":"Receipt found but cannot be updated. Check to ensure that parts have not already been allocated from this Receipt, and that your user account has the necessary permissions to update Receipts."
A successful post will return a JSON object with the newly-created or updated Receipt. Here’s an example of a /receipt
POST, and the response:
curl -v \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer (access token)" \ -d '{"receipt":{"part_number":"1233","quantity_received":1.25,"unit_cost":1.99,"created_on":"2020-09-29","api_key":"1"}}' \ https://www.mtcproweb.com/api/v1/mpw/receipts
Response:
{"id":236255, "Organization_id":3305, "inventory_id":252212, "Warehouse_id":6289, "Vendor_id":null, "Part_number":"1233", "Created_on":"2020-09-29", "Invoice_number":null, "Quantity_received":1.25, "Quantity_remaining":1.25, "Unit_cost":1.99, "Description":null, "Vendor_name":null, "Vendor_number":null, "Api_key":"1", "purchase_order_number":null, "Purchase_order_prefix_number":"", "warehouse_name":"Warehouse #1"}
Receipts can be deleted via a DELETE request to the /receipt/api_key
endpoint, where “api_key” is replaced by the api_key
of the Receipt to be deleted.
Endpoint:
https://www.mtcproweb.com/api/v1/mpw/receipt/api_key
Here’s an example of a DELETE /receipt
request, along with the response:
curl -X https://www.mtcproweb.com/api/v1/mpw/receipt/12A -H "Authorization: Bearer (access token)"
Response:
{"api_key":"12A"}
The /inventories
API returns an array of JSON objects describing Inventory within MPW via a GET request to the following endpoint:
Endpoint:
https://www.mtcproweb.com/api/v1/mpw/inventories
The following parameters are supported:
Parameter | Required | Format |
---|---|---|
warehouse_name |
Yes | String |
part_number |
Yes | Integer or Float |
api_key |
Yes | Integer or Float |
Parameter Notes:
warehouse_name
: REQUIRED unlessapi_key
is providedpart_number
: REQUIRED unlessapi_key
is providedapi_key
: REQUIRED unlesswarehouse_name
andpart_number
are provided. Theapi_key
is a unique key that you must provide to uniquely identify any Inventory that you create via MPW-API.
Here’s an example of an /inventories
GET, and the response:
curl -H 'Accept: application/json' -H "Authorization: Bearer eyJhbGouVxlY " https://www.mtcproweb.com/api/v1/mpw/inventories?api_key=45
Response:
[{"id":279367, "part_number":"1112", "api_key":"45", "inventory_name":null, "warehouse_name":"Warehouse #1", "bin":null, "category":null, "unit_type":null, "description":null, "quantity":0.0, "reorder_quantity":0.0, "low_stock_level":0.0, "unit_cost":1.99, "tracking_enabled":true}]
New Inventory may be added to MPW via a POST to the /inventories
endpoint. The parameters posted must be a JSON object as follows:
Endpoint:
https://www.mtcproweb.com/api/v1/mpw/inventories
The following parameters are supported in the POST JSON object:
Parameter | Required | Format |
---|---|---|
part_number |
Yes | String |
warehouse_name |
Yes |
String - Must be an exact match |
api_key |
Yes | String |
inventory_name |
No |
String |
bin |
No |
String |
category |
No |
String |
unit_type |
No | String |
description |
No | String |
quantity |
No | Integer or Float |
reorder_quantity |
No | Integer or Float |
low_stock_level |
No | Integer or Float |
unit_cost |
No | Integer or Float |
tracking_enabled |
No | Boolean |
Parameter Notes:
- The parameter
tracking_enabled
must be specified as the string “true
” for inventory tracking to be enabled. - The numeric fields
quantity
andunit_cost
are intended to provide baseline stock level information for newly-created inventory. Instead of updating these parameters, create new Receipts to track quantity and price of new inventory. - The reorder tracking fields
reorder_quantity
andlow_stock_level
can be updated through the API.
An existing Inventory object will be identified and updated based upon the supplied api_key
. If no existing Inventory exists for the supplied api_key
, a new Inventory object will be created.
A successful post will return a JSON object with the newly-created or updated Inventory. Below is an example of an inventories
POST, and the response.
curl -v \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1aTouVxlY" \ -d '{"inventory": { "part_number":"1112", "quantity_received":1.00, "unit_cost":1.99, "warehouse_name":"Warehouse #1", "api_key":"45" } }' \ https://www.mtcproweb.com/api/v1/mpw/inventories
Response:
{"id":279366, "part_number":"1111", "api_key":"", "inventory_name":null, "organization_id":3384, "warehouse_id":6614, "warehouse_name":"Warehouse #1", "bin":null, "category":null, "unit_type":null, "description":null, "quantity":0.0, "reorder_quantity":0.0, "low_stock_level":0.0, "unit_cost":1.99, "tracking_enabled":true}
Inventory may be transferred between Warehouses in a single transaction via a POST to the /inventory_transfers
endpoint. The parameters posted must be a JSON object as follows:
Endpoint:
https://www.mtcproweb.com/api/v1/mpw/inventory_transfers
The following parameters are supported in the POST JSON object:
Parameter | Required | Format |
---|---|---|
part_number |
Yes | String |
warehouse_name |
Yes |
String - Must be an exact match |
destination_warehouse_name |
Yes | String |
quantity |
Yes |
Integer |
Parameter Notes:
- The
warehouse_name
parameter must refer to a Warehouse that contains the specified Inventory. - If Inventory does not already exist in the destination Warehouse, it will be created automatically.
- The quantity transferred cannot exceed the amount available in the current Receipt. An error message will specify this maximum amount.
A successful post will return a JSON object with the newly-created Transfer. Below is an example of an inventory_transfers
POST, and the response.
curl -v \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer (api token)." \ -d '{"inventory_transfer":{"part_number":"000global","warehouse_name":"Totally New Warehouse","destination_warehouse_name":"WH2","quantity":"2.0"}}' \https://www.mtcproweb.com/api/v1/mpw/inventory_transfers
Response:
[{"id":279663, "part_number":"000global", "api_key":null, "inventory_name":null, "organization_id":3305, "warehouse_id":6710, "warehouse_name":"Totally New Warehouse", "bin":null, "category":null, "unit_type":"Each", "description":"", "quantity":23.0, "reorder_quantity":0.0, "low_stock_level":0.0, "unit_cost":0.0, "tracking_enabled":true}, {"id":279670, "part_number":"000global", "api_key":null, "inventory_name":null, "organization_id":3305, "warehouse_id":6713, "warehouse_name":"WH2", "bin":null, "category":null, "unit_type":"Each", "description":"", "quantity":2.0, "reorder_quantity":0.0, "low_stock_level":0.0, "unit_cost":0.0, "tracking_enabled":true}]
Equipment - GET
The /gps_meter_updates
API returns an array of JSON objects describing several equipment attributes, along with the last GPS meter reading date, within MPW via a GET request to the following endpoint:
https://www.mtcproweb.com/api/v1/mpw/gps_meter_updates
The following parameters are supported:
Parameter | Required | Format |
---|---|---|
gps_provider |
Yes | String - The exact matching name of the GPS provider (from your organization's GPS integration list) for which you're querying data (for example, Geotab would match results, but Geo Tab would not). |
name |
No | String - Must be an exact match of the name of an existing equipment in MP Web |
serial_number |
No | String -Must be an exact match of the serial number of an existing equipment in MP Web |
gps_key |
No | Integer - Must be an exact match of the name of a gps_key of an existing equipment in MP Web |
Here’s an example of a GET /gps_meter_updates
request, along with the response:
curl -H 'Accept: application/json' -H "Authorization: Bearer eyJhbGciOiJIUz" 'https://www.mtcproweb.com/api/v1/mpw/gps_meter_updates?gps_provider=Geotab'
Response:
[ {"id":282774, "last_recorded_on":"2019-12-10", "name":"STX-333 KW Hydro", "status":"Active", "category_name":"General Use", "assignee_name":"Roger Daniels", "assignee_number":"330"} ]
Work Orders- GET
The /work_orders
API returns an array of JSON objects describing work orders and their details from MPW via a GET request to the following endpoint:
https://www.mtcproweb.com/api/v1/mpw/work_orders
The following parameters are supported:
Parameter | Required | Format |
---|---|---|
start_on_from |
Yes | String ISO YYYY-MM-DD |
start_on_to |
Yes | String ISO YYYY-MM-DD |
scheduled_on_from |
Yes | String ISO YYYY-MM-DD |
scheduled_on_to |
Yes | String ISO YYYY-MM-DD |
due_on_from |
Yes | String ISO YYYY-MM-DD |
due_on_to |
Yes | String ISO YYYY-MM-DD |
completed_on_from |
Yes | String ISO YYYY-MM-DD |
completed_on_to |
Yes | String ISO YYYY-MM-DD |
status |
No | String - Must be an exact match of a work order Status in MP Web |
Parameter Notes:
- The _from and _to for a parameter type (Start Date, Scheduled Date, Due Date, Completed Date) are both required and represent the timespan you are requesting work orders between. For instance, if you wanted to GET Work Orders scheduled between July 25 and July 30 2023 you'd use the query presented below.
Here’s an example of a GET /work_orders
request, along with the response:
curl -H 'Accept: application/json' -H "Authorization: Bearer x3k4gJYkcynxrGM" 'https://www.mtcproweb.com/api/v1/mpw/work_orders?scheduled_on_from=2023-07-25&scheduled_on_to=2023-07-30'
Response:
{"work_orders": [{"sequential_id":1234567996, "prefix_title":"1234567996", "category_name":"Diagnostic Equip", "location_name":"ATS","start_at":null, "due_on":"2023-07-25", "scheduled_on":"2023-07-25", "completed_at":null, "percent_complete":0, "assignee_name":"Jack Mako", "second_assignee_name":"", "equipment_name":"001", "equipment_title":"001 001 - 2010 ABC", "status":"Open", "priority":"NORMAL", "downtime_hours":null, "custom_fields":{}, "parts_cost":0.0, "labor_cost":0.0, "custom_cost_one":0.0, "custom_cost_two":0.0, "custom_cost_three":0.0, "subtotal":0.0, "tax_rate_one":0.0, "tax_rate_two":0.0, "tax_one_cost":0.0, "tax_two_cost":0.0, "credit_amount":0.0, "tax_cost":0.0, "total_cost":0.0, "tasks": [{"id":425994, "name":"repair3", "task_type":"Repair", "completed_at":null, "note":null, "task_notes":null}] }], "pagination":{"page":1,"pageSize":100,"pageCount":1,"count":1}}
The /purchase_orders
API returns an array of JSON objects describing purchase orders and their details from MPW via a GET request to the following endpoint:
https://www.mtcproweb.com/api/v1/mpw/purchase_orders
Parameter | Required | Format |
---|---|---|
created_on_from |
Yes | String ISO YYYY-MM-DD |
created_on_to |
Yes | String ISO YYYY-MM-DD |
required_on_from |
Yes | String ISO YYYY-MM-DD |
required_on_to |
Yes | String ISO YYYY-MM-DD |
completed_on_from |
Yes | String ISO YYYY-MM-DD |
completed_on_to |
Yes | String ISO YYYY-MM-DD |
status |
No | String - Must be an exact match of a purchase order Status in MP Web |
- The _from and _to for a parameter type (Created Date, Required Date, Completed Date) are both required and represent the timespan you are requesting purchase orders between. For instance, if you wanted to GET Purchase Orders Required between September 12 and September 17 2024 you'd use the query presented below.
curl -H 'Accept: application/json' -H "Authorization: Bearer x3k4gJYkcynxrGM" 'https://www.mtcproweb.com/api/v1/mpw/purchase_orders?required_on_from=2024-09-12&required_on_to=2024-09-17'
{"purchase_orders": [{"sequential_id":1000, "prefix_title":"1000", "status":"requisition", "created_on":"2024-09-17", "required_on":"2024-09-18", "terms":"NET 30", "ship_via":"ground", "invoice_number":"sample invoice no", "work_order_sequential_id":null, "subtotal":585.0, "tax_rate_one":0.0, "tax_rate_two":0.0, "tax_one_cost":0.0, "tax_two_cost":0.0, "freight_cost":0.0, "total_cost":585.0, "completed_on":null, "notes":"PO Notes", "custom_fields": {"cust field 1 label":"cust field 1 value", "cust field 2 label":"cust field 2 value"}, "tax_cost":0.0, "buyer_name":"John Smith", "vendor_name":"Bosch", "warehouse_name":"Warehouse #1", "vendor_number":null, "work_order_prefix_title":"", "items": [ {"id":51212, "quantity":5.0, "quantity_received":0.0, "unit_cost":7.0, "extended_cost":35.0, "part_number":"000000", "name":"Frame Rail Fuel Filter", "category":"Filter", "manufacturer":"Manufacturer Name Example", "unit_type":"Each", "description":"description of part", "taxes":"Both", "supplier_part_number":"AlternateVendorPartNo", "note":null}, {"id":51213, "quantity":50.0, "quantity_received":0.0, "unit_cost":10.0, "extended_cost":500.0, "part_number":"99999", "name":"Oil", "category":"Fluids", "manufacturer":"Manufacturer Name Example", "unit_type":"Gallon", "description":"Desc of Oil", "taxes":"Both", "supplier_part_number":"AlternateVendorPartNo2", "note":null}] }],"pagination":{"page":1,"pageSize":100,"pageCount":1,"count":1}}%
Multiple Purchase Orders can have their status set to "Ordered" in a single transaction via a POST to the /purchase_orders/approve
endpoint. The parameters posted must be a JSON object as follows:
Endpoint:
https://www.mtcproweb.com/api/v1/mpw/purchase_orders/approve
The following parameters are supported in the POST JSON object:
Parameter | Required | Format |
---|---|---|
purchase_order_numbers |
Yes | Integer |
Parameter Notes:
Up to 50 purchase order numbers may be sent separated by a comma
A successful post will return a JSON object with the newly-created Transfer. Below is an example of an inventory_transfers
POST, and the response.
curl -v \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer eyJhbWC3A" \ -d '{"purchase_order_numbers":"1000"}' \https://www.mtcproweb.com/api/v1/mpw/purchase_orders/approve
Response:
{"results":{"purchase_order_numbers":[1000],"errors":[]}}%