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"

{
  "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/"
  -H "Session-Token: session_token_here"
  -X POST
  -d email="user@onupkeep.com"
  -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/"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "results": [
    {
      "id": "fjQXLsOvG7",
      "accountType": "ADMIN",
      "email": "user@onupkeep.com",
      "firstName": "Marty",
      "lastName": "McFly",
      "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.
orderBy	createdAt DESC	(String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

Get a Specific User

curl "https://api.onupkeep.com/api/v2/users/<ID>"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "result": {
    "id": "fjQXLsOvG7",
    "accountType": "ADMIN",
    "email": "user@onupkeep.com",
    "firstName": "Marty",
    "lastName": "McFly",
    "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

curl "https://api.onupkeep.com/api/v2/users/<ID>"
  -H "Session-Token: session_token_here"
  -X PATCH
  -d firstName="Doc"

{
  "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 updates a specific user.

HTTP Request

PATCH https://api.onupkeep.com/api/v2/users/<ID>

URL Parameters

Parameter	Description
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.

Parameter	Type	Required
email	String	false
accountType	String	false
firstName	String	false
lastName	String	false
phoneNumber	String	false

Customers

Create a Customer

curl "https://api.onupkeep.com/api/v2/customers/"
  -H "Session-Token: session_token_here"
  -X POST
  -d name="Mark Boucher"
  -d email="user@onupkeep.com"
  -d phoneNumber="800-123-4567"
  -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",
    "email": "user@onupkeep.com",
    "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.

Parameter	Type	Required
name	String	true
email	String	false
description	String	false
address	String	false
phoneNumber	String	false
website	String	false
type	String	false
billingName	String	false
billingAddressLine1	String	false
billingAddressLine2	String	false
billingAddressLine3	String	false

Get All Customers

curl "https://api.onupkeep.com/api/v2/customers/"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "results": [
    {
      "id": "fjQXLsOvG7",
      "name": "Mark Boucher",
      "email": "user@onupkeep.com",
      "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",
      "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

Parameter	Default	Description
name	undefined	If set the result will only include users with that name.
offset	undefined	(Number) offset for pagination.
limit	undefined	(Number) limit for pagination.
orderBy	createdAt DESC	(String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

Get a Specific Customer

curl "https://api.onupkeep.com/api/v2/customers/<ID>"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "result": {
    "id": "fjQXLsOvG7",
    "name": "Mark Boucher",
    "email": "user@onupkeep.com",
    "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",
    "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 a specific customer.

HTTP Request

GET https://api.onupkeep.com/api/v2/customers/<ID>

URL Parameters

Parameter	Description
ID	The ID of the customer to retrieve

Update a Specific Customer

curl "https://api.onupkeep.com/api/v2/customer/<ID>"
  -H "Session-Token: session_token_here"
  -X PATCH
  -d name="Rob"

{
  "success": true,
  "result": {
    "id": "fjQXLsOvG7",
    "name": "Rob",
    "email": "user@onupkeep.com",
    "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 updates a specific customer.

HTTP Request

PATCH https://api.onupkeep.com/api/v2/customers/<ID>

URL Parameters

Parameter	Description
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.

Parameter	Type	Required
name	String	false
email	String	false
description	String	false
address	String	false
phoneNumber	String	false
website	String	false
type	String	false
billingName	String	false
billingAddressLine1	String	false
billingAddressLine2	String	false
billingAddressLine3	String	false

Vendors

Create a Vendor

curl "https://api.onupkeep.com/api/v2/vendors/"
  -H "Session-Token: session_token_here"
  -X POST
  -d businessName="AVC Inc."
  -d email="user@onupkeep.com"
  -d phoneNumber="800-123-4567"
  -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.",
    "email": "user@onupkeep.com",
    "description": "A1 sevices manager",
    "businessAddress": "421 E Drachman, Hudson Street",
    "phoneNumber": "800-123-4567",
    "website": "www.aoneserv.com",
    "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.

Parameter	Type	Required
businessName	String	true
email	String	false
description	String	false
businessAddress	String	false
phoneNumber	String	false
website	String	false
type	String	false
mainPointOfContact	String	false

Get All Vendors

curl "https://api.onupkeep.com/api/v2/vendors/"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "results": [
    {
      "id": "fjQXLsOvG7",
      "businessName": "AVC Inc.",
      "email": "user@onupkeep.com",
      "description": "A1 sevices manager",
      "businessAddress": "421 E Drachman, Hudson Street",
      "phoneNumber": "800-123-4567",
      "website": "www.aoneserv.com",
      "type": "Raw-Material",
      "mainPointOfContact": "Mark Boucher",
      "customFieldsVendor": [
        {
          "id": "4mFPJFLwxa",
          "name": "Title",
          "value": "Manager",
          "createdByUser": "lv6FZopMhz",
          "updatedByUser": "lv6FZopMhz",
          "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

Parameter	Default	Description
businessName	undefined	If set the result will only include vendors with that businessName.
offset	undefined	(Number) offset for pagination.
limit	undefined	(Number) limit for pagination.
orderBy	createdAt DESC	(String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

Get a Specific Vendor

curl "https://api.onupkeep.com/api/v2/vendors/<ID>"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "result": {
    "id": "fjQXLsOvG7",
    "businessName": "AVC Inc.",
    "email": "user@onupkeep.com",
    "description": "A1 sevices manager",
    "businessAddress": "421 E Drachman, Hudson Street",
    "phoneNumber": "800-123-4567",
    "website": "www.aoneserv.com",
    "type": "Raw-Material",
    "mainPointOfContact": "Mark Boucher",
    "customFieldsVendor": [
      {
        "id": "4mFPJFLwxa",
        "name": "Title",
        "value": "Manager",
        "createdByUser": "lv6FZopMhz",
        "updatedByUser": "lv6FZopMhz",
        "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

Parameter	Description
ID	The ID of the vendors to retrieve

Update a Specific Vendor

curl "https://api.onupkeep.com/api/v2/vendors/<ID>"
  -H "Session-Token: session_token_here"
  -X PATCH
  -d businessName="Doc Inc"

{
  "success": true,
  "result": {
    "id": "fjQXLsOvG7",
    "businessName": "Doc Inc.",
    "email": "user@onupkeep.com",
    "description": "A1 sevices manager",
    "businessAddress": "421 E Drachman, Hudson Street",
    "phoneNumber": "800-123-4567",
    "website": "www.aoneserv.com",
    "type": "Raw-Material",
    "mainPointOfContact": "Mark Boucher",
    "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

Parameter	Description
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.

Parameter	Type	Required
businessName	String	false
email	String	false
description	String	false
businessAddress	String	false
phoneNumber	String	false
website	String	false
type	String	false
mainPointOfContact	String	false

Teams

Create a Team

curl "https://api.onupkeep.com/api/v2/teams/"
  -H "Session-Token: session_token_here"
  -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.

Parameter	Type	Required
name	String	true
description	String	true

Get All Teams

curl "https://api.onupkeep.com/api/v2/teams/"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "results": [
    {
      "id": "fjQXLsOvG7",
      "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 retrieves all teams for your account.

HTTP Request

GET https://api.onupkeep.com/api/v2/teams/

Query Parameters

Parameter	Default	Description
name	undefined	If set the result will only include teams with that name.
offset	undefined	(Number) offset for pagination.
limit	undefined	(Number) limit for pagination.
orderBy	createdAt DESC	(String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

Get a Specific Team

curl "https://api.onupkeep.com/api/v2/teams/<ID>"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "result": {
    "id": "fjQXLsOvG7",
    "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 retrieves a specific team.

HTTP Request

GET https://api.onupkeep.com/api/v2/teams/<ID>

URL Parameters

Parameter	Description
ID	The ID of the team to retrieve

Update a Specific Team

curl "https://api.onupkeep.com/api/v2/users/<ID>"
  -H "Session-Token: session_token_here"
  -X PATCH
  -d name="Team Marty"

{
  "success": true,
  "result": {
    "id": "fjQXLsOvG7",
    "name": "Team Marty",
    "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 updates a specific team.

HTTP Request

PATCH https://api.onupkeep.com/api/v2/teams/<ID>

URL Parameters

Parameter	Description
ID	The ID of the team to retrieve

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.

Parameter	Type	Required
name	String	true
description	String	true

Delete a Specific Team

curl "https://api.onupkeep.com/api/v2/teams/<ID>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
ID	The ID of the team to retrieve

Get All Users for a Specific Team

curl "https://api.onupkeep.com/api/v2/teams/<teamID>/users"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "results": [
    {
      "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 retrieves all users for a specific team.

HTTP Request

GET https://api.onupkeep.com/api/v2/teams/<teamID>/users

URL Parameters

Parameter	Description
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
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/"
  -H "Session-Token: session_token_here"
  -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.

Parameter	Type	Required
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
description	String	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"
  -H "Session-Token: session_token_here"

{
  "success": true,
  "results": [
    {
      "id": "fjQXLsOvG7",
      "UPCNumber": "S5614B09118",
      "additionalInformation": "2 feet by 2 feet",
      "model": "Deluxe 5500",
      "name": "The Ultra Power Generator",
      "notes": "Oldest generator in use",
      "numberOfIncompleteWorkOrders": 55,
      "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",
      "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

Parameter	Default	Description
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.
offset	undefined	(Number) offset for pagination.
limit	undefined	(Number) limit for pagination.
includes	undefined	(Array) send 'location','assignedToUser', 'createdByUser' to expand respective object
orderBy	createdAt DESC	(String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

Get a Specific Asset

curl "https://api.onupkeep.com/api/v2/assets/fjQXLsOvG7"
  -H "Session-Token: session_token_here"

{
  "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",
      "numberOfIncompleteWorkOrders": 55,
      "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",
      "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

Parameter	Description
ID	The ID of the asset to retrieve

Query Parameters

Parameter	Default	Description
includes	undefined	(Array) send 'location','assignedToUser', 'createdByUser', 'assignedUsers', 'assignedTeams', 'assignedCustomers', 'assignedVendors to expand respective object.

Update a Specific Asset

curl "https://api.onupkeep.com/api/v2/assets/fjQXLsOvG7"
  -H "Session-Token: session_token_here"
  -X PATCH
  -d name="The Amazing Power Generator"

{
  "success": true,
  "result": [
    {
      "id": "fjQXLsOvG7",
      "UPCNumber": "S5614B09118",
      "additionalInformation": "2 feet by 2 feet",
      "model": "Deluxe 5500",
      "name": "The Amazing Power Generator",
      "notes": "Oldest generator in use",
      "numberOfIncompleteWorkOrders": 55,
      "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 updates a specific asset.

HTTP Request

PATCH https://api.onupkeep.com/api/v2/assets/<ID>

URL Parameters

Parameter	Description
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)
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
  -H "Session-Token: session_token_here"

{
  "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

Parameter	Description
ID	The ID of the asset to delete

Assign User to an Asset

curl "https://api.onupkeep.com/api/v2/assets/<assetID>/users/<userID>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
assetID	The ID of the desired asset
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
assetID	The ID of the desired asset
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
assetID	The ID of the desired asset
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
assetID	The ID of the desired asset
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
assetID	The ID of the desired asset
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
assetID	The ID of the desired asset
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
assetID	The ID of the desired asset
vendorID	The ID of the vendor to be removed from asset.

Locations

Create a Location

curl "https://api.onupkeep.com/api/v2/locations/"
  -H "Session-Token: session_token_here"
  -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",
      "createdByUser": "lv6FZopMhz",
      "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.

Parameter	Type	Required
name	String	true
address	String	false
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"
  -H "Session-Token: session_token_here"

{
  "success": true,
  "results": [
    {
      "id": "jpSMgHPr11",
      "createdByUser": "lv6FZopMhz",
      "createdByUsername": "test@onupkeep.com",
      "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

Parameter	Default	Description
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.
offset	undefined	(Number) offset for pagination.
limit	undefined	(Number) limit for pagination.
includes	undefined	(Array) send 'createdByUser' to expand respective object.
orderBy	createdAt DESC	(String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

Get a Specific Location

curl "https://api.onupkeep.com/api/v2/locations/fjQXLsOvG7"
  -H "Session-Token: session_token_here"

{
  "success": true,
  "result": {
    "id": "jpSMgHPr11",
    "createdByUser": "lv6FZopMhz",
    "createdByUsername": "test@onupkeep.com",
    "name": "Meeting Room",
    "address": "11087 Sunset Blvd, Los Angeles, CA 90049, USA",
    "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

Parameter	Description
ID	The ID of the location to retrieve

Query Parameters

Parameter	Default	Description
includes	undefined	(Array) send 'createdByUser', 'assignedUsers', 'assignedTeams', 'assignedCustomers', 'assignedVendors to expand respective object.

Update a Specific Location

curl "https://api.onupkeep.com/api/v2/locations/fjQXLsOvG7"
  -H "Session-Token: session_token_here"
  -X PATCH
  -d name="Conference Room"

{
  "success": true,
  "result": [
    {
      "id": "jpSMgHPr11",
      "createdByUser": "lv6FZopMhz",
      "createdByUsername": "test@onupkeep.com",
      "name": "Conference 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 updates a specific location.

HTTP Request

PATCH https://api.onupkeep.com/api/v2/locations/<ID>

URL Parameters

Parameter	Description
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
  -H "Session-Token: session_token_here"

{
  "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

Parameter	Description
ID	The ID of the location to delete

Assign User to a Location

curl "https://api.onupkeep.com/api/v2/locations/<locationID>/users/<userID>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
locationID	The ID of the desired location
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
locationID	The ID of the desired location
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
locationID	The ID of the desired location
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
locationID	The ID of the desired location
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
locationID	The ID of the desired location
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
locationID	The ID of the desired location
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>"
  -H "Session-Token: session_token_here"
  -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

Parameter	Description
locationID	The ID of the desired location
vendorID	The ID of the vendor to be removed from location.

Parts

Create a Part

curl "https://api.onupkeep.com/api/v2/parts/"
  -H "Session-Token: session_token_here"
  -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.

Parameter	Type	Required	Description
name	String	true
description	String	false
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"
  -H "Session-Token: session_token_here"

{
  "success": true,
  "results": [
    {
      "id": "1YHUWGVgdC",
      "image": {
        "name": "dfimg_part_du.jpg",
        "url": "https://upkeep-production.s3.amazonaws.com/dfimg_part_du.jpg"
      },
      "name": "Flux Capacitor",
      "description": "This is what makes time travel possible.",
      "cost": "88.00",
      "quantity": "5",
      "minimumQuantity": "1",
      "serial": "40161502",
      "area": "Mark street",
      "details": "additional details",
      "category": "Filter",
      "location": "jmHFWGVgd1",
      "createdByUser": "pCmWGVgfW",
      "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

Parameter	Default	Description
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.
offset	undefined	(Number) offset for pagination.
limit	undefined	(Number) limit for pagination.
includes	undefined	(Array) send 'location', createdByUser' to expand respective object.
orderBy	createdAt DESC	(String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

Get a Specific Part

curl "https://api.onupkeep.com/api/v2/parts/1YHUWGVgdC"
  -H "Session-Token: session_token_here"

{
  "success": true,
  "result": {
    "id": "1YHUWGVgdC",
    "image": {
      "name": "dfimg_part_du.jpg",
      "url": "https://upkeep-production.s3.amazonaws.com/dfimg_part_du.jpg"
    },
    "name": "Flux Capacitor",
    "description": "This is what makes time travel possible.",
    "cost": "88.00",
    "quantity": "5",
    "minimumQuantity": "1",
    "serial": "40161502",
    "area": "Mark street",
    "details": "additional details",
    "category": "Filter",
    "location": "jmHFWGVgd1",
    "createdByUser": "pCmWGVgfW",
    "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

Parameter	Description
ID	The ID of the part to retrieve

Query Parameters

Parameter	Default	Description
includes	undefined	(Array) send 'location', createdByUser' to expand respective object.

Update a Specific Part

curl "https://api.onupkeep.com/api/v2/parts/1YHUWGVgdC"
  -H "Session-Token: session_token_here"
  -X PATCH
  -d quantity=100

{
  "success": true,
  "result": [
    {
    "id": "1YHUWGVgdC",
    "image": {
      "name": "dfimg_part_du.jpg",
      "url": "https://upkeep-production.s3.amazonaws.com/dfimg_part_du.jpg"
    },
    "name": "Flux Capacitor",
    "description": "This is what makes time travel possible.",
    "cost": "88.00",
    "quantity": "100",
    "minimumQuantity": "1",
    "serial": "40161502",
    "area": "Mark street",
    "details": "additional details",
    "category": "Filter",
    "location": "jmHFWGVgd1",
    "createdByUser": "pCmWGVgfW",
    "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

Parameter	Description
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
  -H "Session-Token: session_token_here"

{
  "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

Parameter	Description
ID	The ID of the part to delete

Requests

Create a Request

curl "https://api.onupkeep.com/api/v2/requests/"
  -H "Session-Token: session_token_here"
  -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

Provide any of the below required fields and optional fields for the user.

Parameter	Type	Required	Description
title	String	true
description	String	false
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:

If your account has a Zapier integration enabled, data will be sent to Zapier for the new request trigger
"New Request" emails will be sent to admins alerting them.

Get All Requests

curl "https://api.onupkeep.com/api/v2/requests"
  -H "Session-Token: session_token_here"

{
  "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

Parameter	Default	Description
requestedByUser	undefined	(ID) id of the upkeep user who created the request.if provided will show only requests requested by the user.
publicRequesterEmail	undefined	(String) email id of requester(request via request portal/via email). if provided will show only requests requested by the user. request will have either requestedByUser or publicRequesterEmail set.
offset	undefined	(Number) offset for pagination.
limit	undefined	(Number) limit for pagination.
includes	undefined	(Array) send 'asset' to expand respective object.
orderBy	createdAt DESC	(String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

Get a Specific Request

curl "https://api.onupkeep.com/api/v2/requests/HW2I379ErS"
  -H "Session-Token: session_token_here"

{
  "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",
          "name": "dfimg_request2.jpg",
          "url": "https://demo-api-upkeep.s3.amazonaws.com/dfimg_request2.jpg"
        },
      "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

Parameter	Description
ID	The ID of the request to retrieve

Query Parameters

Parameter	Default	Description
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
  -H "Session-Token: session_token_here"

{
  "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

Parameter	Description
ID	The ID of the request to cancel

Events After Request is Cancelled

If the API returns with status 200:

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
  -H "Session-Token: session_token_here"

{
  "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

Parameter	Description
ID	The ID of the request to delete

Work Orders

Create a Work Order

curl "https://api.onupkeep.com/api/v2/work-orders/"
  -H "Session-Token: session_token_here"
  -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

Provide any of the below required fields and optional fields for the user.

Parameter	Type	Required	Description
title	String	true
description	String	false
priority	Number	false	0,1,2,3. 0 being lowest
category	String	false	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

If the API returns with status 200:

If your account has a Zapier integration enabled, data will be sent to Zapier for the new Work Order trigger.
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"
  -H "Session-Token: session_token_here"

{
  "success": true,
  "results": [
    {
      "id": "HW2I379ErS",
      "workOrderNo": "014",
      "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",
      "category": "Electrical",
      "formItems": [
        "YChe6OjzHC",
        "FuJBoOf8Di",
        "e2iFG6t7I9"
      ],
      "assignedByUser": "5ZXaLRZ40I",
      "assignedByUsername": "test@onupkeep.com",
      "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,
      "category": "Electrical",
      "image": {
          "__type": "File",
          "name": "dfimg_request2.jpg",
          "url": "https://demo-api-upkeep.s3.amazonaws.com/dfimg_request2.jpg"
      },
      "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, except for Preventative Maintenance work orders.

To fetch the first work order created for each of your repeating schedules (root recurring work order), check out the section Get All Preventative Maintenance Work Orders
To fetch work orders included in a repeating schedule, excluding the root recurring work order, (ie., children of root recurring work orders) check out the section Get The Schedule of Preventative Maintenance Work Orders

HTTP Request

GET https://api.onupkeep.com/api/v2/work-orders

Query Parameters

Parameter	Default	Description
title	undefined	If set, only work orders with this title will be included.
isComplete	undefined	If set to "0", the result will only include work orders that have not been completed. If set to "1", the result will only include work orders that have been completed.
status	undefined	If set, the work orders fetched will be of the specified status only(allowed values '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.
offset	undefined	(Number) offset for pagination.
limit	undefined	(Number) limit for pagination.
includes	undefined	(Array) send 'asset', 'location', 'assignedToUser', 'team', 'formItems', 'parts' to expand respective object.
orderBy	createdAt DESC	(String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt', 'dueDate', 'dateCompleted'. Second value: "ASC" or "DESC".

Note

For querying on dates eg
createdAt, updatedAt ,dueDate ,dateCompleted etc
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"
  -H "Session-Token: session_token_here"

{
  "success": true,
  "result": {
      "id": "HW2I379ErS",
      "workOrderNo": "014",
      "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",
      "time": "20",
      "cost": "25",
      "location": "Mkr457Gkk3",
      "team": "PD6I909nLS",
      "category": "Electrical",
      "assignedByUser": "5ZXaLRZ40I",
      "assignedByUsername": "test@onupkeep.com",
      "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,
      "category": "Electrical",
      "files": [
          "2HMRIGeDKu"
      ],
      "formItems": [
        "YChe6OjzHC",
        "FuJBoOf8Di",
        "e2iFG6t7I9"
      ],
      "image": {
         "__type": "File",
         "name": "dfimg_request2.jpg",
         "url": "https://demo-api-upkeep.s3.amazonaws.com/dfimg_request2.jpg"
      },
      "image2": {...},
      "image3": {...},
      "image4": {...},
      "image5": {...},
      "arrayOfUpdateItems": [
        "dGCW3cSjWv",
        "SPRXIDJDZ1"
      ],
      "parts": [
        "sDmjnbbpAL",
        "QhWwJbfGb4"
      ],
      "respectivePartQuantityUsed": [
        5,
        1
      ],
      "additionalUsers": [
        "vk6BHzQVCX",
        "lv6FZopMhz"
      ],
      "publicRequesterEmail": "test@onupkeep.com",
      "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

Parameter	Description
ID	The ID of the work order to retrieve

Query Parameters

Parameter	Default	Description
includes	undefined	(Array) send 'asset', 'location', 'assignedToUser', 'assignedByUser', 'team', 'formItems', 'arrayOfUpdateItems', 'parts', 'additionalUsers' to expand respective object.

Update a Specific Work Order

curl "https://api.onupkeep.com/api/v2/work-orders/<ID>"
  -H "Session-Token: session_token_here"
  -X PATCH
  -d title="Repair Sink"
  -d category="Electrical"

{
  "success": true,
  "result": {
      "id": "HW2I379ErS",
      "workOrderNo": "014",
      "title": "Repair Sink",
      "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",
      "category": "Electrical",
      "assignedByUser": "5ZXaLRZ40I",
      "assignedByUsername": "test@onupkeep.com",
      "estimatedDurationInHours" : 5,
      "priority": "1",
      "image": {
         "__type": "File",
         "name": "dfimg_request2.jpg",
         "url": "https://demo-api-upkeep.s3.amazonaws.com/dfimg_request2.jpg"
      },
      "image2": {...},
      "image3": {...},
      "image4": {...},
      "image5": {...},
      "publicRequesterEmail": "test@onupkeep.com",
      "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

Parameter	Description
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
priority	Number	false
asset	String	false
location	String	false
assignedToUser	String	false
estimatedDurationInHours	Number

Events After Work Order is Updated

If the API returns with status 200:

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
  -H "Session-Token: session_token_here"
  -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
  -H "Session-Token: session_token_here"

{
  "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

Parameter	Description
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/"
  -H "Session-Token: session_token_here"
  -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",
    "assignedToUsername": "test@onupkeep.com",
    "asset": "gDK45aHe12",
    "location": "MD565aHenL",
    "assignedByUser": "lv6FZopMhz",
    "assignedByUsername": "test@onupkeep.com",
    "rescheduledBasedOnCompletion": true,
    "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

Provide any of the below required fields and optional fields for the user.

Parameter	Type	Required	Description
title	String	true
recurringSchedule	String	true	Represents the frequency of repetition. Allowed values 'daily', 'weekly', 'twoWeeks', 'monthly', twoMonths', 'threeMonths', 'sixMonths', 'yearly'. For repetition on certain days of week send comma separated day codes. Allowed day codes- 'Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'. eg "Su,Th,Fr".
description	String	false
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
estimatedDurationInHours	Number	false
assignedToUser	String	false	id of user whom the Work Order is assigned
rescheduledBasedOnCompletion	Boolean	false	boolean true is sent if next instance of work Order is to be created only if last child is complete. By default its false.

Events After Work Order is Created

If the API returns with status 200:

If your account has a Zapier integration enabled, data will be sent to Zapier for the new Work Order trigger.
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"
  -H "Session-Token: session_token_here"

{
  "success": true,
  "results": [
    {
      "id": "6yDTWLAEmh",
      "title": "Check Oil",
      "status": "open",
      "dueDate": "2018-01-09T07:20:22.310Z",
      "endDueDate": "2018-01-30T02:30:00.000Z",
      "recurringSchedule": "daily",
      "assignedToUser": "vk6BHzQVCX",
      "assignedToUsername": "test@onupkeep.com",
      "asset": "knyWfDnXWo",
      "location": "cXRAu708NU",
      "time": "20",
      "cost": "25",
      "assignedByUser": "lv6FZopMhz",
      "assignedByUsername": "test@onupkeep.com",
      "priority": 1,
      "description": "Confirm the tractor is optimal",
      "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. A preventative maintenance work order or a root recurring work order is a blue print or template from which its clones/children recurring work orders are created based on the recurring frequency. This end point only fetches all root recurring work orders i.e. the root recurring Work order templates for your account which we call Preventative Maintenance Work Orders.

HTTP Request

GET https://api.onupkeep.com/api/v2/preventative-maintenance

Query Parameters

Parameter	Default	Description
title	undefined	If set, only work orders with this title will be included.
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.
recurringSchedule	undefined	If set, only work orders with this repeating schedule 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.
offset	undefined	(Number) offset for pagination.
limit	undefined	(Number) limit for pagination.
includes	undefined	(Array) send 'asset', 'location', 'assignedToUser', 'team' to expand respective object.
orderBy	createdAt DESC	(String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt', 'dueDate'. Second value: "ASC" or "DESC".
rescheduledBasedOnCompletion	undefined	(String) send 'true' or 'false' to filter Work Orders rescheduled based on completion

Get a Specific Preventative Maintenance Work Order

curl "https://api.onupkeep.com/api/v2/preventative-maintenance/HW2I379ErS"
  -H "Session-Token: session_token_here"

{
  "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": "vk6BHzQVCX",
    "time": "20",
    "cost": "25",
    "assignedToUsername": "test@onupkeep.com",
    "asset": "knyWfDnXWo",
    "location": "cXRAu708NU",
    "assignedByUser": "lv6FZopMhz",
    "assignedByUsername": "test@onupkeep.com",
    "priority": 1,
    "description": "Confirm the tractor is optimal",
    "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

Parameter	Description
ID	The ID of the preventative maintenance work order to retrieve

Query Parameters

Parameter	Default	Description
includes	undefined	(Array) send 'asset', 'location', 'assignedToUser', 'assignedByUser', 'team', 'formItems', 'arrayOfUpdateItems', 'parts', 'additionalUsers' to expand respective object.

Update a Preventative Maintenance Work Order

curl "https://api.onupkeep.com/api/v2/preventative-maintenance/"
  -H "Session-Token: session_token_here"
  -X POST
  -d title="Check Oil"
  -d description="Confirm the tractor is optimal"
  -d priority=1
  -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",
    "assignedToUsername": "test@onupkeep.com",
    "asset": "gDK45aHe12",
    "location": "MD565aHenL",
    "assignedByUser": "lv6FZopMhz",
    "assignedByUsername": "test@onupkeep.com",
    "rescheduledBasedOnCompletion": true,
    "priority": 1,
    "description": "Confirm the tractor is optimal",
    "createdAt": "2018-01-09T07:56:53.743Z",
    "updatedAt": "2018-01-09T07:56:53.743Z"
  }
}

This endpoint updates a new Preventative Work Order.

HTTP Request

PATCH https://api.onupkeep.com/api/v2/preventative-maintenance/<ID>

Request Body

Provide any of the below required fields and optional fields for the user.

Parameter	Type	Required	Description
title	String	false
description	String	false
priority	Number	false
estimatedDurationInHours	Number	false
category	String	false
asset	String	false	id of asset
location	String	false	id of location
assignedToUser	String	false	id of user whom the Work Order is assigned

Delete a Specific Preventative Maintenance Work Order

curl "https://api.onupkeep.com/api/v2/preventative-maintenance/jQXLsOvG7"
  -X DELETE
  -H "Session-Token: session_token_here"

{
  "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

Parameter	Description
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"
  -H "Session-Token: session_token_here"

{
  "success": true,
  "results": [
    {
      "title": "Check Oil",
      "status": "open",
      "dueDate": "2018-01-09T07:20:22.310Z",
      "assignedToUser": "vk6BHzQVCX",
      "assignedToUsername": "test@onupkeep.com",
      "asset": "knyWfDnXWo",
      "location": "cXRAu708NU",
      "time": "20",
      "cost": "25",
      "assignedByUser": "lv6FZopMhz",
      "assignedByUsername": "test@onupkeep.com",
      "priority": 1,
      "description": "Confirm the tractor is optimal",
      "createdAt": "2018-01-09T07:56:53.743Z",
      "updatedAt": "2018-01-09T07:56:53.743Z"
    }
  ]
}

This endpoint retrieves the schedule of all preventative maintenance work orders for your account.

Disclaimer: If the limit is set to n, this endpoint may still return results >= n. This is because the pagination is based on the root recurring Work Orders. So, when the limit is set to n, our servers fetch n root work orders from your account, then calculate their generated schedule (child work orders) and send those back.

HTTP Request

GET https://api.onupkeep.com/api/v2/work-order-schedule

Query Parameters

Parameter	Default	Description
utcOffset	0	Difference between UTC and your time-zone in minutes.
title	undefined	If set, only work orders with this title will be included.
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.
includes	undefined	(Array) send 'asset', 'location', 'assignedToUser', 'team' to expand respective object.
rescheduledBasedOnCompletion	undefined	(String) send 'true' or 'false' to filter Work Orders rescheduled based on completion
offset	undefined	(Number) offset for pagination. The pagination is based on root Work Orders i.e. Preventative Maintenance Work Orders
limit	undefined	(Number) limit for pagination. The pagination is based on root Work Orders i.e. Preventative Maintenance Work Orders

Meters

Create a Meter

curl "https://api.onupkeep.com/api/v2/meters/"
  -H "Session-Token: session_token_here"
  -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,
    "createdByUser": "lv6FZopMhz",
    "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.

Parameter	Type	Required	Description
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/"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "results": [
    {
      "id": "WEeI86SMu4",
      "name": "Mileage",
      "units": "KMPL",
      "frequency": 7,
      "createdByUser": "lv6FZopMhz",
      "location": "M75FZevseo",
      "asset": "KXi4CS5Nft",
      "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

Parameter	Default	Description
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.
offset	undefined	(Number) offset for pagination.
limit	undefined	(Number) limit for pagination.
includes	undefined	(Array) send 'asset', 'location', 'lastReading' to expand respective object.
orderBy	createdAt DESC	(String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

Get a Specific Meter

curl "https://api.onupkeep.com/api/v2/meters/<ID>"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "result": {
    "id": "WEeI86SMu4",
    "name": "Mileage",
    "units": "KMPL",
    "frequency": 7,
    "createdByUser": "lv6FZopMhz",
    "location": "M75FZevseo",
    "asset": "KXi4CS5Nft",
    "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

Parameter	Description
ID	The ID of the meter to retrieve

Query Parameters

Parameter	Default	Description
includes	undefined	(Array) send 'asset', 'location', 'lastReading' to expand respective object.

Update a Specific Meter

curl "https://api.onupkeep.com/api/v2/meters/<ID>"
  -H "Session-Token: session_token_here"
  -X PATCH
  -d frequency=4

{
  "success": true,
  "result": {
    "id": "WEeI86SMu4",
    "name": "Mileage",
    "units": "KMPL",
    "frequency": 4,
    "createdByUser": "lv6FZopMhz",
    "location": "M75FZevseo",
    "asset": "KXi4CS5Nft",
    "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

Parameter	Description
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.

Parameter	Type	Required	Description
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

curl "https://api.onupkeep.com/api/v2/meters/<ID>"
  -X DELETE
  -H "Session-Token: session_token_here"

{
  "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

Parameter	Description
ID	The ID of the meter to delete

Add a Reading to a Meter

curl "https://api.onupkeep.com/api/v2/meters/<meterID>/readings"
  -H "Session-Token: session_token_here"
  -X POST
  -d value=1

{
  "success": true,
  "result": {
    "id": "iGIkXrVtGS",
    "date": "2018-01-30T10:05:20.402Z",
    "meter": "GvWe2sCUkY",
    "value": 1,
    "createdByUser": "lv6FZopMhz",
    "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.

Parameter	Type	Required	Description
value	Number	true

URL Parameters

Parameter	Description
meterID	The ID of the meter

Events After Reading is Added

If the API returns with status 200:

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"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "results": [
    {
      "id": "iGIkXrVtGS",
      "date": "2018-01-30T10:05:20.402Z",
      "meter": "GvWe2sCUkY",
      "value": 1,
      "createdByUser": "lv6FZopMhz",
      "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

Parameter	Default	Description
offset	undefined	(Number) offset for pagination.
limit	undefined	(Number) limit for pagination.
includes	undefined	(Array) send 'createdByUser' expand respective object.
orderBy	createdAt DESC	(String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

URL Parameters

Parameter	Description
meterID	The ID of the meter

Create a Meter Notification

curl "https://api.onupkeep.com/api/v2/meters/<meterID>/notifications"
  -H "Session-Token: session_token_here"
  -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",
    "createdByUser": "lv6FZopMhz",
    "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.

Parameter	Type	Required	Description
title	String	true	Title of Work Order to create on trigger.
triggerValue	Number	true	Value to be compared for trigger.
triggerFrequency	String	true	Comparison operator for trigger. Allowed values- 'ONE_TIME_IS_GREATER_THAN', '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

Parameter	Description
meterID	The ID of the meter

Get All Meter Notifications

curl "https://api.onupkeep.com/api/v2/meters/<meterID>/notifications"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "results": [
    {
      "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",
      "createdByUser": "lv6FZopMhz",
      "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

Parameter	Default	Description
offset	undefined	(Number) offset for pagination.
limit	undefined	(Number) limit for pagination.
includes	undefined	(Array) send 'assignedToUser', 'createdByUser' expand respective object.
orderBy	createdAt DESC	(String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

URL Parameters

Parameter	Description
meterID	The ID of the meter

Get a Specific Meter Notification

curl "https://api.onupkeep.com/api/v2/meters/<meterID>/notifications/<ID>"
  -H "Session-Token: session_token_here"
  -X GET

{
  "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",
    "createdByUser": "lv6FZopMhz",
    "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

Parameter	Description
ID	The ID of the meter notification to retrieve
meterID	The ID of the meter

Query Parameters

Parameter	Default	Description
includes	undefined	(Array) send 'assignedToUser', 'createdByUser' expand respective object.

Update a Specific Meter Notification

curl "https://api.onupkeep.com/api/v2/meters/<meterID>/notifications/<ID>"
  -H "Session-Token: session_token_here"
  -X PATCH
  -d assignedToUser="MtmhmKKg56"

{
  "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": "MtmhmKKg56",
    "createdByUser": "lv6FZopMhz",
    "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

Parameter	Description
ID	The ID of the meter notification to update
meterID	The ID of the meter

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.

Parameter	Type	Required	Description
title	String	false	Title of Work Order to create on trigger.
triggerValue	Number	false	Value to be compared for trigger.
triggerFrequency	String	false	Comparison operator for trigger. Allowed values- 'ONE_TIME_IS_GREATER_THAN', '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

curl "https://api.onupkeep.com/api/v2/meters/<meterID>/notifications/<ID>"
  -X DELETE
  -H "Session-Token: session_token_here"

{
  "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

Parameter	Description
ID	The ID of the meter notification to delete
meterID	The ID of the meter

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",
   "purchaseOrderNumber": 100,
   "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
    ],
    "partsPendingQuantities": {
      "t0RYP2jIPz": 5
    },
    "partialFulfillHistory": [],
    "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": 100,
    "category": "Electrical",
    "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.

Parameter	Type	Required	Description
title	String	true
purchaseOrderNumber	Number	false	Set a custom purchase order number, if not passed, the default one from settings will be used.
parts	Array	false	Array Of objects containg part id and quantity
vendor	String	false	(ID) of vendor
description	String	false
category	String	false
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/"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "results": [
    {
      "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
      ],
      "partsPendingQuantities": {
          "t0RYP2jIPz": 5
      },
      "partialFulfillHistory": [],
      "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,
      "category": "Electrical",
      "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

Parameter	Default	Description
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.
offset	undefined	(Number) offset for pagination.
limit	undefined	(Number) limit for pagination.
includes	undefined	(Array) send 'vendor'expand object.
orderBy	createdAt DESC	(String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

Get a Specific Purchase Order

curl "https://api.onupkeep.com/api/v2/purchase-orders/<ID>"
  -H "Session-Token: session_token_here"
  -X GET

{
  "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
    ],
    "partsPendingQuantities": {
        "t0RYP2jIPz": 5
    },
    "partialFulfillHistory": [],
    "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,
    "category": "Electrical",
    "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

Parameter	Description
ID	The ID of the Purchase Order to retrieve

Query Parameters

Parameter	Default	Description
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 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X PATCH
  -d '{"status": "fulfilled"}'

{
  "success": true,
  "result": {
    "id": "XHUi1SyW0t",
    "createdByUser": "7w6jIHFdEr",
    "title": "Power dice shortage",
    "description": "Small dice model 5",
    "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",
    "vendor": "IPS0tjjV5I",
    "parts": [
        "t0RYP2jIPz"
    ],
    "partQuantities": [
        5
    ],
    "partsPendingQuantities": {
        "t0RYP2jIPz": 5
    },
    "partialFulfillHistory": [],
    "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,
    "category": "Electrical",
    "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

Parameter	Description
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.

Parameter	Type	Description
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

Partially Fulfill a Purchase Order

curl 'https://api.onupkeep.com/api/v2/purchase-orders/<ID>'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X PATCH
  -d '{
        "partsReceived": {
          "t0RYP2jIPz": 3
        },
        "statusAction": "partially-fulfilled"
      }'

{
  "success": true,
  "result": {
    "id": "XHUi1SyW0t",
    "createdByUser": "7w6jIHFdEr",
    "title": "Power dice shortage",
    "description": "Small dice model 5",
    "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",
    "vendor": "IPS0tjjV5I",
    "parts": [
        "t0RYP2jIPz"
    ],
    "partQuantities": [
        5
    ],
    "partsPendingQuantities": {
        "t0RYP2jIPz": 2
    },
    "partialFulfillHistory": [
        {
            "timestamp": "2019-05-03T10:09:35.165Z",
            "user": "TRdK0rLIOj",
            "received": {
                "t0RYP2jIPz": 3,
            }
        }
    ],
    "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,
    "category": "Electrical",
    "createdAt": "2018-06-08T09:15:46.452Z",
    "updatedAt": "2018-06-08T09:15:46.452Z"
  }
}

This API call partially fulfills a Purchase Order.

HTTP Request

PATCH https://api.onupkeep.com/api/v2/purchase-orders/<ID>

URL Parameters

Parameter	Description
ID	The ID of the Purchase Order to partially-fulfill

Request Body

Provide all of the below body params to execute a partial-fulfill on a purchase order.

Parameter	Type	Description
statusAction	String	Allowed value: `partially-fulfilled`
partsReceived	Object	An object containing parts' IDs and their respective fulfilled quantities.

{
    "success": false,
    "message": "Invalid partial-fulfill values; should be valid positive numbers",
}

{
    "success": false,
    "message": "Can partially-fulfill only if status is approved or partially-fulfilled.",
}

{
    "success": false,
    "message": "Invalid partial-fulfillment values - should not be more than pending quantities"
}

Note

Note that on partial fulfillment of parts, the fields partsPendingQuantities and partialFulfillHistory change.

partsPendingQuantities: This stores the fulfillment pending counts of parts.
partialFulfillHistory: This stores a history of all partial fulfillments - basically a record of the user who did the partial-fulfillment, and the received counts of partially-fulfilled parts, along with a timestamp.

Delete a Specific Purchase Order

curl "https://api.onupkeep.com/api/v2/purchase-orders/<ID>"
  -X DELETE
  -H "Session-Token: session_token_here"

{
  "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

Parameter	Description
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"
  -H "Session-Token: session_token_here"
  -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.

Parameter	Type	Required	Description
text	String	true

URL Parameters

Parameter	Description
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/'
  -H 'Session-Token: session_token_here'
  -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.

Parameter	Type	Required	Description
name	String	true

Get All Purchase Orders Categories

curl "https://api.onupkeep.com/api/v2/purchase-order-categories/"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "results": [
    {
      "id": "G25KW7hlV0",
      "name": "Electrical",
      "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>"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "result": {
    "id": "G25KW7hlV0",
    "name": "Electrical",
    "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

Parameter	Description
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>'
  -H 'Session-Token: session_token_here'
  -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

Parameter	Description
ID	The ID of the Purchase Order Category to update

Request Body

Parameter	Type	Description
name	String

Delete a Specific Purchase Order Category

curl "https://api.onupkeep.com/api/v2/purchase-order-categories/<ID>"
  -X DELETE
  -H "Session-Token: session_token_here"

{
  "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

Parameter	Description
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"
  -H "Session-Token: session_token_here"
  -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

Parameter	Default	Description
timeZone	UTC	(String) Specifies your time-zone string, eg timeZone=America/New_York
groupBy	user-assigned	(String) Entity to group data. Allowed Allowed values- user-assigned, user-created, user-completed, asset-assigned, team-assigned, category-assigned, requested-by, location-assigned. Default value is user-assigned, eg groupBy=user-assigned
workOrderType	reactive	(String) To count for recurring Work Orders send value 'preventative' otherwise count will be made 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
createdAtStart	undefined	(String) Filters Work Orders created after a particular time. Timestring is in your local time. eg createdAtStart=2018-01-09T07:20:22 .By default createdAt is set to one month ago
createdAtEnd	undefined	(String) Filters Work Orders created before a particular time. Timestring is in your local time. eg createdAtEnd=2018-10-09T07:20:22
updatedAtStart	undefined	(String) Filters Work Orders updated after a particular time. Timestring is in your local time. eg updatedAtStart=2018-01-09T07:20:22
updatedAtEnd	undefined	Filters Work Orders updated before a particular time. Timestring is in your local time. eg updatedAtEnd=2018-10-09T07:20:22
dueDateStart	undefined	(String) Filters Work Orders due after a particular time. Timestring is in your local time. eg dueDateStart=2018-01-09T07:20:22
dueDateEnd	undefined	(String) Filters Work Orders due before a particular time. Timestring is in your local time. eg dueDateEnd=2018-10-09T07:20:22
dateCompletedStart	undefined	(String) Filters Work Orders completed after a particular time. Timestring is in your local time. eg dateCompletedStart=2018-01-09T07:20:22
dateCompletedEnd	undefined	(String) Filters Work Orders completed before a particular time. Timestring is in your local time. eg 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!
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