Upkeep PDF

6/5/2019 Introduction – UpKeep API Reference
Introduction
Authentication
Users
Customers
Vendors
Create a Vendor
Get All Vendors
Get a Specific Vendor
Update a Specific Vendor
Teams
Create a Team
Get All Teams
Get a Specific Team
Update a Specific Team
Delete a Specific Team
Get All Users for a Specific Team
Add User to a Specific Team
Removes User from a Specific Team
Assets
Locations
Parts
Create a Part
Get All Parts
Get a Specific Part
Update a Specific Part
Delete a Specific Part
Requests
Create a Request
Get All Requests
Get a Specific Request
Cancel a Specific Request
Delete a Specific Request
Work Orders
Preventative Maintenance
Work Order Schedule
Get The Schedule of Preventative Maintenance Work Orders
Meters
Purchase Orders
Purchase Order Category
Reporting (BETA)
Common Use Cases
developers.onupkeep.com 1/86
Errors
Introduction
Welcome to the UpKeep API! You can use our API to control and gain access to data such as work orders and assets.
The UpKeep API is enabled only for accounts on the Business Plus Plan or Enterprise Plan. For more information click here.
Authentication
The UpKeep API uses session tokens to authorize API calls. Session tokens can be generated with the credentials of any user in your
account.
Log In
curl "https://api.onupkeep.com/api/v2/auth"
-X POST
-d email="user@onupkeep.com"
-d password="password"
The above command returns JSON structured like this:
{
"success": true,
"result": {
"sessionToken": "r:4a25eddbf5aj42jk323f1472724hc43f",
"expiresAt": "2018-12-31T00:00:00.000Z"
}
}
This endpoint returns a session token for a valid email and password.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/auth/
REQUEST BODY
Provide a valid email and password.
Parameter Type Required
email String true
password String true
Log Out
curl "https://api.onupkeep.com/api/v2/auth"
-X DELETE
-H "Session-Token: session_token_here"
{
"success": true,
"message": "session deleted"
}
This endpoint invalidates an existing session.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/auth/
Users
Create a User
curl "https://api.onupkeep.com/api/v2/users/"
-X POST
-d password="mypassword"
-d accountType="ADMIN"
-d firstName="Marty"
-d lastName="McFly"
-d phoneNumber="800-123-4567"
{
"success": true,
"result": {
"id": "fjQXLsOvG7",
"accountType": "ADMIN",
"email": "user@onupkeep.com",
"firstName": "Marty",
"lastName": "McFly",
"phoneNumber": "800-123-4567",
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
}
This endpoint creates a new user.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/users/
REQUEST BODY
Provide any of the below required fields and optional fields for the user.
Parameter Type Required Description
email String true
accountType String true must be one of the following: ADMIN, TECH, VIEW_ONLY, REQUESTER, LIMITED_TECH
password String true
firstName String false
lastName String false
phoneNumber String false
Get All Users
curl "https://api.onupkeep.com/api/v2/users/"
-X GET
{
"success": true,
"results": [
{
"id": "fjQXLsOvG7",
"phoneNumber": "800-123-4567",
"userStatus": "on call",
"jobTitle": "Manager",
"dateOfLastLogin": "2018-05-22T03:05:27.262Z",
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
]
}
This endpoint retrieves all users for your account.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/users/
QUERY PARAMETERS
Parameter Default Description
email undefined If set the result will only include user with that email.
offset undefined (Number) offset for pagination.
limit undefined (Number) limit for pagination.
createdAt (String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or
orderBy
DESC "DESC".
Get a Specific User
curl "https://api.onupkeep.com/api/v2/users/<ID>"
-X GET
{
"success": true,
"result": {
"id": "fjQXLsOvG7",
"phoneNumber": "800-123-4567",
"userStatus": "on call",
"jobTitle": "Manager",
"dateOfLastLogin": "2018-05-22T03:05:27.262Z",
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
}
This endpoint retrieves a specific user.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/users/<ID>
URL PARAMETERS
Parameter Description
ID The ID of the user to retrieve
Update a Specific User
-X PATCH
-d firstName="Doc"
{
"success": true,
"result": {
"id": "fjQXLsOvG7",
"phoneNumber": "800-123-4567",
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
}
This endpoint updates a specific user.
HTTP REQUEST
PATCH https://api.onupkeep.com/api/v2/users/<ID>
URL PARAMETERS
ID The ID of the user to retrieve
REQUEST BODY
Provide any of the below fields of the user in the payload to update those specific fields. Null values are allowed to erase the value unless
otherwise stated.
email String false
accountType String false
firstName String false
lastName String false
Customers
Create a Customer
curl "https://api.onupkeep.com/api/v2/customers/"
-X POST
-d name="Mark Boucher"
-d description="A1 sevices manager"
-d address="421 E Drachman, Hudson Street"
-d website="www.aoneserv.com"
-d type="Daily-User"
-d billingName="Mark Boucher Sr"
-d billingAddressLine1="345 B"
-d billingAddressLine2="Jackson Street"
-d billingAddressLine3="CA"
{
"success": true,
"result": {
"id": "fjQXLsOvG7",
"name": "Mark Boucher",
"description": "A1 sevices manager",
"address": "421 E Drachman, Hudson Street",
"phoneNumber": "800-123-4567",
"website": "www.aoneserv.com",
"type": "Daily-User",
"billingName": "Mark Boucher Sr",
"billingAddressLine1": "345 B",
"billingAddressLine2": "Jackson Street",
"billingAddressLine3": "CA",
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
}
This endpoint creates a new customer.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/customers/
REQUEST BODY
Provide any of the below required fields and optional fields for the customer.
name String true
email String false
description String false
address String false
website String false
type String false
billingName String false
billingAddressLine1 String false
Get All Customers
curl "https://api.onupkeep.com/api/v2/customers/"
-X GET
{
"success": true,
"results": [
{
"id": "fjQXLsOvG7",
"phoneNumber": "800-123-4567",
"customFieldsCustomer": [
{
"id": "fjQXLsOvG7",
"name": "Title",
"value": "Manager",
"createdByUser": "lv6FZopMhz",
"updatedByUser": "lv6FZopMhz",
"customer": "fjQXLsOvG7",
"createdAt": "2018-03-20T05:47:32.690Z",
"updatedAt": "2018-03-20T05:47:32.690Z"
}
],
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
]
}
This endpoint retrieves all customers for your account.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/customers/
QUERY PARAMETERS
name undefined If set the result will only include users with that name.
orderBy
DESC "DESC".
Get a Specific Customer
curl "https://api.onupkeep.com/api/v2/customers/<ID>"
-X GET
{
"success": true,
"result": {
"id": "fjQXLsOvG7",
"phoneNumber": "800-123-4567",
"customFieldsCustomer": [
{
"id": "fjQXLsOvG7",
"name": "Title",
"value": "Manager",
"customer": "fjQXLsOvG7",
"createdAt": "2018-03-20T05:47:32.690Z",
"updatedAt": "2018-03-20T05:47:32.690Z"
}
],
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
}
This endpoint retrieves a specific customer.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/customers/<ID>
URL PARAMETERS
ID The ID of the customer to retrieve
Update a Specific Customer
curl "https://api.onupkeep.com/api/v2/customer/<ID>"
-X PATCH
-d name="Rob"
{
"success": true,
"result": {
"id": "fjQXLsOvG7",
"name": "Rob",
"phoneNumber": "800-123-4567",
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
}
This endpoint updates a specific customer.
HTTP REQUEST
PATCH https://api.onupkeep.com/api/v2/customers/<ID>
URL PARAMETERS
ID The ID of the customer to update
REQUEST BODY
Provide any of the below fields of the customer in the payload to update those specific fields. Null values are allowed to erase the value
unless otherwise stated.
name String false
email String false
type String false
billingName String false
Vendors
Create a Vendor
curl "https://api.onupkeep.com/api/v2/vendors/"
-X POST
-d businessName="AVC Inc."
-d description="A1 sevices manager"
-d businessAddress="421 E Drachman, Hudson Street"
-d website="www.aoneserv.com"
-d type="Raw-Material"
-d mainPointOfContact="Mark Boucher"
{
"success": true,
"result": {
"id": "fjQXLsOvG7",
"businessName": "AVC Inc.",
"businessAddress": "421 E Drachman, Hudson Street",
"phoneNumber": "800-123-4567",
"type": "Raw-Material",
"mainPointOfContact": "Mark Boucher",
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
}
This endpoint creates a new vendor.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/vendors/
REQUEST BODY
Provide any of the below required fields and optional fields for the vendor.
businessName String true
email String false
businessAddress String false
type String false
mainPointOfContact String false
Get All Vendors
curl "https://api.onupkeep.com/api/v2/vendors/"
-X GET
{
"success": true,
"results": [
{
"id": "fjQXLsOvG7",
"phoneNumber": "800-123-4567",
"customFieldsVendor": [
{
"id": "4mFPJFLwxa",
"name": "Title",
"value": "Manager",
"vendor": "fjQXLsOvG7",
"createdAt": "2018-03-20T05:53:25.017Z",
"updatedAt": "2018-03-20T05:53:25.017Z"
}
],
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
]
}
This endpoint retrieves all vendors for your account.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/vendors/
QUERY PARAMETERS
businessName undefined If set the result will only include vendors with that businessName.
orderBy
DESC "DESC".
Get a Specific Vendor
curl "https://api.onupkeep.com/api/v2/vendors/<ID>"
-X GET
{
"success": true,
"result": {
"id": "fjQXLsOvG7",
"phoneNumber": "800-123-4567",
"customFieldsVendor": [
{
"id": "4mFPJFLwxa",
"name": "Title",
"value": "Manager",
"vendor": "fjQXLsOvG7",
"createdAt": "2018-03-20T05:53:25.017Z",
"updatedAt": "2018-03-20T05:53:25.017Z"
}
],
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
}
This endpoint retrieves a specific vendor.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/vendors/<ID>
URL PARAMETERS
ID The ID of the vendors to retrieve
Update a Specific Vendor
curl "https://api.onupkeep.com/api/v2/vendors/<ID>"
-X PATCH
-d businessName="Doc Inc"
{
"success": true,
"result": {
"id": "fjQXLsOvG7",
"businessName": "Doc Inc.",
"phoneNumber": "800-123-4567",
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
}
This endpoint updates a specific vendor.
HTTP REQUEST
PATCH https://api.onupkeep.com/api/v2/vendors/<ID>
URL PARAMETERS
ID The ID of the vendor to update
REQUEST BODY
Provide any of the below fields of the vendor in the payload to update those specific fields. Null values are allowed to erase the value unless
otherwise stated.
businessName String false
email String false
businessAddress String false
type String false
mainPointOfContact String false
Teams
Create a Team
curl "https://api.onupkeep.com/api/v2/teams/"
-X POST
-d name="Maintenance Team"
{
"success": true,
"result": {
"name": "Team Doc",
"description": "Marty! I need you to go back with me! Back to the future!",
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
}
This endpoint creates a new team.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/teams/
REQUEST BODY
Provide any of the below required fields and optional fields for the team.
name String true
description String true
Get All Teams
curl "https://api.onupkeep.com/api/v2/teams/"
-X GET
{
"success": true,
"results": [
{
"id": "fjQXLsOvG7",
"name": "Team Doc",
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
]
}
This endpoint retrieves all teams for your account.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/teams/
QUERY PARAMETERS
name undefined If set the result will only include teams with that name.
orderBy
DESC "DESC".
Get a Specific Team
curl "https://api.onupkeep.com/api/v2/teams/<ID>"
-X GET
{
"success": true,
"result": {
"id": "fjQXLsOvG7",
"name": "Team Doc",
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
}
This endpoint retrieves a specific team.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/teams/<ID>
URL PARAMETERS
ID The ID of the team to retrieve
Update a Specific Team
-X PATCH
-d name="Team Marty"
{
"success": true,
"result": {
"id": "fjQXLsOvG7",
"name": "Team Marty",
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
}
This endpoint updates a specific team.
HTTP REQUEST
PATCH https://api.onupkeep.com/api/v2/teams/<ID>
URL PARAMETERS
REQUEST BODY
Provide any of the below fields of the team in the payload to update those specific fields. Null values are allowed to erase the value unless
otherwise stated.
name String true
description String true
Delete a Specific Team
curl "https://api.onupkeep.com/api/v2/teams/<ID>"
-X DELETE
{
"success": true,
"message": "1 team deleted"
}
This endpoint deletes a specific team.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/teams/<ID>
URL PARAMETERS
Get All Users for a Specific Team
curl "https://api.onupkeep.com/api/v2/teams/<teamID>/users"
-X GET
{
"success": true,
"results": [
{
"id": "fjQXLsOvG7",
"phoneNumber": "800-123-4567",
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
]
}
This endpoint retrieves all users for a specific team.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/teams/<teamID>/users
URL PARAMETERS
teamID The ID of the team to retrieve
Add User to a Specific Team
curl "https://api.onupkeep.com/api/v2/teams/<teamID>/users/<userID>"
-X POST
{
"success": true,
"message": "1 user added to team <teamID>"
}
This endpoint adds users for a specific team.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/teams/<teamID>/users/<userID>
URL PARAMETERS
teamID The ID of the desired team
userID The ID of the user to add to the team
Removes User from a Specific Team
curl "https://api.onupkeep.com/api/v2/teams/<teamID>/users/<userID>"
-X DELETE
{
"success": true,
"message": "1 user removed from team <teamID>"
}
This endpoint removes users for a specific team.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/teams/<teamID>/users/<userID>
URL PARAMETERS
teamID The ID of the desired team
userID The ID of the user to remove from the team
Assets
Create an Asset
curl "https://api.onupkeep.com/api/v2/assets/"
-X POST
-d name="The Deluxe Power Generator"
-d UPCNumber="S5614B09118"
-d model="Deluxe 5500"
{
"success": true,
"result": [
{
"id": "fjQXLsOvG7",
"UPCNumber": "S5614B09118",
"additionalInformation": "2 feet by 2 feet",
"model": "Deluxe 5500",
"name": "The Ultra Power Generator",
"notes": "Oldest generator in use",
"serial": "1234567",
"location": "OPkIOYYZ0F",
"image": {
"name": "image_generator_001.jpg",
"url": "https://upkeep-production.s3.amazonaws.com/image_generator_001.jpg"
},
"status": "active",
"description": "The Generator Powering Life Support for the Space Station",
"category": "Generators",
"assignedToUsername": "abc@def.com",
"assignedToUser": "BZuHycQMog",
"createdByUsername": "zys@abce.com",
"createdByUser": "DNbSREeodF",
"updatedAt": "2017-11-16T15:01:01",
"createdAt": "2017-11-16T15:01:01"
}
]
}
This endpoint creates a new asset.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/assets/
REQUEST BODY
Provide any of the below required fields and optional fields for the asset.
UPCNumber String false
additionalInformation String false
model String false
name String true
notes String false
serial String false
location String (ID) false
status String; "active" or "inactive" false
category String, one of the set categories on your UpKeep account false
assignedToUser String, the ID of the user object to assign to false
Get All Assets
curl "https://api.onupkeep.com/api/v2/assets"
{
"success": true,
"results": [
{
"id": "fjQXLsOvG7",
"numberOfIncompleteWorkOrders": 55,
"serial": "1234567",
"image": {
},
"status": "active",
"checkInProcedure": "Connect generator",
"checkOutProcedure": "Disconnect Generator",
"availabilityStatus": "available",
"downtimeStatus": "available",
"availabilityTrackingOn": true,
"updatedAt": "2017-11-16T15:01:01",
"createdAt": "2017-11-16T15:01:01"
}
]
}
This endpoint retrieves all assets for your account.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/assets
QUERY PARAMETERS
name undefined If set, the result will only include assets with that name.
UPCNumber undefined If set, the result will only include assets with this UPCNumber.
model undefined If set, the result will only include assets with this model.
serial undefined If set, the result will only include assets with this serial number.
location undefined (ID) If set, the result will only include assets belonging to this location.
status undefined If set, the result will only include assets with this status.
category undefined If set, the result will only include assets with this category.
assignedToUser undefined (ID) If set, the result will only include assets assigned to this user.
createdByUser undefined (ID) If set, the result will only include assets created by this user.
includes undefined (Array) send 'location','assignedToUser', 'createdByUser' to expand respective object
createdAt (String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC"
orderBy
DESC or "DESC".
Get a Specific Asset
curl "https://api.onupkeep.com/api/v2/assets/fjQXLsOvG7"
{
"success": true,
"result": [
{
"id": "fjQXLsOvG7",
"serial": "1234567",
"image": {
},
"status": "active",
"checkInProcedure": "Connect generator",
"checkOutProcedure": "Disconnect Generator",
"availabilityStatus": "available",
"downtimeStatus": "available",
"availabilityTrackingOn": true,
"subAssets": [
"z40xOYM9yd"
],
"parts": [
"ydOS2PdR3a"
],
"files": [
"sKrlT2f3mf",
"Vgwf41LLg1"
],
"formItems": [
"Ia536KS4RZ"
],
"customFieldsAsset": [
{
"id": "AI5uBGp7nz",
"name": "Width",
"value": "10",
"asset": "fjQXLsOvG7",
"unit": "cm",
"createdAt": "2018-03-20T06:54:48.325Z",
"updatedAt": "2018-03-20T06:54:48.325Z"
}
],
"updatedAt": "2017-11-16T15:01:01",
"createdAt": "2017-11-16T15:01:01"
}
]
}
This endpoint retrieves a specific asset.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/assets/<ID>
URL PARAMETERS
ID The ID of the asset to retrieve
QUERY PARAMETERS
(Array) send 'location','assignedToUser', 'createdByUser', 'assignedUsers', 'assignedTeams',

includes undefined
'assignedCustomers', 'assignedVendors to expand respective object.
Update a Specific Asset
curl "https://api.onupkeep.com/api/v2/assets/fjQXLsOvG7"
-X PATCH
-d name="The Amazing Power Generator"
{
"success": true,
"result": [
{
"id": "fjQXLsOvG7",
"name": "The Amazing Power Generator",
"serial": "1234567",
"image": {
},
"status": "active",
"updatedAt": "2017-11-16T15:01:01",
"createdAt": "2017-11-16T15:01:01"
}
]
}
This endpoint updates a specific asset.
HTTP REQUEST
PATCH https://api.onupkeep.com/api/v2/assets/<ID>
URL PARAMETERS
ID The ID of the asset to update
REQUEST BODY
Provide any of the below fields of the asset in the payload to update those specific fields. Null values are allowed to erase the value unless
otherwise stated.
Parameter Type
UPCNumber String
additionalInformation String
model String
name String
notes String
serial String
location String (ID)
Parameter Type
status String; "active" or "inactive"
description String
category String, one of the set categories on your UpKeep account
assignedToUser String, the ID of the user object to assign to
Delete a Specific Asset
curl "https://api.onupkeep.com/api/v2/assets/jQXLsOvG7"
-X DELETE
{
"success": true,
"message": "1 asset deleted"
}
This endpoint deletes a specific asset
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/assets/<ID>
URL PARAMETERS
ID The ID of the asset to delete
Assign User to an Asset
curl "https://api.onupkeep.com/api/v2/assets/<assetID>/users/<userID>"
-X POST
{
"success": true,
"message": "user <userID> assigned to asset <assetID>"
}
This endpoint assigns user to a specific asset.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/assets/<assetID>/users/<userID>
URL PARAMETERS
assetID The ID of the desired asset
userID The ID of the user to be assigned to asset.
Remove Assigned User from an Asset
curl "https://api.onupkeep.com/api/v2/assets/<assetID>/users/<userID>"
-X DELETE
{
"success": true,
"message": "user <userID> removed from asset <assetID>"
}
This endpoint removes assigned user from a specific asset.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/assets/<assetID>/users/<userID>
URL PARAMETERS
userID The ID of the user to be removed from asset.
Assign Team to an Asset
curl "https://api.onupkeep.com/api/v2/assets/<assetID>/teams/<teamID>"
-X POST
{
"success": true,
"message": "team <teamID> assigned to asset <assetID>"
}
This endpoint assigns team to a specific asset.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/assets/<assetID>/teams/<teamID>
URL PARAMETERS
teamID The ID of the team to be assigned to asset.
Remove Assigned Team from an Asset
curl "https://api.onupkeep.com/api/v2/assets/<assetID>/teams/<teamID>"
-X DELETE
{
"success": true,
"message": "team <teamID> removed from asset <assetID>"
}
This endpoint removes assigned team from a specific asset.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/assets/<assetID>/teams/<teamID>
URL PARAMETERS
teamID The ID of the team to be removed from asset.
Assign Customer to an Asset
curl "https://api.onupkeep.com/api/v2/assets/<assetID>/customers/<customerID>"
-X POST
{
"success": true,
"message": "customer <customerID> assigned to asset <assetID>"
}
This endpoint assigns customer to a specific asset.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/assets/<assetID>/customers/<customerID>
URL PARAMETERS
customerID The ID of the customer to be assigned to asset.
Remove Assigned Customer from an Asset
curl "https://api.onupkeep.com/api/v2/assets/<assetID>/customers/<customerID>"
-X DELETE
{
"success": true,
"message": "customer <customerID> removed from asset <assetID>"
}
This endpoint removes assigned customer from a specific asset.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/assets/<assetID>/customers/<customerID>
URL PARAMETERS
customerID The ID of the customer to be removed from asset.
Assign Vendor to an Asset
curl "https://api.onupkeep.com/api/v2/assets/<assetID>/vendors/<vendorID>"
-X POST
{
"success": true,
"message": "vendor <vendorID> assigned to asset <assetID>"
}
This endpoint assigns vendor to a specific asset.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/assets/<assetID>/vendors/<vendorID>
URL PARAMETERS
vendorID The ID of the vendor to be assigned to asset.
Remove Assigned Vendor from an Asset
curl "https://api.onupkeep.com/api/v2/assets/<assetID>/vendors/<vendorID>"
-X DELETE
{
"success": true,
"message": "vendor <vendorID> removed from asset <assetID>"
}
This endpoint removes assigned vendor from a specific asset.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/assets/<assetID>/vendors/<vendorID>
URL PARAMETERS
vendorID The ID of the vendor to be removed from asset.
Locations
Create a Location
curl "https://api.onupkeep.com/api/v2/locations/"
-X POST
-d name="Sherlock Homes' House"
-d address="221B Baker Street, London NW1 6XE, UK"
-d longitude=51.523767
-d latitude=-0.1585557
-d hideMap="0"
{
"success": true,
"result": [
{
"id": "jpSMgHPr11",
"createdByUsername": "test@onupkeep.com",
"name": "Sherlock Homes' House",
"address": "221B Baker Street, London NW1 6XE, UK",
"longitude": 51.523767,
"latitude": -0.1585557,
"hideMap": "0",
"createdAt": "2017-10-23T23:51:58.098Z",
"updatedAt": "2017-10-27T20:36:24.563Z"
}
]
}
This endpoint creates a new location.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/locations/
REQUEST BODY
Provide any of the below required fields and optional fields for the asset.
name String true
longitude Float false
latitude Float false
hideMap Boolean as a string; "0" or "1" false
Get All Locations
curl "https://api.onupkeep.com/api/v2/locations"
{
"success": true,
"results": [
{
"id": "jpSMgHPr11",
"name": "Tutorial: Meeting Room",
"address": "11087 Sunset Blvd, Los Angeles, CA 90049, USA",
"longitude": -118.25525040000002,
"latitude": 34.07583059999999,
"hideMap": "0",
"createdAt": "2017-10-23T23:51:58.098Z",
"updatedAt": "2017-10-27T20:36:24.563Z"
}
]
}
This endpoint retrieves all locations for your account.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/locations
QUERY PARAMETERS
name undefined If set, the result will only include locations with that name.
createdByUser undefined (ID) If set, the result will only include locations created by this user.
includes undefined (Array) send 'createdByUser' to expand respective object.
orderBy
DESC "DESC".
Get a Specific Location
curl "https://api.onupkeep.com/api/v2/locations/fjQXLsOvG7"
{
"success": true,
"result": {
"id": "jpSMgHPr11",
"name": "Meeting Room",
"longitude": -118.25525040000002,
"latitude": 34.07583059999999,
"hideMap": "0",
"subLocations": [
"UgKWefUzv6"
],
"files": [
"e1HbFRtKAV",
"tzfnyFGBMm"
],
"customFieldsLocation": [
{
"id": "AvmCM4NHrI",
"name": "Floor",
"value": "1st",
"location": "rJm0aQBpLC",
"unit": "g",
"user": "7w6jIHFdEr",
"createdAt": "2018-05-17T07:38:33.619Z",
"updatedAt": "2018-05-17T07:38:33.619Z"
}
],
"createdAt": "2017-10-23T23:51:58.098Z",
"updatedAt": "2017-10-27T20:36:24.563Z"
}
}
This endpoint retrieves a specific location.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/locations/<ID>
URL PARAMETERS
ID The ID of the location to retrieve
QUERY PARAMETERS
(Array) send 'createdByUser', 'assignedUsers', 'assignedTeams', 'assignedCustomers', 'assignedVendors to

includes undefined
expand respective object.
Update a Specific Location
curl "https://api.onupkeep.com/api/v2/locations/fjQXLsOvG7"
-X PATCH
-d name="Conference Room"
{
"success": true,
"result": [
{
"id": "jpSMgHPr11",
"name": "Conference Room",
"longitude": -118.25525040000002,
"latitude": 34.07583059999999,
"hideMap": "0",
"createdAt": "2017-10-23T23:51:58.098Z",
"updatedAt": "2017-10-27T20:36:24.563Z"
}
]
}
This endpoint updates a specific location.
HTTP REQUEST
PATCH https://api.onupkeep.com/api/v2/locations/<ID>
URL PARAMETERS
ID The ID of the location to update
REQUEST BODY
Provide any of the below fields of the location in the payload to update those specific fields. Null values are allowed to erase the value
unless otherwise stated.
Parameter Type
name String
address String
longitude Float
latitude Float
hideMap Boolean as a string; "0" or "1"
Delete a Specific Location
curl "https://api.onupkeep.com/api/v2/locations/jQXLsOvG7"
-X DELETE
{
"success": true,
"message": "1 location deleted"
}
This endpoint deletes a specific location
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/locations/<ID>
URL PARAMETERS
ID The ID of the location to delete
Assign User to a Location
curl "https://api.onupkeep.com/api/v2/locations/<locationID>/users/<userID>"
-X POST
{
"success": true,
"message": "user <userID> assigned to location <locationID>"
}
This endpoint assigns user to a specific location.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/locations/<locationID>/users/<userID>
URL PARAMETERS
locationID The ID of the desired location
userID The ID of the user to be assigned to location.
Remove Assigned User from a Location
curl "https://api.onupkeep.com/api/v2/locations/<locationID>/users/<userID>"
-X DELETE
{
"success": true,
"message": "user <userID> removed from location <locationID>"
}
This endpoint removes assigned user from a specific location.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/locations/<locationID>/users/<userID>
URL PARAMETERS
userID The ID of the user to be removed from location.
Assign Team to a Location
curl "https://api.onupkeep.com/api/v2/locations/<locationID>/teams/<teamID>"
-X POST
{
"success": true,
"message": "team <teamID> assigned to location <locationID>"
}
This endpoint assigns team to a specific location.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/locations/<locationID>/teams/<teamID>
URL PARAMETERS
teamID The ID of the team to be assigned to location.
Remove Assigned Team from a Location
curl "https://api.onupkeep.com/api/v2/locations/<locationID>/teams/<teamID>"
-X DELETE
{
"success": true,
"message": "team <teamID> removed from location <locationID>"
}
This endpoint removes assigned team from a specific location.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/locations/<locationID>/teams/<teamID>
URL PARAMETERS
teamID The ID of the team to be removed from location.
Assign Customer to a Location
curl "https://api.onupkeep.com/api/v2/locations/<locationID>/customers/<customerID>"
-X POST
{
"success": true,
"message": "customer <customerID> assigned to location <locationID>"
}
This endpoint assigns customer to a specific location.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/locations/<locationID>/customers/<customerID>
URL PARAMETERS
customerID The ID of the customer to be assigned to location.
Remove Assigned Customer from a Location
curl "https://api.onupkeep.com/api/v2/locations/<locationID>/customers/<customerID>"
-X DELETE
{
"success": true,
"message": "customer <customerID> removed from location <locationID>"
}
This endpoint removes assigned customer from a specific location.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/locations/<locationID>/customers/<customerID>
URL PARAMETERS
customerID The ID of the customer to be removed from location.
Assign Vendor to a Location
curl "https://api.onupkeep.com/api/v2/locations/<locationID>/vendors/<vendorID>"
-X POST
{
"success": true,
"message": "vendor <vendorID> assigned to location <locationID>"
}
This endpoint assigns vendor to a specific location.

HTTP REQUEST
POST https://api.onupkeep.com/api/v2/locations/<locationID>/vendors/<vendorID>
URL PARAMETERS
vendorID The ID of the vendor to be assigned to location.
Remove Assigned Vendor from a Location
curl "https://api.onupkeep.com/api/v2/locations/<locationID>/vendors/<vendorID>"
-X DELETE
{
"success": true,
"message": "vendor <vendorID> removed from location <locationID>"
}
This endpoint removes assigned vendor from a specific location.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/locations/<locationID>/vendors/<vendorID>
URL PARAMETERS
vendorID The ID of the vendor to be removed from location.
Parts
Create a Part
curl "https://api.onupkeep.com/api/v2/parts/"
-X POST
-d name="Flux Capacitor"
-d description="This is what makes time travel possible."
-d cost=88.00
-d quantity=15
-d minimumQuantity=1
-d serial=40161502
-d category="Compressor",
-d location="jmHFWGVgd1"
{
"success": true,
"result": [
{
"id": "1YHUWGVgdC",
"name": "Flux Capacitor",
"description": "This is what makes time travel possible.",
"cost": "88.00",
"quantity": "15",
"minimumQuantity": "1",
"serial": "40161502",
"category": "Compressor",
"location": "jmHFWGVgd1",
"createdByUser": "pCmWGVgfW",
"createdAt": "2017-10-23T23:51:58.097Z",
"updatedAt": "2017-10-23T23:51:58.097Z"
}
]
}
This endpoint creates a new part.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/parts/
REQUEST BODY
Provide any of the below required fields and optional fields for the part.
name String true
cost Float false
quantity Number false
minimumQuantity Number false
serial String false
area String false
details String false
category String false
location String (ID) false id of the location
Get All Parts
curl "https://api.onupkeep.com/api/v2/parts"
{
"success": true,
"results": [
{
"id": "1YHUWGVgdC",
"image": {
"name": "dfimg_part_du.jpg",
"url": "https://upkeep-production.s3.amazonaws.com/dfimg_part_du.jpg"
},
"cost": "88.00",
"quantity": "5",
"serial": "40161502",
"area": "Mark street",
"details": "additional details",
"category": "Filter",
"createdAt": "2017-10-23T23:51:58.097Z",
"updatedAt": "2017-10-23T23:51:58.097Z"
}
]
}
This endpoint retrieves all parts for your account.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/parts
QUERY PARAMETERS
name undefined If set the result will only include parts with that name.
category undefined If set the result will only include parts with that category.
location undefined (ID) If set the result will only include parts belonging to this location.
createdByUser undefined (ID) If set the result will only include parts created by this user.
includes undefined (Array) send 'location', createdByUser' to expand respective object.
orderBy
DESC "DESC".
Get a Specific Part
curl "https://api.onupkeep.com/api/v2/parts/1YHUWGVgdC"
{
"success": true,
"result": {
"id": "1YHUWGVgdC",
"image": {
},
"cost": "88.00",
"quantity": "5",
"serial": "40161502",
"files": [
"MUfUCa0JBo",
"FGyvo6raqZ"
],
"customFieldsPart": [
{
"id": "axdcV3NKaB",
"name": "Manufactured By",
"value": "ABC Parts Inc",
"partInventory": "ydOS2PdR3a",
"unit": "cxcxc",
"user": "7w6jIHFdEr",
"createdAt": "2018-05-18T09:37:21.593Z",
"updatedAt": "2018-05-18T09:37:21.593Z"
}
]
"createdAt": "2017-10-23T23:51:58.097Z",
"updatedAt": "2017-10-23T23:51:58.097Z"
}
}
This endpoint retrieves a specific part.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/parts/<ID>
URL PARAMETERS
ID The ID of the part to retrieve
QUERY PARAMETERS
includes undefined (Array) send 'location', createdByUser' to expand respective object.
Update a Specific Part
curl "https://api.onupkeep.com/api/v2/parts/1YHUWGVgdC"
-X PATCH
-d quantity=100
{
"success": true,
"result": [
{
"id": "1YHUWGVgdC",
"image": {
},
"cost": "88.00",
"quantity": "100",
"serial": "40161502",
"createdAt": "2017-10-23T23:51:58.097Z",
"updatedAt": "2017-10-23T23:51:58.097Z"
}
]
}
This endpoint updates a specific part.
HTTP REQUEST
PATCH https://api.onupkeep.com/api/v2/parts/<ID>
URL PARAMETERS
ID The ID of the part to update
REQUEST BODY
Provide any of the below fields of the part in the payload to update those specific fields. Null values are allowed to erase the value unless
otherwise stated.
Parameter Type
name String
description String
cost Float
quantity Number
minimumQuantity Number
serial String
area String
details String
category String
location String (ID)
Delete a Specific Part
curl "https://api.onupkeep.com/api/v2/parts/jQXLsOvG7"
-X DELETE
{
"success": true,
"message": "1 part deleted"
}
This endpoint deletes a specific part
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/parts/<ID>
URL PARAMETERS
ID The ID of the part to delete
Requests
Create a Request
curl "https://api.onupkeep.com/api/v2/requests/"
-X POST
-d title="Repair sink"
-d description="Sink broke yesterday"
-d team="hp8LFaUelk"
-d location="yuhLKaHelk"
-d asset="pLkyFaFelk"
-d category="Electrical"
-d assignedToUser="cCkyAfIelk"
-d dueDate=1515482422310
{
"success": true,
"result": {
"id": "9shLaaHeMQ",
"title": "Repair sink",
"description": "Sink broke yesterday",
"location": "yuhLKaHelk",
"asset": "pLkyFaFelk",
"team": "pLykFaFelk",
"category": "Electrical",
"assignedToUser": "cCkyAfIelk",
"assignedToUsername" : "satya",
"status": "open",
"requestedByUser": "8PhLFaHelk",
"dueDate": "2018-01-09T07:20:22.310Z",
"createdAt": "2018-01-09T06:24:16.297Z",
"updatedAt": "2018-01-09T06:24:16.297Z"
}
}
This endpoint creates a new request.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/requests/
REQUEST BODY
title String true
location String false id of a location
asset String false id of an asset
team String false id of a Team
assignedToUser String false id of user
dueDate Number false timestamp in milliseconds
category String false Can not be a random string, check for the allowed category
EVENTS AFTER REQUEST IS CREATED
If the API returns with status 200:
1. If your account has a Zapier integration enabled, data will be sent to Zapier for the new request trigger
2. "New Request" emails will be sent to admins alerting them.
Get All Requests
curl "https://api.onupkeep.com/api/v2/requests"
{
"success": true,
"results": [
{
"id": "hn5PE6HXAG",
"title": "Broken light in the production room",
"description": "There is a light that is out in the production room. Hint: Approving this request will move it to the work orders section",
"image": {
"__type": "File",
"name": "dfimg_request2.jpg",
"url": "https://demo-api-upkeep.s3.amazonaws.com/dfimg_request2.jpg"
},
"requestedByUser": "8PhLFaHelk",
"createdAt": "2018-01-09T03:43:23.769Z",
"updatedAt": "2018-01-09T03:43:23.769Z"
}
]
}
This endpoint retrieves all requests for your account.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/requests
QUERY PARAMETERS
(ID) id of the upkeep user who created the request.if provided will show only requests requested
requestedByUser undefined
by the user.
(String) email id of requester(request via request portal/via email). if provided will show only
publicRequesterEmail undefined requests requested by the user. request will have either requestedByUser or publicRequesterEmail
set.
includes undefined (Array) send 'asset' to expand respective object.
createdAt (String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC"
orderBy
DESC or "DESC".
Get a Specific Request
curl "https://api.onupkeep.com/api/v2/requests/HW2I379ErS"
{
"success": true,
"result": {
"id": "hn5PE6HXAG",
"title": "Tutorial: Broken light in the production room",
"description": "There is a light that is out in the production room. Hint: Approving this request will move it to the work orders section",
"image": {
"__type": "File",
},
"publicRequesterEmail": "test@abc.com",
"createdAt": "2018-01-09T03:43:23.769Z",
"updatedAt": "2018-01-09T03:43:23.769Z"
}
}
This endpoint retrieves a specific requests.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/requests/<ID>
URL PARAMETERS
ID The ID of the request to retrieve
QUERY PARAMETERS
includes undefined (Array) send 'asset' to expand respective object.
Cancel a Specific Request
curl "https://api.onupkeep.com/api/v2/requests/jQXLsOvG7/cancel"
-X DELETE
{
"success": true,
"message": "1 request cancelled"
}
This endpoint cancels a specific request.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/requests/<ID>/cancel
URL PARAMETERS
ID The ID of the request to cancel
EVENTS AFTER REQUEST IS CANCELLED
1. The requester will be sent an email informing him or her about request cancellation.
Delete a Specific Request
curl "https://api.onupkeep.com/api/v2/requests/jQXLsOvG7"
-X DELETE
{
"success": true,
"message": "1 request deleted"
}
This endpoint deletes a specific request.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/requests/<ID>
URL PARAMETERS
ID The ID of the request to delete
Work Orders
Create a Work Order
curl "https://api.onupkeep.com/api/v2/work-orders/"
-X POST
-d title="Repair sink"
-d description="Sink broke yesterday"
-d priority=1
-d dueDate=1515482422310
-d asset="gDK45aHe12"
-d location="MD565aHenL"
-d assignedToUser="lv6FZopMhz"
-d estimatedDurationInHours=5
-d category="Damage"
{
"success": true,
"result": {
"id": "6yDTWLAEmh",
"workOrderNo": "006",
"title": "Repair sink",
"description": "Sink broke yesterday",
"status": "open",
"category": "Damage",
"dueDate": "2018-01-09T07:20:22.310Z",
"assignedToUser": "vk6BHzQVCX",
"assignedToUsername": "test@onupkeep.com",
"asset": "knyWfDnXWo",
"location": "cXRAu708NU",
"assignedByUser": "lv6FZopMhz",
"assignedByUsername": "test@onupkeep.com",
"estimatedDurationInHours" : 5,
"priority": 1,
"createdAt": "2018-01-09T07:56:53.743Z",
"updatedAt": "2018-01-09T07:56:53.743Z"
}
}
This endpoint creates a new Work Order.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/work-orders/
REQUEST BODY
title String true
priority Number false 0,1,2,3. 0 being lowest
one of the set categories for Work Orders on your account, including the default
ones
dueDate Number false timestamp in milliseconds
asset String false id of asset
location String false id of location
assignedToUser String false id of user whom the Work Order is assigned
estimatedDurationInHours Number false
EVENTS AFTER WORK ORDER IS CREATED
1. If your account has a Zapier integration enabled, data will be sent to Zapier for the new Work Order trigger.
2. If a user is assigned to the work order, an email will be sent to him or her. If it is assigned to no one, emails will be sent to admins.
Get All Work Orders
curl "https://api.onupkeep.com/api/v2/work-orders"
{
"success": true,
"results": [
{
"id": "HW2I379ErS",
"title": "Replace the warp drive on the fusion reactor",
"description": "Warp drive has been malfunctioning, check the coils that generate the warp field.",
"status": "onHold",
"dueDate": "2017-12-06T19:23:09.162Z",
"dateCompleted": "2017-12-06T19:23:09.162Z",
"assignedToUser": "5ZXaLRZ40I",
"assignedToUsername": "5ZXaLRZ40I",
"completedByUser": "5ZXaLRZ40I",
"asset": "kW6I379ELS",
"location": "Mkr457Gkk3",
"team": "PD6I909nLS",
"time": "20",
"cost": "25",
"formItems": [
"YChe6OjzHC",
"FuJBoOf8Di",
"e2iFG6t7I9"
],
"assignedByUser": "5ZXaLRZ40I",
"priority": "1",
"signatureImage": {
"__type": "File",
"name": "da696460251395f712d5b83d948a360c_2cd43b_434c5b3602af429f927d290cbc27d790_mv2.png",
"url": "https://demo-api-upkeep.s3.amazonaws.com/da696460251395f712d5b83d948a360c_2cd43b_434c5b3602af429f927d290cbc27d790_mv2.png"
},
"requiresSignature": 1,
"image": {
"__type": "File",
},
"parts": [
"sDmjnbbpAL",
"QhWwJbfGb4"
],
"image2": {...},
"image3": {...},
"image4": {...},
"image5": {...},
"publicRequesterEmail": "test@onupkeep.com",
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
]
}
This endpoint retrieves all work orders for your account.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/work-orders
QUERY PARAMETERS
title undefined If set, only work orders with this title will be included.
If set to "0", the result will only include work orders that have not been completed. If set to "1",
isComplete undefined
the result will only include work orders that have been completed.
If set, the work orders fetched will be of the specified status only(allowed values
status undefined
'open','onHold','inProgress', 'complete')
asset undefined (ID) If set, only work orders associated with this asset will be included.
location undefined (ID) If set, only work orders belonging to this location will be included.
category undefined If set, only work orders with this category will be included.
assignedToUser undefined (ID) If set, only work orders assigned to this user will be included.
assignedByUser undefined (ID) If set, only work orders assigned by this user will be included.
publicRequesterEmail undefined If set, only work orders created by this email on the public request portal will be included.
(Array) send 'asset', 'location', 'assignedToUser', 'team', 'formItems', 'parts' to expand respective
includes undefined
object.
createdAt (String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt', 'dueDate',
orderBy
DESC 'dateCompleted'. Second value: "ASC" or "DESC".
NOTE
For querying on dates eg

etc
createdAt, updatedAt ,dueDate ,dateCompleted
Append key with filter name GreaterThan, LessThan, GreaterThanOrEqualTo, LessThanOrEqualTo eg
createdAtLessThanOrEqualTo
The value must be unix timestamp (epoh) in milliseconds(required) eg
https://api.onupkeep.com/api/v2/work-orders?createdAtLessThan=1525132801455
Get a Specific Work Order
curl "https://api.onupkeep.com/api/v2/work-orders/HW2I379ErS"
{
"success": true,
"result": {
"id": "HW2I379ErS",
"title": "Replace the warp drive on the fusion reactor",
"status": "onHold",
"dueDate": "2017-12-06T19:23:09.162Z",
"time": "20",
"cost": "25",
"priority": "1",
"signatureImage": {
"__type": "File",
"name": "da696460251395f712d5b83d948a360c_2cd43b_434c5b3602af429f927d290cbc27d790_mv2.png",
"url": "https://demo-api-upkeep.s3.amazonaws.com/da696460251395f712d5b83d948a360c_2cd43b_434c5b3602af429f927d290cbc27d790_mv2.png"
},
"requiresSignature": 1,
"files": [
"2HMRIGeDKu"
],
"formItems": [
"YChe6OjzHC",
"FuJBoOf8Di",
"e2iFG6t7I9"
],
"image": {
"__type": "File",
},
"image2": {...},
"image3": {...},
"image4": {...},
"image5": {...},
"arrayOfUpdateItems": [
"dGCW3cSjWv",
"SPRXIDJDZ1"
],
"parts": [
"sDmjnbbpAL",
"QhWwJbfGb4"
],
"respectivePartQuantityUsed": [
5,
1
],
"additionalUsers": [
"vk6BHzQVCX",
"lv6FZopMhz"
],
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
}
This endpoint retrieves a specific work order.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/work-orders/<ID>
URL PARAMETERS
ID The ID of the work order to retrieve
QUERY PARAMETERS
(Array) send 'asset', 'location', 'assignedToUser', 'assignedByUser', 'team', 'formItems', 'arrayOfUpdateItems',

includes undefined
'parts', 'additionalUsers' to expand respective object.
Update a Specific Work Order
curl "https://api.onupkeep.com/api/v2/work-orders/<ID>"
-X PATCH
-d title="Repair Sink"
-d category="Electrical"
{
"success": true,
"result": {
"id": "HW2I379ErS",
"title": "Repair Sink",
"status": "onHold",
"dueDate": "2017-12-06T19:23:09.162Z",
"estimatedDurationInHours" : 5,
"priority": "1",
"image": {
"__type": "File",
},
"image2": {...},
"image3": {...},
"image4": {...},
"image5": {...},
"createdAt": "2017-12-06T19:23:09.162Z",
"updatedAt": "2017-12-08T18:41:44.335Z"
}
}
This endpoint updates a specific Work Order.
HTTP REQUEST
PATCH https://api.onupkeep.com/api/v2/work-orders/<ID>
URL PARAMETERS
ID The ID of the Work Order to update
REQUEST BODY
Provide any of the below fields of the part in the payload to update those specific fields. Null values are allowed to erase the value unless
otherwise stated.
Parameter Type Description
title String
description String
status String Allowed values- open, onHold, inProgress, complete
category String one of the set categories for Work Orders on your account, including the default ones
dueDate Number timestamp in milliseconds
estimatedDurationInHours Number
EVENTS AFTER WORK ORDER IS UPDATED
1. If the work order status is updated and your account has a Zapier integration enabled, data will be sent to Zapier for the status
change trigger.
Update Work Order messages
curl "https://api.onupkeep.com/api/v2/work-orders/jQXLsOvG7/update-messages/"
-X POST
-d text="New message"
{
"success": true,
"message": "1 message Added"
}
This endpoint add/update message to a specific work order.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/work-orders/<ID>/update-messages/
REQUEST BODY
Parameter type Required
text string Yes
API returns with status 200
Delete a Specific Work Order

curl "https://api.onupkeep.com/api/v2/work-orders/jQXLsOvG7"
-X DELETE
{
"success": true,
"message": "1 work order deleted"
}
This endpoint deletes a specific work order.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/work-orders/<ID>
URL PARAMETERS
ID The ID of the work order to delete
Preventative Maintenance
Create a Preventative Maintenance Work Order
curl "https://api.onupkeep.com/api/v2/preventative-maintenance/"
-X POST
-d title="Check Oil"
-d description="Confirm the tractor is optimal"
-d priority=1
-d recurringSchedule="daily"
-d dueDate=1515482422310
-d endDueDate=1517279400000
-d asset="gDK45aHe12"
-d location="MD565aHenL"
-d assignedToUser="lv6FZopMhz"
{
"success": true,
"result": {
"id": "6yDTWLAEmh",
"title": "Check Oil",
"status": "open",
"dueDate": "2018-01-09T07:20:22.310Z",
"endDueDate": "2018-01-30T02:30:00.000Z",
"recurringSchedule": "daily",
"assignedToUser": "lv6FZopMhz",
"asset": "gDK45aHe12",
"location": "MD565aHenL",
"priority": 1,
"description": "Confirm the tractor is optimal",
"createdAt": "2018-01-09T07:56:53.743Z",
"updatedAt": "2018-01-09T07:56:53.743Z"
}
}
This endpoint creates a new Preventative Work Order.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/preventative-maintenance/
REQUEST BODY
title String true
Represents the frequency of repetition. Allowed values 'daily', 'weekly', 'twoWeeks',

'monthly', twoMonths', 'threeMonths', 'sixMonths', 'yearly'. For repetition on certain days
recurringSchedule String true
of week send comma separated day codes. Allowed day codes- 'Su', 'Mo', 'Tu', 'We', 'Th',
'Fr', 'Sa'. eg "Su,Th,Fr".
dueDate Number false timestamp in milliseconds. If provided Preventative Work Orders will start from this date.
endDueDate Number false timestamp in milliseconds. If provided Preventative Work Orders will stop at this date.
asset String false id of asset
location String false id of location
assignedToUser String false id of user whom the Work Order is assigned
EVENTS AFTER WORK ORDER IS CREATED
1. If your account has a Zapier integration enabled, data will be sent to Zapier for the new Work Order trigger.
2. If a user is assigned to the work order, an email will be sent to him or her. If it is assigned to no one, emails will be sent to admins.
Get All Preventative Maintenance Work Orders
curl "https://api.onupkeep.com/api/v2/preventative-maintenance"
{
"success": true,
"results": [
{
"id": "6yDTWLAEmh",
"status": "open",
"dueDate": "2018-01-09T07:20:22.310Z",
"endDueDate": "2018-01-30T02:30:00.000Z",
"time": "20",
"cost": "25",
"priority": 1,
"createdAt": "2018-01-09T07:56:53.743Z",
"updatedAt": "2018-01-09T07:56:53.743Z"
}
]
}
This endpoint retrieves all preventative maintenance work orders for your account.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/preventative-maintenance
QUERY PARAMETERS
recurringSchedule undefined If set, only work orders with this repeating schedule will be included.
includes undefined (Array) send 'asset', 'location', 'assignedToUser', 'team' to expand respective object.
createdAt (String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt', 'dueDate'. Second
orderBy
DESC value: "ASC" or "DESC".
Get a Specific Preventative Maintenance Work Order

curl "https://api.onupkeep.com/api/v2/preventative-maintenance/HW2I379ErS"
{
"success": true,
"result": {
"id": "6yDTWLAEmh",
"status": "open",
"dueDate": "2018-01-09T07:20:22.310Z",
"endDueDate": "2018-01-30T02:30:00.000Z",
"time": "20",
"cost": "25",
"priority": 1,
"createdAt": "2018-01-09T07:56:53.743Z",
"updatedAt": "2018-01-09T07:56:53.743Z"
}
}
This endpoint retrieves a specific work order.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/preventative-maintenance/<ID>
URL PARAMETERS
ID The ID of the preventative maintenance work order to retrieve
QUERY PARAMETERS
(Array) send 'asset', 'location', 'assignedToUser', 'assignedByUser', 'team', 'formItems', 'arrayOfUpdateItems',

includes undefined
'parts', 'additionalUsers' to expand respective object.
Delete a Specific Preventative Maintenance Work Order
curl "https://api.onupkeep.com/api/v2/preventative-maintenance/jQXLsOvG7"
-X DELETE
{
"success": true,
"message": "1 work order deleted"
}
This endpoint deletes a specific work order.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/preventative-maintenance/<ID>
URL PARAMETERS
ID The ID of the work order to delete
Work Order Schedule
Get The Schedule of Preventative Maintenance Work Orders
curl "https://api.onupkeep.com/api/v2/work-order-schedule"
{
"success": true,
"results": [
{
"status": "open",
"dueDate": "2018-01-09T07:20:22.310Z",
"time": "20",
"cost": "25",
"priority": 1,
"createdAt": "2018-01-09T07:56:53.743Z",
"updatedAt": "2018-01-09T07:56:53.743Z"
}
]
}
This endpoint retrieves all preventative maintenance work orders for your account.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/work-order-schedule
QUERY PARAMETERS
utcOffset 0 Difference between UTC and your time-zone in minutes.
category undefined If set, only work orders with this category will be included.
includes undefined (Array) send 'asset', 'location', 'assignedToUser', 'team' to expand respective object.
Meters
Create a Meter
curl "https://api.onupkeep.com/api/v2/meters/"
-X POST
-d name="Mileage"
-d units="KMPL"
-d frequency=7
-d asset="KXi4CS5Nft"
-d location="M75FZevseo"
{
"success": true,
"result": {
"id": "WEeI86SMu4",
"name": "Mileage",
"units": "KMPL",
"frequency": 7,
"location": "M75FZevseo",
"asset": "KXi4CS5Nft",
"createdAt": "2018-01-30T10:19:24.141Z",
"updatedAt": "2018-01-30T10:19:24.141Z"
}
}
This endpoint creates a new meter.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/meters/
REQUEST BODY
Provide any of the below required fields and optional fields for meter.
name String true
units String true
frequency Number true
asset String false (ID) of asset
location String false (ID) of location
Get All Meters
curl "https://api.onupkeep.com/api/v2/meters/"
-X GET
{
"success": true,
"results": [
{
"id": "WEeI86SMu4",
"name": "Mileage",
"units": "KMPL",
"frequency": 7,
"createdAt": "2018-01-30T10:19:24.141Z",
"updatedAt": "2018-01-30T10:19:24.141Z"
}
]
}
This endpoint retrieves all meters for your account.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/meters/
QUERY PARAMETERS
name undefined If set the result will only include meters with that name.
asset undefined (ID) If set the result will only include meters with that asset.
location undefined (ID) If set the result will only include meters with that location.
includes undefined (Array) send 'asset', 'location', 'lastReading' to expand respective object.
orderBy
DESC "DESC".
Get a Specific Meter
curl "https://api.onupkeep.com/api/v2/meters/<ID>"
-X GET
{
"success": true,
"result": {
"id": "WEeI86SMu4",
"name": "Mileage",
"units": "KMPL",
"frequency": 7,
"lastReading": "IwOZ7ulcv5",
"createdAt": "2018-01-30T10:19:24.141Z",
"updatedAt": "2018-01-30T10:19:24.141Z"
}
}
This endpoint retrieves a specific meter.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/meters/<ID>
URL PARAMETERS
ID The ID of the meter to retrieve
QUERY PARAMETERS
includes undefined (Array) send 'asset', 'location', 'lastReading' to expand respective object.
Update a Specific Meter
-X PATCH
-d frequency=4
{
"success": true,
"result": {
"id": "WEeI86SMu4",
"name": "Mileage",
"units": "KMPL",
"frequency": 4,
"lastReading": "IwOZ7ulcv5",
"createdAt": "2018-01-30T10:19:24.141Z",
"updatedAt": "2018-01-30T10:19:24.141Z"
}
}
This endpoint updates a specific meter.
HTTP REQUEST
PATCH https://api.onupkeep.com/api/v2/meters/<ID>
URL PARAMETERS
ID The ID of the meter to update
REQUEST BODY
Provide any of the below fields of the meter in the payload to update those specific fields. Null values are allowed to erase the value unless
otherwise stated.
name String true
units String true
frequency Number true
asset String false (ID) of asset
location String false (ID) of location
NOTE
Updating meter does not update past readings.
Delete a Specific Meter
-X DELETE
{
"success": true,
"message": "1 meter deleted"
}
This endpoint deletes a specific meter.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/meters/<ID>
URL PARAMETERS
ID The ID of the meter to delete
Add a Reading to a Meter
curl "https://api.onupkeep.com/api/v2/meters/<meterID>/readings"
-X POST
-d value=1
{
"success": true,
"result": {
"id": "iGIkXrVtGS",
"date": "2018-01-30T10:05:20.402Z",
"meter": "GvWe2sCUkY",
"value": 1,
"createdAt": "2018-01-30T10:05:20.425Z",
"updatedAt": "2018-01-30T10:05:20.425Z"
}
}
This adds a reading to meter.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/meters/<meterID>/readings
REQUEST BODY
Provide any of the below required fields and optional fields for the meter reading.
value Number true
URL PARAMETERS
meterID The ID of the meter
EVENTS AFTER READING IS ADDED
1. If a Work Order trigger is set via meter notification, Specified Work Order will be created if conditions are met.
Get All Readings for a Meter
curl "https://api.onupkeep.com/api/v2/meters/<meterID>/readings"
-X GET
{
"success": true,
"results": [
{
"id": "iGIkXrVtGS",
"date": "2018-01-30T10:05:20.402Z",
"meter": "GvWe2sCUkY",
"value": 1,
"createdAt": "2018-01-30T10:05:20.425Z",
"updatedAt": "2018-01-30T10:05:20.425Z"
}
]
}
This endpoint retrieves all readings for a meter.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/meters/<meterID>/readings
QUERY PARAMETERS
includes undefined (Array) send 'createdByUser' expand respective object.
orderBy
DESC "DESC".
URL PARAMETERS
Create a Meter Notification
curl "https://api.onupkeep.com/api/v2/meters/<meterID>/notifications"
-X POST
-d title="Reading less than 100"
-d description="Triggers when reading is less than 100"
-d triggerValue=100
-d triggerFrequency="ONE_TIME_IS_LESS_THAN"
-d assignedToUser="qTmhmORg85"
{
"success": true,
"result": {
"id": "LNbrsMFfMy",
"title": "Reading less than 100",
"triggerFrequency": "ONE_TIME_IS_LESS_THAN",
"description": "Triggers when reading is less than 100",
"triggerValue": 100,
"assignedToUser": "qTmhmORg85",
"createdAt": "2018-02-05T05:06:24.570Z",
"updatedAt": "2018-02-05T05:06:24.570Z"
}
}
This endpoint creates a new meter notification for particular meter.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/meters/<meterID>/notifications
REQUEST BODY
Provide any of the below required fields and optional fields for meter notifications.
title String true Title of Work Order to create on trigger.
triggerValue Number true Value to be compared for trigger.
Comparison operator for trigger. Allowed values- 'ONE_TIME_IS_GREATER_THAN',

triggerFrequency String true 'ONE_TIME_IS_LESS_THAN', 'EVERY_TIME_IS_LESS_THAN', 'EVERY_TIME_IS_GREATER_THAN',
'EVERY_TIME_IS_EQUAL_TO', 'EVERY_TIME_REACHES'.
description String false Work Order description.
assignedToUser String false (ID) of User assigned.
URL PARAMETERS
Get All Meter Notifications
curl "https://api.onupkeep.com/api/v2/meters/<meterID>/notifications"
-X GET
{
"success": true,
"results": [
{
"id": "LNbrsMFfMy",
"createdAt": "2018-02-05T05:06:24.570Z",
"updatedAt": "2018-02-05T05:06:24.570Z"
}
]
}
This endpoint retrieves all notifications for particular meter.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/meters/<meterID>/notifications
QUERY PARAMETERS
includes undefined (Array) send 'assignedToUser', 'createdByUser' expand respective object.
orderBy
DESC "DESC".
URL PARAMETERS
Get a Specific Meter Notification
curl "https://api.onupkeep.com/api/v2/meters/<meterID>/notifications/<ID>"
-X GET
{
"success": true,
"result": {
"id": "LNbrsMFfMy",
"createdAt": "2018-02-05T05:06:24.570Z",
"updatedAt": "2018-02-05T05:06:24.570Z"
}
}
This endpoint retrieves a specific meter notification.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/meters/<meterID>/notifications/<ID>
URL PARAMETERS
ID The ID of the meter notification to retrieve
QUERY PARAMETERS
includes undefined (Array) send 'assignedToUser', 'createdByUser' expand respective object.
Update a Specific Meter Notification
-X PATCH
-d assignedToUser="MtmhmKKg56"
{
"success": true,
"result": {
"id": "LNbrsMFfMy",
"assignedToUser": "MtmhmKKg56",
"createdAt": "2018-02-05T05:06:24.570Z",
"updatedAt": "2018-02-05T05:06:24.570Z"
}
}
This endpoint updates a specific meter notification.
HTTP REQUEST
PATCH https://api.onupkeep.com/api/v2/meters/<meterID>/notifications/<ID>
URL PARAMETERS
ID The ID of the meter notification to update
REQUEST BODY
Provide any of the below fields of the Meter Notification in the payload to update those specific fields. Null values are allowed to erase the
value unless otherwise stated.
title String false Title of Work Order to create on trigger.
triggerValue Number false Value to be compared for trigger.
Comparison operator for trigger. Allowed values- 'ONE_TIME_IS_GREATER_THAN',

triggerFrequency String false 'ONE_TIME_IS_LESS_THAN', 'EVERY_TIME_IS_LESS_THAN', 'EVERY_TIME_IS_GREATER_THAN',
'EVERY_TIME_IS_EQUAL_TO', 'EVERY_TIME_REACHES'.
description String false Work Order description.
assignedToUser String false (ID) of User assigned.
Delete a Specific Meter Notification
-X DELETE
{
"success": true,
"message": "1 notification deleted"
}
This endpoint deletes a specific meter notification.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/meters/<meterID>/notifications/<ID>
URL PARAMETERS
ID The ID of the meter notification to delete
Purchase Orders
Create a Purchase Order
curl 'https://api.onupkeep.com/api/v2/purchase-orders/'
-H 'Session-Token: session_token_here'
-H 'Content-Type: application/json'
-X POST
-d '{"title": "Power dice shortage", "parts": [{"id": "t0RYP2jIPz", "quantity": 5}],
"vendor": "IPS0tjjV5I", "description": "Small dice model 5","dueDate":"2018-06-30",
"poDate": "2018-06-28", "tax": 12, "shippingCost": 120, "otherCost": 1300,
"requisitioner": "Mark Boucher", "shippingMethod": "Ground", "fobPoint": "184.83",
"terms": "T & C apply", "notes": "Recomended by engineering team","companyName":"AB Inc",
"companySlogan": "Time is money", "companyStreet": "23 Chester Evenue",
"companyCity": "Los Angeles", "companyState": "California", "companyZip":"90224",
"companyPhone": "+1 888-452-1505", "companyFax":"+1 333-452-1505","shippingName":"Mr VC Ness",
"shippingCompany":"DMR Dice suppliers", "shippingStreet": "345 PVN Mart",
"shippingCity": "Los Angeles", "shippingState":"California","shippingZip": "90224",
"shippingPhone": "+1 222-452-1505", "shippingFax": "+1 123-452-1505", "category": "Electrical"}'
{
"success": true,
"result": {
"id": "XHUi1SyW0t",
"createdByUser": "7w6jIHFdEr",
"title": "Power dice shortage",
"description": "Small dice model 5",
"status": "awaiting",
"poDate": "2018-06-28T00:00:00.000Z",
"dueDate": "2018-06-30T00:00:00.000Z",
"vendor": "IPS0tjjV5I",
"parts": [
"t0RYP2jIPz"
],
"partQuantities": [
5
],
"totalQuantity": 5,
"totalCost": 60,
"tax": 12,
"shippingCost": 120,
"otherCost": 1300,
"requisitioner": "Mark Boucher",
"shippingMethod": "Ground",
"fobPoint": "184.83",
"terms": "T & C apply",
"notes": "Recomended by engineering team",
"companyName": "AB Inc",
"companySlogan": "Time is money",
"companyStreet": "23 Chester Evenue",
"companyCity": "Los Angeles",
"companyState": "California",
"companyZip": "90224",
"companyPhone": "+1 888-452-1505",
"companyFax": "+1 333-452-1505",
"shippingName": "Mr VC Ness",
"shippingCompany": "DMR Dice suppliers",
"shippingStreet": "345 PVN Mart",
"shippingCity": "Los Angeles",
"shippingState": "California",
"shippingZip": "90224",
"shippingPhone": "+1 222-452-1505",
"shippingFax": "+1 123-452-1505",
"purchaseOrderNumber": 36,
"createdAt": "2018-06-08T09:15:46.452Z",
"updatedAt": "2018-06-08T09:15:46.452Z"
}
}
This endpoint creates a Purchase Order.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/purchase-orders/
REQUEST BODY
Provide any of the below required fields and optional fields for Purchase Order.
title String true
parts Array false Array Of objects containg part id and quantity
vendor String false (ID) of vendor
dueDate String false
poDate String false Date of Purchase Order
tax Number false
shippingCost Number false
otherCost Number false
requisitioner String false
shippingMethod String false
fobPoint String false Free on board shipping point
terms String false
notes String false
companyName String false
companySlogan String false
companyStreet String false
companyCity String false
companyState String false
companyZip String false
companyPhone String false
companyFax String false
shippingName String false
shippingCompany String false
shippingStreet String false
shippingCity String false
shippingState String false
shippingZip String false
shippingPhone String false
shippingFax String false
Get All Purchase Orders
curl "https://api.onupkeep.com/api/v2/purchase-orders/"
-X GET
{
"success": true,
"results": [
{
"id": "XHUi1SyW0t",
"poDate": "2018-06-28T00:00:00.000Z",
"dueDate": "2018-06-30T00:00:00.000Z",
"parts": [
"t0RYP2jIPz"
],
"partQuantities": [
5
],
"totalQuantity": 5,
"totalCost": 60,
"tax": 12,
"otherCost": 1300,
"fobPoint": "184.83",
"companyPhone": "+1 888-452-1505",
"companyFax": "+1 333-452-1505",
"shippingPhone": "+1 222-452-1505",
"shippingFax": "+1 123-452-1505",
"createdAt": "2018-06-08T09:15:46.452Z",
"updatedAt": "2018-06-08T09:15:46.452Z"
}
]
}
This endpoint retrieves all Purchase Orders for your account.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/purchase-orders/
QUERY PARAMETERS
title undefined If set the result will only include Purchase Orders with that title.
status undefined If set the result will only include Purchase Orders with that status.
vendor undefined If set the result will only include Purchase Orders with that vendor.
includes undefined (Array) send 'vendor'expand object.
orderBy
DESC "DESC".
Get a Specific Purchase Order
curl "https://api.onupkeep.com/api/v2/purchase-orders/<ID>"
-X GET
{
"success": true,
"result": {
"id": "XHUi1SyW0t",
"poDate": "2018-06-28T00:00:00.000Z",
"dueDate": "2018-06-30T00:00:00.000Z",
"parts": [
"t0RYP2jIPz"
],
"partQuantities": [
5
],
"totalQuantity": 5,
"totalCost": 60,
"tax": 12,
"otherCost": 1300,
"fobPoint": "184.83",
"companyPhone": "+1 888-452-1505",
"companyFax": "+1 333-452-1505",
"shippingPhone": "+1 222-452-1505",
"shippingFax": "+1 123-452-1505",
"createdAt": "2018-06-08T09:15:46.452Z",
"updatedAt": "2018-06-08T09:15:46.452Z"
}
}
This endpoint retrieves a specific Purchase Order.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/purchase-orders/<ID>
URL PARAMETERS
ID The ID of the Purchase Order to retrieve
QUERY PARAMETERS
includes undefined (Array) send 'vendor', 'parts' to expand respective object.
Update a Specific Purchase Order
curl 'https://api.onupkeep.com/api/v2/purchase-orders/<ID>'
-H 'Content-Type: application/json'
-X PATCH
-d '{"status": "fulfilled"}'
{
"success": true,
"result": {
"id": "XHUi1SyW0t",
"status": "fulfilled",
"fulfilledAt": "2018-06-08T10:04:05.108Z",
"fulfilledByUser": "7w6jIHFdEr",
"poDate": "2018-06-28T00:00:00.000Z",
"dueDate": "2018-06-30T00:00:00.000Z",
"parts": [
"t0RYP2jIPz"
],
"partQuantities": [
5
],
"totalQuantity": 5,
"totalCost": 60,
"tax": 12,
"otherCost": 1300,
"fobPoint": "184.83",
"companyPhone": "+1 888-452-1505",
"companyFax": "+1 333-452-1505",
"shippingPhone": "+1 222-452-1505",
"shippingFax": "+1 123-452-1505",
"createdAt": "2018-06-08T09:15:46.452Z",
"updatedAt": "2018-06-08T09:15:46.452Z"
}
}
This endpoint updates a specific Purchase Order.
HTTP REQUEST
PATCH https://api.onupkeep.com/api/v2/purchase-orders/<ID>
URL PARAMETERS
ID The ID of the Purchase Order to update
REQUEST BODY
Provide any of the below fields of the Purchase Order in the payload to update those specific fields. Null values are allowed to erase the
value unless otherwise stated.
title String
status String Allowed values 'awaiting', 'approved', 'declined', 'fulfilled'
parts Array Array Of objects containing part id and quantity
vendor String (ID) of vendor
description String
category String
dueDate String
poDate String
tax Number
shippingCost Number
otherCost Number
requisitioner String
shippingMethod String
fobPoint String
terms String
notes String
companyName String
companySlogan String
companyStreet String
companyCity String
companyState String
companyZip String
companyPhone String
companyFax String
shippingName String
shippingCompany String
shippingStreet String
shippingCity String
shippingState String
shippingZip String
shippingPhone String
shippingFax String
NOTE
For updating parts in Purchase order. Its required to send all array objects with quantity just like the create request
Delete a Specific Purchase Order
curl "https://api.onupkeep.com/api/v2/purchase-orders/<ID>"
-X DELETE
{
"success": true,
"message": "1 Purchase Order deleted"
}
This endpoint deletes a specific Purchase Order.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/purchase-orders/<ID>
URL PARAMETERS
ID The ID of the Purchase Order to delete
Add text message to Purchase Order
curl "https://api.onupkeep.com/api/v2/purchase-orders/<purchaseOrderID>/update-messages"
-X POST
-d text="Will be delevered soon"
{
"success": true,
"message": "update message added"
}
This endpoint adds update message for particular Purchase Order.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/purchase-orders/<purchaseOrderID>/update-messages
REQUEST BODY
Provide any of the below required fields and optional fields for message.
text String true
URL PARAMETERS
purchaseOrderID The ID of the Purchase Order
Purchase Order Category
Create a Purchase Order Category
curl 'https://api.onupkeep.com/api/v2/purchase-order-categories/'
-X POST
-d name="Electrical"
{
"success": true,
"result": {
"id": "G25KW7hlV0",
"name": "Electrical",
"createdAt": "2018-06-08T10:49:16.489Z",
"updatedAt": "2018-06-08T10:49:16.489Z"
}
}
This endpoint creates a Purchase Order Category.
HTTP REQUEST
POST https://api.onupkeep.com/api/v2/purchase-order-categories/
REQUEST BODY
Provide any of the below required fields and optional fields for Purchase Order Category.
name String true
Get All Purchase Orders Categories
curl "https://api.onupkeep.com/api/v2/purchase-order-categories/"
-X GET
{
"success": true,
"results": [
{
"id": "G25KW7hlV0",
"createdAt": "2018-06-08T10:49:16.489Z",
"updatedAt": "2018-06-08T10:49:16.489Z"
}
]
}
This endpoint retrieves all Purchase Order Categories for your account.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/purchase-order-categories/
Get a Specific Purchase Order Category
curl "https://api.onupkeep.com/api/v2/purchase-order-categories/<ID>"
-X GET
{
"success": true,
"result": {
"id": "G25KW7hlV0",
"createdAt": "2018-06-08T10:49:16.489Z",
"updatedAt": "2018-06-08T10:49:16.489Z"
}
}
This endpoint retrieves a specific Purchase Order Category.
HTTP REQUEST
GET https://api.onupkeep.com/api/v2/purchase-order-categories/<ID>
URL PARAMETERS
ID The ID of the Purchase Order Category to retrieve
Update a Specific Purchase Order Category
curl 'https://api.onupkeep.com/api/v2/purchase-order-categories/<ID>'
-X PATCH
-d name="Project"
{
"success": true,
"result": {
"id": "G25KW7hlV0",
"name": "Project",
"createdAt": "2018-06-08T10:49:16.489Z",
"updatedAt": "2018-06-08T10:49:16.489Z"
}
}
This endpoint updates a specific Purchase Order Category.
HTTP REQUEST
PATCH https://api.onupkeep.com/api/v2/purchase-order-categoriess/<ID>
URL PARAMETERS
ID The ID of the Purchase Order Category to update
REQUEST BODY
name String
Delete a Specific Purchase Order Category
curl "https://api.onupkeep.com/api/v2/purchase-order-categories/<ID>"
-X DELETE
{
"success": true,
"message": "1 Purchase Order Category deleted"
}
This endpoint deletes a specific Purchase Order Category.
HTTP REQUEST
DELETE https://api.onupkeep.com/api/v2/purchase-order-categories/<ID>
URL PARAMETERS
ID The ID of the Purchase Order Category to delete
Reporting (BETA)
Get Work Order Aggregate Counts
curl "https://analytics-api.onupkeep.com/v2/work-orders/dashboard"
-X GET
{
"success": true,
"results": [
{
"id": "WHjlKzI9h3",
"name": "Manish Sangwan",
"completed": "0",
"inProgress": "2",
"onHold": "0",
"open": "6",
"pastDue": "0",
"totalHours": "312.20",
"additionalCost": "0.00",
"priorityNone": "7",
"priorityLow": "0",
"priorityMedium": "1",
"priorityHigh": "0",
"averageHoursToComplete": "0.00"
}
],
"groupedBy": "user-assigned"
}
Public api for for fetching various aggregate counts eg Work Orders open, In progress, Avg time to complete etc. User can group by
different entities and apply various filters. By default data is fetched for Work Orders created within last month
NOTE: REPORTING API IS CURRENTLY IN BETA AND QUERY PARAMS/RESPONSE/FUNCTIONALITY IS LIKELY TO BE CHANGED IN NEAR FUTURE.
HTTP REQUEST
GET https://analytics-api.onupkeep.com/v2/work-orders/dashboard
QUERY PARAMETERS
timeZone UTC (String) Specifies your time-zone string, eg timeZone=America/New_York
(String) Entity to group data. Allowed Allowed values- user-assigned, user-created, user-completed,
user-
groupBy asset-assigned, team-assigned, category-assigned, requested-by, location-assigned. Default value
assigned
is user-assigned, eg groupBy=user-assigned
(String) To count for recurring Work Orders send value 'preventative' otherwise count will be made
workOrderType reactive
on non recurring Work Orders. eg workOrderType=preventative
assignedTo undefined (String) Filters Work Orders assigned to particular user. eg assignedTo=fjQXLsOvG7
createdBy undefined (String) Filters Work Orders created by particular user. eg createdBy=fjQXLsOvG7
completedBy undefined (String) Filters Work Orders completed by particular user. eg completedBy=fjQXLsOvG7
location undefined (String) Filters Work Orders attached to particular location. eg location=6yDTWLAEmh
asset undefined (String) Filters Work Orders attached to particular asset. eg asset=0kDUM9MnqF
category undefined (String) Filters Work Orders having to particular category. eg category=Project
(String) Filters Work Orders created after a particular time. Timestring is in your local time. eg
createdAtStart undefined
createdAtStart=2018-01-09T07:20:22 .By default createdAt is set to one month ago
(String) Filters Work Orders created before a particular time. Timestring is in your local time. eg
createdAtEnd undefined
createdAtEnd=2018-10-09T07:20:22
(String) Filters Work Orders updated after a particular time. Timestring is in your local time. eg
updatedAtStart undefined
updatedAtStart=2018-01-09T07:20:22
Filters Work Orders updated before a particular time. Timestring is in your local time. eg
updatedAtEnd undefined
updatedAtEnd=2018-10-09T07:20:22
(String) Filters Work Orders due after a particular time. Timestring is in your local time. eg
dueDateStart undefined
dueDateStart=2018-01-09T07:20:22
(String) Filters Work Orders due before a particular time. Timestring is in your local time. eg
dueDateEnd undefined
dueDateEnd=2018-10-09T07:20:22
(String) Filters Work Orders completed after a particular time. Timestring is in your local time. eg
dateCompletedStart undefined
dateCompletedStart=2018-01-09T07:20:22
(String) Filters Work Orders completed before a particular time. Timestring is in your local time. eg
dateCompletedEnd undefined
dateCompletedEnd=2018-10-09T07:20:22
Common Use Cases
The work-order API returns all single work orders for your UpKeep account. A common use case for UpKeep’s APIs are to utilize the fetch
work order API with specific filters to run your own reports. For example, if you wanted to generate a report on a specific set of work
orders, you may want to use the filter where userAssignedTo equals Tom to pull all work orders. From the response, you’ll be able to pull a
report and aggregate things like the total time, cost, and average time to completion for this group of individuals.
You may also want to generate a report for all preventative work orders. To do this you’ll want to use our preventative maintenance API
to find all of the root preventative maintenance work orders. To find the schedules of the preventative maintenance work orders, you’ll use
the ID of the root PM work orders and pass the root preventative maintenance work order into the “get work order schedule” API. With that
data, you will receive an array of all of the PMs that match the criteria so you can do aggregate reporting on PMs.
A common use case for the parts API may be to update and increase the quantity of a given part after you have received new inventory.
This could be a trigger set up from another system that tracks when new inventory has arrived at your facility.
A common use case for the asset API may be to utilize your tracking system to update the asset’s location. You can do that utilizing the
“update a specific asset” API. First, you may want to utilize the “get all locations” API to find the ID of the correct location and pass in the
location ID into the “update asset” API to update the asset’s location.
A common use case for utilizing the requests API would be to set up integrations with your company’s work order request system. You
may want to create UpKeep requests through our API without needing to manually enter the same information in.
Use the users API, to add, remove or update a specific user from your UpKeep account.
Errors
The UpKeep API uses the following error codes:
Error Code Meaning
400 Bad Request -- See the accompanying message.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The object requested is hidden for administrators only.
404 Not Found -- The specified object could not be found.
405 Method Not Allowed -- You tried to access a object with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- You're requesting too many objects! Slow down!
Error Code Meaning
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
If the API Endpoint returns an error of status 500 or 400, the body of the request will contain a message property. Below are common
messages:
Message Meaning
{field} cannot be null The {field} in your POST or PATCH request must contain a value.
invalid filter key: {field} The {field} in your GET request does not exist.
{field} not in schema The {field} with a value in your POST request does not exist.
{field} is not allowed to be set! The {field} in your PATCH request cannot be edited.
For any other errors, please contact info@onupkeep.com

Upkeep PDF

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Upkeep PDF

Enviado por

Direitos autorais:

Formatos disponíveis

6/5/2019 Introduction – UpKeep API Reference

Get The Schedule of Preventative Maintenance Work Orders

The above command returns JSON structured like this:

Provide a valid email and password.

Parameter Type Required

email String true

password String true

The above command returns JSON structured like this:

This endpoint invalidates an existing session.

The above command returns JSON structured like this:

This endpoint creates a new user.

Parameter Type Required Description

email String true

password String true

firstName String false

lastName String false

phoneNumber String false

Get All Users

The above command returns JSON structured like this:

This endpoint retrieves all users for your account.

Parameter Default Description

Parameter Default Description

offset undefined (Number) offset for pagination.

limit undefined (Number) limit for pagination.

Get a Specific User

The above command returns JSON structured like this:

This endpoint retrieves a specific user.

ID The ID of the user to retrieve

Update a Specific User

The above command returns JSON structured like this:

This endpoint updates a specific user.

ID The ID of the user to retrieve

Parameter Type Required

email String false

accountType String false

firstName String false

lastName String false

phoneNumber String false

The above command returns JSON structured like this:

This endpoint creates a new customer.

Parameter Type Required Description

name String true

email String false

description String false

address String false

phoneNumber String false

website String false

type String false

Parameter Type Required Description

billingName String false

billingAddressLine1 String false

billingAddressLine2 String false

billingAddressLine3 String false

Get All Customers

The above command returns JSON structured like this:

This endpoint retrieves all customers for your account.

Parameter Default Description

offset undefined (Number) offset for pagination.

limit undefined (Number) limit for pagination.

Get a Specific Customer

The above command returns JSON structured like this:

This endpoint retrieves a specific customer.

ID The ID of the customer to retrieve

Update a Specific Customer