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. 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/

Expanding Responses

Because of the nested nature of UpKeep, responses may contain additional information. The API allows you to expand these responses using the includes query parameter. There are several ways they can be expanded since the parameter can take either an array or string value.

Arrays in query parameters can be passed by repeating the parameter multiple times:
GET https://api.onupkeep.com/api/v2/parts?includes=createdByUser&includes=location&includes=files
Arrays in query parameters can also be passed by repeating a parameter along with empty square brackets:
GET https://api.onupkeep.com/api/v2/parts?includes[]=createdByUser&includes[]=location&includes[]=files
Or, simply by providing a list of comma-separated values:
GET https://api.onupkeep.com/api/v2/parts?includes=createdByUser,location,files

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

Versioning

We will release a new, dated version of the API whenever we make any changes that are not backwards compatible. We consider the following changes to be backwards compatible:

Adding new API resources.
Adding new optional request parameters to existing API methods.
Adding new properties to existing API responses.
Changing the order of properties in existing API resources where an order is not specified (e.g. the order of properties in objects).

All other changes will result in new API versions.

All requests use the default API version specified on your account settings page, unless you override the default API version. To override the default API version and set the API version for a specific request, send an upkeep-version header with your preferred version like so:

upkeep-version: '2021-11-23'

The current version of the UpKeep API is 2022-09-14.

All versions and their changes will be listed in the changelog below.

Changelog

2022-09-14

All /preventative-maintenance endpoints have been sunset and are no longer available on this version. If you still need these endpoints for legacy recurring work orders, use a previous version of the API.
The GET /work-order-schedule/ endpoint has been sunset and no longer available.
You can now create, read, update, and delete PM Triggers using the /preventive-maintenance endpoints. Note the slight spelling difference vs the sunset endpoints.

2022-04-07

The GET and DELETE /assets/<assetID>/custom-fields/<fieldID> endpoints have been deprecated.
The PATCH /assets/<assetID>/custom-fields/<fieldID> endpoint has been sunset and is no longer available.
The customFieldsAsset property will still be included in GET /assets and GET /assets/<assetID> responses, but it will no longer be an available property for POST /assets and PATCH /assets/<assetID> requests.
You can now create, read, update, and delete UpKeep's new custom fields using the /custom-fields/assets endpoints.
You can now set UpKeep's new custom fields when creating or updating an asset.

2022-03-17

The GET /work-orders endpoint now returns all work orders, including reactive and preventive work orders. The /work-order-schedule endpoint is no longer necessary and has been deprecated.

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"
  -d jobTitle="Plant Manager"

{
  "success": true,
  "result": {
    "id": "fjQXLsOvG7",
    "accountType": "ADMIN",
    "email": "user@onupkeep.com",
    "firstName": "Marty",
    "lastName": "McFly",
    "phoneNumber": "800-123-4567",
    "jobTitle": "Plant Manager",
    "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
jobTitle	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": "Plant Manager",
      "isLocationBased": true,
      "dateOfLastLogin": "2018-05-22T03:05:27.262Z",
      "createdAt": "2017-12-06T19:23:09.162Z",
      "updatedAt": "2017-12-08T18:41:44.335Z"
    }
  ]
}

This endpoint gets all users for your account.

HTTP Request

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

Query Parameters

Parameter	Type	Default	Description
email	String	undefined	If set, the result will only include user with that email.
accountType	String	undefined	If set, the result will only include user with that account type.
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`. Second value: `ASC` or `DESC`.
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

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": "Plant Manager",
    "isLocationBased": false,
    "dateOfLastLogin": "2018-05-22T03:05:27.262Z",
    "createdAt": "2017-12-06T19:23:09.162Z",
    "updatedAt": "2017-12-08T18:41:44.335Z"
  }
}

This endpoint gets 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 get

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",
    "jobTitle": "Plant Manager",
    "isLocationBased": false,
    "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 get

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
isLocationBased	Boolean	false

Add location access for a user

curl "https://api.onupkeep.com/api/v2/users/<ID>/locations"
  -H "Session-Token: session_token_here"
  -X PUT
  -d locationIds=["xyzabc123"]

{
  "success": true,
  "results": [
    {
      "locationId": "xyzabc123"
    }
  ]
}

This endpoint updates location access for a specific user.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the user to get

Request Body

Parameter	Type	Required	Description
locationIds	Array of String	true	Required. Only parent location IDs are allowed to be passed in this parameter. Example: `{"locationIds": ["abcxyz123", "xyzabc123"...]}`

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 gets all customers for your account.

HTTP Request

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

Query Parameters

Parameter	Type	Default	Description
name	String	undefined	If set, the result will only include customers with that name.
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`. Second value: `ASC` or `DESC`.
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

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 gets 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 get

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 gets all vendors for your account.

HTTP Request

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

Query Parameters

Parameter	Type	Default	Description
businessName	String	undefined	If set, the result will only include vendors with that business name.
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`. Second value: `ASC` or `DESC`.
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

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 gets 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 get

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	false

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 gets all teams for your account.

HTTP Request

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

Query Parameters

Parameter	Type	Default	Description
name	String	undefined	If set, the result will only include teams with that name.
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`. Second value: `ASC` or `DESC`.
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

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 gets 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 get

Update a Specific Team

curl "https://api.onupkeep.com/api/v2/teams/<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 get

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 get

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 gets 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 get

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

Form Template

Get All Form Templates

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

{
  "success": true,
  "results": [
    {
      "Name": "Daily Rounds",
      "userCreated": "BRho3lxEyI",
      "description": "These tasks and checks should be performed every day at the end of each shift.",
      "createdAt": "2022-06-22T18:53:07.884Z",
      "updatedAt": "2022-12-08T13:23:42.261Z",
      "id": "XKtMGAAjDF",
      "formItems": [
        {
          "name": "Check, close, and lock windows",
          "type": "TASK"
        },
        {
          "name": "Record room temp",
          "type": "METER_READING",
          "meter": "cjFVMI6cmg"
        },
        {
          "name": "Check office occupancy",
          "type": "NUMBER"
        },
        {
          "name": "Inspected by",
          "type": "TEXT"
        },
        {
          "name": "Temperature below 90",
          "type": "CHECKLIST"
        },
        {
          "name": "Shift",
          "type": "MULTIPLE_CHOICE",
          "options": [
            "1st",
            "2nd",
            "3rd"
          ]
        }
      ]
    }
  ]
}

This endpoint gets all saved form templates (checklists) for your account.

HTTP Request

GET https://api.onupkeep.com/api/v2/form-templates/

Query Parameters

Parameter	Type	Default	Description
sort	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`. Second value: `ASC` or `DESC`.
limit	Number	undefined	Limit for pagination.
offset	Number	undefined	Offset for pagination.

Get a specific form template by ID

curl "https://api.onupkeep.com/api/v2/form-templates/<templateId>"
  -H "Session-Token: session_token_here"
  -X GET

{
  "success": true,
  "result": {
    "Name": "Daily Rounds",
    "userCreated": "BRho3lxEyI",
    "description": "These tasks and checks should be performed every day at the end of each shift.",
    "createdAt": "2022-06-22T18:53:07.884Z",
    "updatedAt": "2022-12-08T13:23:42.261Z",
    "id": "XKtMGAAjDF",
    "formItems": [
      {
        "name": "Check, close, and lock windows",
        "type": "TASK"
      },
      {
        "name": "Record room temp",
        "type": "METER_READING",
        "meter": "cjFVMI6cmg"
      },
      {
        "name": "Check office occupancy",
        "type": "NUMBER"
      },
      {
        "name": "Inspected by",
        "type": "TEXT"
      },
      {
        "name": "Temperature below 90",
        "type": "CHECKLIST"
      },
      {
        "name": "Shift",
        "type": "MULTIPLE_CHOICE",
        "options": [
          "1st",
          "2nd",
          "3rd"
        ]
      }
    ]
  }
}

This endpoint gets a specific form template (checklist) by its ID.

HTTP Request

GET https://api.onupkeep.com/api/v2/form-templates/<templateId>

URL Parameters

Parameter	Description
templateId	ID of the form template

Files

Upload/Create a File

curl "https://api.onupkeep.com/api/v2/files/"
  -H "Session-Token: session_token_here"
  -X POST
  -F 'file=@"/path/to/file.png"'
  -F 'filename="custom_file_name"'

{
  "success": true,
  "data": {
    "id": "cfUb96FKU6",
    "filename": "custom_file_name.png",
    "url": "https://api.onupkeep.s3.amazonaws.com/files/OJkfjPlMa/custom_file_name.png",
    "mimeType": "image/png",
    "createdAt": "2022-11-18T12:06:27.017Z"
  }
}

This endpoint uploads the file to our servers and creates a new file record.

HTTP Request

POST https://api.onupkeep.com/api/v2/files/

Request Body

To upload a file, you’ll need to send a request of type multipart/form-data. Include both the file itself and the filename.

Parameter	Type	Required
file	File	true
filename	String	true

Get All Files

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

{
  "success": true,
  "results": [
    {
      "id": "cfUb96FKU6",
      "filename": "custom_file_name.png",
      "url": "https://api.onupkeep.s3.amazonaws.com/files/OJkfjPlMa/custom_file_name.png",
      "mimeType": "image/png",
      "createdAt": "2022-11-18T12:06:27.017Z"
    }
  ]
}

This endpoint gets all files for your account.

HTTP Request

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

Query Parameters

Parameter	Type	Default	Description
sort	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`. Second value: `ASC` or `DESC`.
limit	Number	undefined	Limit for pagination.
offset	Number	undefined	Offset for pagination.

Get a specific file by ID

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

{
  "success": true,
  "result": {
    "id": "cfUb96FKU6",
    "filename": "custom_file_name.png",
    "url": "https://api.onupkeep.s3.amazonaws.com/files/OJkfjPlMa/custom_file_name.png",
    "mimeType": "image/png",
    "createdAt": "2022-11-18T12:06:27.017Z"
  }
}

This endpoint gets a specific file by its ID.

HTTP Request

GET https://api.onupkeep.com/api/v2/files/<fileId>

URL Parameters

Parameter	Description
fileId	ID of the file

Assets

Create an Asset

curl 'https://api.onupkeep.com/api/v2/assets'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X POST
  -d '{
        "name": "The Deluxe Power Generator",
        "serial": "S5614B09118",
        "serialNumber": "SER-100",
        "purchaseDate": "2022-06-30T00:08:00Z",
        "placedInServiceDate": "2022-07-01T00:08:00Z",
        "warrantyExpiration": "2023-07-01T00:08:00Z",
        "purchasePrice": 50000,
        "residualValue": 4500,
        "usefulLife": {
            "quantity": 5,
            "units": "years"
        },        
        "model": "Deluxe 5500",
        "customFields": [
          {
            "id": "AZuXycOMod",
            "fieldValue": {
              "singleLineTextValue": "Custom info"
            }
          }
        ],
        "manufacturerVendor": "aSeGenoGam",
        "parentAsset": "sEgDAFDMY5",
        "image": "rcOGeIogMA",
        "purchaseReceipt": "rqOxxIyyVC",
        "warrantyFile": "hIfOkWDFss",
        "files": [
          "CiOGeIogVC",
          "rqYED7B65S"
        ],
      }'

{
  "success": true,
  "result": {
    "id": "fjQXLsOvG7",
    "serial": "S5614B09118",
    "serialNumber": "SER-100",
    "additionalInformation": "2 feet by 2 feet",
    "purchaseDate": "2022-06-30T00:08:00Z",
    "placedInServiceDate": "2022-07-01T00:08:00Z",
    "warrantyExpiration": "2023-07-01T00:08:00Z",
    "purchasePrice": 50000,
    "residualValue": 4500,
    "usefulLife": {
        "quantity": 5,
        "units": "years"
    },
    "model": "Deluxe 5500",
    "name": "The Ultra Power Generator",
    "notes": "Oldest generator in use",
    "barcode": "S5614B09118",
    "location": "OPkIOYYZ0F",
    "image": {
      "name": "image_generator_001.jpg",
      "url": "https://upkeep-production.s3.amazonaws.com/image_generator_001.jpg"
    },
    "purchaseReceipt": {
      "name": "image_generator_receipt.jpg",
      "url": "https://upkeep-production.s3.amazonaws.com/image_generator_receipt.jpg"
    },
    "warrantyFile": {
      "name": "image_generator_warranty.pdf",
      "url": "https://upkeep-production.s3.amazonaws.com/image_generator_warranty.pdf"
    },
    "files": [
      "CiOGeIogVC",
      "rqYED7B65S"
    ],
    "status": "active",
    "description": "The Generator Powering Life Support for the Space Station",
    "category": "Generators",
    "manufacturerVendor": "aSeGenoGam",
    "parentAsset": "sEgDAFDMY5",
    "assignedToUsername": "abc@def.com",
    "assignedToUser": "BZuHycQMog",
    "createdByUsername": "zys@abce.com",
    "createdByUser": "DNbSREeodF",
    "customFields": [
      {
        "id": "AZuXycOMod",
        "name": "Custom text field",
        "type": "singleLineText",
        "decimalPrecision": null,
        "options": null,
        "createdByUser": "x2uAyc1Zod",
        "createdAt": "2022-03-24T22:03:07.717Z",
        "updatedAt": null,
        "fieldValue": {
          "singleLineTextValue": "Custom info",
          "multiLineTextValue": null,
          "numberValue": null,
          "dateValue": null,
          "currencyValue": null
          "dropdownValue": null
          "createdAt": "2022-03-24T22:03:07.717Z",
          "updatedAt": null
        }
      }
    ],
    "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	Description
serial	String	false	The asset's barcode number.
additionalInformation	String	false
purchaseDate	String	false	The date (GMT) of purchase.
placedInServiceDate	String	false	The start date (GMT) of service.
warrantyExpiration	String	false	The date (GMT) of warranty expiration.
purchasePrice	Number	false	The purchase price.
residualValue	Number	false	The value at the end of the depreciation lifespan.
usefulLife	Object	false	The depreciation lifespan.
model	String	false
name	String	true
notes	String	false
serialNumber	String	false	The asset's serial number.
manufacturerVendor	String	false	The ID of the vendor.
parentAsset	String	false	The ID of parent Asset.
location	String	false	The ID of the location.
image	String	false	The ID of the file (jpg, png) representing the image.
purchaseReceipt	String	false	The ID of the file (jpg, png) representing the purchase receipt.
warrantyFile	String	false	The ID of the file (jpg, png, pdf) representing the warranty.
files	Array of String	false	A list of file IDs.
area	String	false
status	String	false	Must be either `active` or `inactive`.
downtimeStatus	String	false	Supports either `available` or `not-available`. For custom downtime status, provide the ID of custom asset downtime status.
description	String	false
category	String	false	The category of the asset. Must be one of the configured categories for assets.
checkInProcedure	String	false
checkOutProcedure	String	false
availabilityStatus	String	false
availabilityTrackingOn	Boolean	false
assignedToUser	String	false	The ID of the user.
customFields	Array of objects	false	A list of custom fields of the asset.

The usefulLife object has the following properties:

Property	Type	Required	Description
quantity	Number	true	A non-negative integer
units	String	true	'days', 'weeks', 'months', or 'years'

Each custom field object has the following properties:

Property	Type	Required	Description
id	String	true	The ID of the custom field.
fieldValue	object	true	An object denoting field type and value.

The fieldValue object has the properties listed below. Each property corresponds to a specific type of custom field, thus only one property should be included for each fieldValue object.

Property	Type	Required	Description
singleLineTextValue	String	false	A value for the Single Line Text custom field type.
multiLineTextValue	String	false	A value for the Multi-Line Text custom field type.
numberValue	Number	false	A value for the Number custom field type.
dateValue	String	false	A value for the Date custom field type. Must be an ISO 8601 timestamp.
currencyValue	Number	false	A value for the Currency custom field type.
dropdownValue	String	false	A value for the Dropdown custom field type.

Get All Assets

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

{
  "success": true,
  "results": [
    {
      "id": "fjQXLsOvG7",
      "serial": "S5614B09118",
      "serialNumber": "SER-100",
      "additionalInformation": "2 feet by 2 feet",
      "purchaseDate": "2022-06-30T00:08:00Z",
      "placedInServiceDate": "2022-07-01T00:08:00Z",
      "warrantyExpiration": "2023-07-01T00:08:00Z",
      "purchasePrice": 50000,
      "residualValue": 4500,
      "usefulLife": {
          "quantity": 5,
          "units": "years"
      },
      "model": "Deluxe 5500",
      "name": "The Ultra Power Generator",
      "notes": "Oldest generator in use",
      "numberOfIncompleteWorkOrders": 55,
      "barcode": "S5614B09118",
      "location": "OPkIOYYZ0F",
      "image": {
        "name": "image_generator_001.jpg",
        "url": "https://upkeep-production.s3.amazonaws.com/image_generator_001.jpg"
      },
      "purchaseReceipt": {
        "name": "image_generator_receipt.jpg",
        "url": "https://upkeep-production.s3.amazonaws.com/image_generator_receipt.jpg"
      },
      "warrantyFile": {
        "name": "image_generator_warranty.pdf",
        "url": "https://upkeep-production.s3.amazonaws.com/image_generator_warranty.pdf"
      },
      "files": [
        "CiOGeIogVC",
        "rqYED7B65S"
      ],
      "status": "active",
      "description": "The Generator Powering Life Support for the Space Station",
      "category": "Generators",
      "assignedToUsername": "abc@def.com",
      "manufacturerVendor": "XyzAbC123n",
      "parentAsset": "0lcpd45AKe",
      "assignedToUser": "BZuHycQMog",
      "createdByUsername": "zys@abce.com",
      "createdByUser": "DNbSREeodF",
      "checkInProcedure": "Connect generator",
      "checkOutProcedure": "Disconnect Generator",
      "availabilityStatus": "available",
      "downtimeStatus": "available",
      "availabilityTrackingOn": true,
      "customFields": [
        {
          "id": "AZuXycOMod",
          "name": "Custom text field",
          "type": "singleLineText",
          "decimalPrecision": null,
          "options": null,
          "createdByUser": "x2uAyc1Zod",
          "createdAt": "2022-03-24T22:03:07.717Z",
          "updatedAt": null,
          "fieldValue": {
            "singleLineTextValue": "Custom info",
            "multiLineTextValue": null,
            "numberValue": null,
            "dateValue": null,
            "currencyValue": null,
            "dropdownValue": null,
            "createdAt": "2022-03-24T22:03:07.717Z",
            "updatedAt": null
          }
        },
        {
          "id": "0lcpd45AKe",
          "name": "Weight in KGs",
          "type": "number",
          "decimalPrecision": 2,
          "options": null,
          "subAssets": [
            "fjQXLsOvG7"
          ],
          "createdByUser": "YMv1dUhTGy",
          "createdAt": "2023-11-24T22:32:27.745Z",
          "updatedAt": "2023-11-24T22:32:27.745Z",
          "fieldValue": {
            "singleLineTextValue": null,
            "multiLineTextValue": null,
            "dropdownValue": null,
            "numberValue": 50.12,
            "currencyValue": null,
            "dateValue": null,
            "createdBy": "YMv1dUhTGy",
            "createdAt": "2023-11-28T13:39:42.407Z",
            "updatedAt": "2023-11-28T13:39:42.407Z"
          }
        }
      ],
      "updatedAt": "2017-11-16T15:01:01",
      "createdAt": "2017-11-16T15:01:01"
    }
  ]
}

This endpoint gets all assets.

HTTP Request

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

Query Parameters

Parameter	Type	Default	Description
name	String	undefined	If set, the result will only include assets with that name.
serial	String	undefined	If set, the result will only include assets with given barcode number.
serialNumber	String	undefined	If set, the result will only include assets with given serial number.
location	String	undefined	The ID of the location. If set, the result will only include assets assigned to this location.
status	String	undefined	If set, the result will only include assets with this status.
category	String	undefined	If set, the result will only include assets with this category.
assignedToUser	String	undefined	The ID of the user. If set, the result will only include assets assigned to this user.
createdByUser	String	undefined	The ID of the user. If set, the result will only include assets created by this user.
downtimeStatus	String	undefined	The ID of the asset downtime status. If set, the result will only include assets with this asset downtime status.
customFields	Array	undefined	An array of objects used to filter by custom asset fields. Each object must be in the following format: `customFields[<index>][type]=<type>&customFields[<index>][id]=<id>&customFields[<index>][value / minValue / maxValue]` Example for various field types: Type: `currency` `{{host}}/api/v2/assets/?customFields[0][type]=currency&customFields[0][id]=xYzAbc&customFields[0][minValue]=12.23&customFields[0][maxValue]=20.00` Type: `date` `{{host}}/api/v2/assets/?customFields[1][type]=date&customFields[1][id]=ISBfStMOfc&customFields[1][minValue]=2023-10-30&customFields[1][maxValue]=2023-11-03` Type: `dropdown` `{{host}}/api/v2/assets/?customFields[2][type]=dropdown&customFields[2][id]=mmZHmTLshb&customFields[2][value]=option 1`
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`. Second value: `ASC` or `DESC`.
includes	Array or String	undefined	Expandable objects are `location`, `parentAsset`, `createdByUser` , `assignedToUser`.
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

Each filter object for customFields can have the following properties:

Property	Type	Required	Description
id	String	true	The ID of the custom field.
type	String	true	The type of the custom field. The available types are: `text, number, currency, date, dropdown`
minValue	Number / Date	true (if type is `number, currency, date`)	A minimum value to search for a range of data. It should be `numeric` value for field types: `number, currency` And a `date` value if field type is: `date`.
maxValue	Number / Date	true (if type is `number, currency, date`)	A maximum value to search for a range of data. It should be `numeric` value for field types: `number, currency` And a `date` value if field type is: `date`.
value	String	true if type is `text` or `dropdown`	The substring to search for in field value (for the types: `text, dropdown`).

Get a Specific Asset

curl 'https://api.onupkeep.com/api/v2/assets/<ID>'
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "result": {
    "id": "fjQXLsOvG7",
    "serial": "S5614B09118",
    "serialNumber": "SER-100",
    "additionalInformation": "2 feet by 2 feet",
    "purchaseDate": "2022-06-30T00:08:00Z",
    "placedInServiceDate": "2022-07-01T00:08:00Z",
    "warrantyExpiration": "2023-07-01T00:08:00Z",
    "purchasePrice": 50000,
    "residualValue": 4500,
    "usefulLife": {
        "quantity": 5,
        "units": "years"
    },
    "model": "Deluxe 5500",
    "name": "The Ultra Power Generator",
    "notes": "Oldest generator in use",
    "numberOfIncompleteWorkOrders": 55,
    "barcode": "S5614B09118",
    "location": "OPkIOYYZ0F",
    "image": {
      "name": "image_generator_001.jpg",
      "url": "https://upkeep-production.s3.amazonaws.com/image_generator_001.jpg"
    },
    "purchaseReceipt": {
        "name": "image_generator_receipt.jpg",
        "url": "https://upkeep-production.s3.amazonaws.com/image_generator_receipt.jpg"
    },
    "warrantyFile": {
        "name": "image_generator_warranty.pdf",
        "url": "https://upkeep-production.s3.amazonaws.com/image_generator_warranty.pdf"
    },
    "status": "active",
    "description": "The Generator Powering Life Support for the Space Station",
    "category": "Generators",
    "assignedToUsername": "abc@def.com",
    "manufacturerVendor": "xY1zabCmNo",
    "parentAsset": "0lcpd45AKe",
    "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"
    ],
    "customFields": [
      {
        "id": "AZuXycOMod",
        "name": "Custom text field",
        "type": "singleLineText",
        "decimalPrecision": null,
        "options": null,
        "createdByUser": "x2uAyc1Zod",
        "createdAt": "2022-03-24T22:03:07.717Z",
        "updatedAt": null,
        "fieldValue": {
          "singleLineTextValue": "Custom info",
          "multiLineTextValue": null,
          "numberValue": null,
          "dateValue": null,
          "currencyValue": null
          "dropdownValue": null
          "createdAt": "2022-03-24T22:03:07.717Z",
          "updatedAt": null
        }
      }
    ],
    "updatedAt": "2017-11-16T15:01:01",
    "createdAt": "2017-11-16T15:01:01"
  }
}

This endpoint gets 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 get.

Query Parameters

Parameter	Type	Default	Description
includes	Array or String	undefined	Expandable objects are `assignedUsers`, `assignedTeams`, `assignedCustomers`, `assignedVendors`, `formItems`, `files`, `parts`, `subAssets`, `location`, `parentAsset`, `createdByUser` , `assignedToUser`.

Update a Specific Asset

curl 'https://api.onupkeep.com/api/v2/assets/<ID>'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X PATCH
  -d '{
        "name": "The Amazing Power Generator",
        "purchaseDate": "2022-06-21T00:08:00Z",
        "residualValue": 3500,
        "usefulLife": {
           "quantity": 60,
           "units": "months"
        },
        "customFields": [
          {
            "id": "AZuXycOMod",
            "fieldValue": {
              "singleLineTextValue": "Custom info"
            }
          }
        ],
        "manufacturerVendor": "aSeGenoGam",
        "parentAsset": "sEgDAFDMY5",
        "image": "rcOGeIogMA",
        "files": [
          "CiOGeIogVC",
          "rqYED7B65S"
        ],
      }'

{
  "success": true,
  "result": {
    "id": "fjQXLsOvG7",
    "serial": "S5614B09118",
    "serialNumber": "SER-100",
    "additionalInformation": "2 feet by 2 feet",
    "purchaseDate": "2022-06-21T00:08:00Z",
    "placedInServiceDate": "2022-07-01T00:08:00Z",
    "warrantyExpiration": "2023-07-01T00:08:00Z",
    "purchasePrice": 50000,
    "residualValue": 3500,
    "usefulLife": {
        "quantity": 60,
        "units": "months"
    },    
    "model": "Deluxe 5500",
    "name": "The Amazing Power Generator",
    "notes": "Oldest generator in use",
    "numberOfIncompleteWorkOrders": 55,
    "barcode": "S5614B09118",
    "location": "OPkIOYYZ0F",
    "image": {
      "name": "image_generator_001.jpg",
      "url": "https://upkeep-production.s3.amazonaws.com/image_generator_001.jpg"
    },
    "purchaseReceipt": {
      "name": "image_generator_receipt.jpg",
      "url": "https://upkeep-production.s3.amazonaws.com/image_generator_receipt.jpg"
    },
    "warrantyFile": {
      "name": "image_generator_warranty.pdf",
      "url": "https://upkeep-production.s3.amazonaws.com/image_generator_warranty.pdf"
    },
    "status": "active",
    "description": "The Generator Powering Life Support for the Space Station",
    "category": "Generators",
    "manufacturerVendor": "aSeGenoGam",
    "parentAsset": "sEgDAFDMY5",
    "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": [
      "CiOGeIogVC",
      "rqYED7B65S"
    ],
    "formItems": [
      "Ia536KS4RZ"
    ],
    "customFields": [
      {
        "id": "AZuXycOMod",
        "name": "Custom text field",
        "type": "singleLineText",
        "options": null,
        "decimalPrecision": null,
        "createdByUser": "x2uAyc1Zod",
        "createdAt": "2022-03-24T22:03:07.717Z",
        "updatedAt": null,
        "fieldValue": {
          "singleLineTextValue": "Custom info",
          "multiLineTextValue": null,
          "numberValue": null,
          "dateValue": null,
          "currencyValue": null
          "dropdownValue": null
          "createdAt": "2022-03-24T22:03:07.717Z",
          "updatedAt": null
        }
      }
    ],
    "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	Required	Description
serial	String	false	The asset's barcode number.
additionalInformation	String	false
purchaseDate	String	false	The date (GMT) of purchase.
placedInServiceDate	String	false	The start date (GMT) of service.
warrantyExpiration	String	false	The date (GMT) of warranty expiration.
purchasePrice	Number	false	The purchase price.
residualValue	Number	false	The value at the end of the depreciation lifespan.
usefulLife	Object	false	The depreciation lifespan.
model	String	false
name	String	true
notes	String	false
serialNumber	String	false	The asset's serial number.
manufacturerVendor	String	false	The ID of the vendor.
parentAsset	String	false	The ID of parent Asset.
location	String	false	The ID of the location.
image	String	false	The ID of the file (jpg, png) representing the image.
purchaseReceipt	String	false	The ID of the file (jpg, png) representing the purchase receipt.
warrantyFile	String	false	The ID of the file (jpg, png, pdf) representing the warranty.
files	Array of String	false	A list of file IDs.
area	String	false
status	String	false	Must be either `active` or `inactive`.
downtimeStatus	String	false	Supports either `available` or `not-available`. For custom downtime status, provide the ID of custom asset downtime status.
description	String	false
category	String	false	The category of the asset. Must be one of the configured categories for assets.
checkInProcedure	String	false
checkOutProcedure	String	false
availabilityStatus	String	false
availabilityTrackingOn	Boolean	false
assignedToUser	String	false	The ID of the user.
customFields	Array of objects	false	A list of custom fields of the asset.

The usefulLife object has the following properties:

Property	Type	Required	Description
quantity	Number	true	A non-negative integer
units	String	true	'days', 'weeks', 'months', or 'years'

Each custom field object has the following properties:

Property	Type	Required	Description
id	String	true	The ID of the custom field.
fieldValue	object	true	An object denoting field type and value.

The fieldValue object has the properties listed below. Each property corresponds to a specific type of custom field, thus only one property should be included for each fieldValue object.

Property	Type	Required	Description
singleLineTextValue	String	false	A value for the Single Line Text custom field type.
multiLineTextValue	String	false	A value for the Multi-Line Text custom field type.
numberValue	Number	false	A value for the Number custom field type.
dateValue	String	false	A value for the Date custom field type. Must be an ISO 8601 timestamp.
currencyValue	Number	false	A value for the Currency custom field type.
dropdownValue	String	false	A value for the Dropdown custom field type.

Delete a Specific Asset

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

{
  "success": true,
  "message": "1 asset deleted"
}

This endpoint deletes a specific asset.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the asset to delete.

Record Downtime Events

curl 'https://api.onupkeep.com/api/v2/assets/downtime'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X POST
  -d '[
    {
      "assetId": "TFtPTiUQQ3",
      "status": "available",
      "recordedOn": "not a date"
    },
    {
      "assetId": "SQENCkGVrr",
      "status": "available",
      "recordedOn": "2023-10-25T23:25:59.999Z"
    }
  ]'

{
  "success": false,
  "results": [
    {
      "assetId": "TFtPTiUQQ3",
      "status": "available",
      "recordedOn": "not a date",
      "row": 1,
      "errors": [
        {
          "message": "Invalid recordedOn date",
          "slug": "invalid-recorded-on",
          "value": "not a date"
        }
      ]
    },
    {
      "assetId": "SQENCkGVrr",
      "status": "available",
      "recordedOn": "2023-10-25T23:25:59.999Z",
      "row": 3,
      "statusMessage": "Insert new asset activity update",
      "statusSlug": "insert-asset-activity-update",
      "newAssetActivityUpdateId": "Dn0Uv1Be4W"
    }
  ]
}

This endpoint records downtime events by enabling bulk updates of assets' downtime status. It returns success: true when all status updates are recorded successfully. If any status updates fails, the endpoint returns success: false with errors for the failed status updates in the response.

HTTP Request

POST https://api.onupkeep.com/api/v2/assets/downtime

Request Body

Provide array of objects with at least one object required. The available fields for each object are as follows:

Parameter	Type	Required	Description
assetId	String	true	The asset's ID
status	String	true	`available` or `not-available`.
recordedOn	String	true	The timestamp of the status change. Must be an ISO 8601 timestamp, or Unix time in miliseconds.
statusCategory	String	false	The ID of a custom downtime status category.
userId	String	false	The ID of a user associated with the downtime status change.

Get a Custom Field for a Specific Asset (DEPRECATED)

curl 'https://api.onupkeep.com/api/v2/assets/<assetID>/custom-fields/<fieldID>'
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "result": {
    "id": "AI5uBGp7nz",
    "name": "width",
    "value": "10",
    "unit": "cm",
    "asset": "fjQXLsOvG7",
    "user": "lv6FZopMhz",
    "createdAt": "2018-03-20T06:54:48.325Z",
    "updatedAt": "2018-03-20T06:54:48.325Z"
  }
}

This endpoint gets a custom field for a specific asset.

HTTP Request

GET https://api.onupkeep.com/api/v2/assets/<assetID>/custom-fields/<fieldID>

URL Parameters

Parameter	Description
assetID	The ID of the asset.
fieldID	The ID of the custom field.

Update a Custom Field for a Specific Asset (SUNSET)

curl 'https://api.onupkeep.com/api/v2/assets/<assetID>/custom-fields/<fieldID>'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X PATCH
  -d '{
        "value": "15",
      }'

{
  "success": true,
  "result": {
    "id": "AI5uBGp7nz",
    "name": "width",
    "value": "15",
    "unit": "cm",
    "asset": "fjQXLsOvG7",
    "user": "lv6FZopMhz",
    "createdAt": "2018-03-20T06:54:48.325Z",
    "updatedAt": "2018-03-20T06:54:48.325Z"
  }
}

This endpoint updates a custom field for a specific asset.

HTTP Request

PATCH https://api.onupkeep.com/api/v2/assets/<assetID>/custom-fields/<fieldID>

URL Parameters

Parameter	Description
assetID	The ID of the asset.
fieldID	The ID of the custom field.

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	Default	Description
name	String	undefined	The name of the custom field.
value	String	undefined	The value of the custom field.
unit	String	undefined	The unit of measurement.

Delete a Custom Field for a Specific Asset (DEPRECATED)

curl 'https://api.onupkeep.com/api/v2/assets/<assetID>/custom-fields/<fieldID>'
  -X DELETE
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "message": "1 custom field deleted"
}

This endpoint deletes a custom field for a specific asset.

HTTP Request

DELETE https://api.onupkeep.com/api/v2/assets/<assetID>/custom-fields/<fieldID>

URL Parameters

Parameter	Description
assetID	The ID of the asset.
fieldID	The ID of the custom field.

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 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 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 asset.
teamID	The ID of the team to be assigned to the 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 asset.
teamID	The ID of the team to be removed from the 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 asset.
customerID	The ID of the customer to be assigned to the 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 asset.
customerID	The ID of the customer to be removed from the 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 asset.
vendorID	The ID of the vendor to be assigned to the 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 asset.
vendorID	The ID of the vendor to be removed from the asset.

Assign Part to an Asset

curl 'https://api.onupkeep.com/api/v2/assets/<assetID>/parts/<partID>'
  -H 'Session-Token: session_token_here'
  -X POST

{
  "success": true,
  "message": "part <partID> assigned to asset <assetID>"
}

This endpoint assigns part to a specific asset.

HTTP Request

POST https://api.onupkeep.com/api/v2/assets/<assetID>/parts/<partID>

URL Parameters

Parameter	Description
assetID	The ID of the asset.
partID	The ID of the part to be assigned to the asset.

Remove Assigned Part from an Asset

curl 'https://api.onupkeep.com/api/v2/assets/<assetID>/parts/<partID>'
  -H 'Session-Token: session_token_here'
  -X DELETE

{
  "success": true,
  "message": "part <partID> removed from asset <assetID>"
}

This endpoint removes assigned part from a specific asset.

HTTP Request

DELETE https://api.onupkeep.com/api/v2/assets/<assetID>/parts/<partID>

URL Parameters

Parameter	Description
assetID	The ID of the asset.
partID	The ID of the part to be removed from the asset.

Asset Downtime Statuses

Create an Asset Downtime Status

curl 'https://api.onupkeep.com/api/v2/asset-downtime-statuses'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X POST
  -d '{
        "name": "Under Maintenance" 
      }'

{
  "success": true,
  "result": {
    "id": "dHK4JGfhp8",
    "name": "underMaintenance",
    "createdAt": "2020-01-21T03:49:06.012Z",
    "updatedAt": "2020-01-21T03:49:06.012Z"
  }
}

This endpoint creates a new asset downtime status.

HTTP Request

POST https://api.onupkeep.com/api/v2/asset-downtime-statuses

Request Body

Provide any of the below required fields and optional fields for the asset downtime status.

Parameter	Type	Required	Description
name	String	true	The name of the asset downtime status.

Get All Asset Downtime Statuses

curl 'https://api.onupkeep.com/api/v2/asset-downtime-statuses'
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "results": [
    {
      "id": "dHK4JGfhp8",
      "name": "Under Maintenance",
      "createdAt": "2020-01-21T03:49:06.012Z",
      "updatedAt": "2020-01-21T03:49:06.012Z"
    }
  ]
}

This endpoint gets all asset downtime statuses.

HTTP Request

GET https://api.onupkeep.com/api/v2/asset-downtime-statuses

Query Parameters

Parameter	Type	Default	Description
name	String	undefined	If set, the result will only include asset downtime statuses with that name.
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`. Second value: `ASC` or `DESC`.
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

Get a Specific Asset Downtime Status

curl 'https://api.onupkeep.com/api/v2/asset-downtime-statuses/<ID>'
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "result": {
    "id": "dHK4JGfhp8",
    "name": "Under Maintenance",
    "createdAt": "2020-01-21T03:49:06.012Z",
    "updatedAt": "2020-01-21T03:49:06.012Z"
  }
}

This endpoint gets a specific asset downtime status.

HTTP Request

GET https://api.onupkeep.com/api/v2/asset-downtime-statuses/<ID>

URL Parameters

Parameter	Description
ID	The ID of the asset downtime status to get.

Update a Specific Asset Downtime Status

curl 'https://api.onupkeep.com/api/v2/asset-downtime-statuses/<ID>'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X PATCH
  -d '{
        "name": "Under Process"
      }'

{
  "success": true,
  "result": {
    "id": "dHK4JGfhp8",
    "name": "Under Process",
    "createdAt": "2020-01-21T03:49:06.012Z",
    "updatedAt": "2020-01-21T03:57:49.374Z"
  }
}

This endpoint updates a specific asset downtime status.

HTTP Request

PATCH https://api.onupkeep.com/api/v2/asset-downtime-statuses/<ID>

URL Parameters

Parameter	Description
ID	The ID of the asset downtime to update.

Request Body

Parameter	Type	Default	Description
name	String	undefined	The name of the asset downtime status.

Delete a Specific Asset Downtime Status

curl 'https://api.onupkeep.com/api/v2/asset-downtime-statuses/<ID>'
  -X DELETE
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "message": "1 downtime status deleted"
}

This endpoint deletes a specific asset downtime status.

HTTP Request

DELETE https://api.onupkeep.com/api/v2/asset-downtime-statuses/<ID>

URL Parameters

Parameter	Description
ID	The ID of the asset downtime status to delete.

Asset Custom Fields

Create a custom field

curl 'https://api.onupkeep.com/api/v2/custom-fields/assets'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X POST
  -d '{
        "name": "Custom number field",
        "type": "number",
        "decimalPrecision": 0
      }'

{
  "success": true,
  "result": {
    "id": "eqvBjzLWXW"
    "name": "Custom number field"
    "type": "number"
    "options": null,
    "decimalPrecision": 0,
    "createdAt": "2022-04-04T23:51:58.098Z"
    "updatedAt": null,
    "createdByUser": "gmWbjzIKxW"
  }
}

This endpoint creates a new custom field for assets.

HTTP Request

POST https://api.onupkeep.com/api/v2/custom-fields/assets

Request Body

Provide any of the below required and optional properties for the custom field.

Parameter	Type	Required	Description
name	String	true	The name of the custom field.
type	String	true	One of `singleLineText`, `multiLineText`, `dropdown`, `date`, `number`, or `currency`.
options	Array of Strings	Required if `type` is `dropdown`.	A list of possible options for a dropdown.
decimalPrecision	Number	Required if `type` is `number` or `currency`.	A number from 0 to 5 representing the number of digits after the decimal point (e.g. a `decimalPrecision` of 0 would correspond to 52 while a `decimalPrecision` of 2 would correspond to 52.24).

Get all custom fields

curl 'https://api.onupkeep.com/api/v2/custom-fields/assets'
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "results": [
    {
      "id": "eqvBjzLWXW"
      "name": "Custom number field"
      "type": "number"
      "options": null,
      "decimalPrecision": 0,
      "createdAt": "2022-04-04T23:51:58.098Z"
      "updatedAt": null,
      "createdByUser": "gmWbjzIKxW"
    },
    {
      "id": "arvVjzgWUp"
      "name": "Custom dropdown field"
      "type": "dropdown"
      "options": [
        "First",
        "Second",
        "Third"
      ],
      "decimalPrecision": null,
      "createdAt": "2022-04-05T23:51:58.098Z"
      "updatedAt": null,
      "createdByUser": "gmWbjzIKxW"
    }
  ]
}

This endpoint gets all custom fields for assets.

HTTP Request

GET https://api.onupkeep.com/api/v2/custom-fields/assets

Get a specific custom field

curl 'https://api.onupkeep.com/api/v2/custom-fields/assets/eqvBjzLWXW'
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "result": {
      "id": "eqvBjzLWXW"
      "name": "Custom number field"
      "type": "number"
      "options": null,
      "decimalPrecision": 0,
      "createdAt": "2022-04-04T23:51:58.098Z"
      "updatedAt": null,
      "createdByUser": "gmWbjzIKxW"
  }
}

This endpoint gets a specific custom field for assets.

HTTP Request

GET https://api.onupkeep.com/api/v2/custom-fields/assets/<ID>

URL Parameters

Parameter	Description
ID	The ID of the custom field.

Update a specific custom field

curl 'https://api.onupkeep.com/api/v2/custom-fields/assets/eqvBjzLWXW'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X POST
  -d '{
        "name": "A different field name"
      }'

{
  "success": true,
  "result": {
    "id": "eqvBjzLWXW"
    "name": "A different field name"
    "type": "number"
    "options": null,
    "decimalPrecision": 0,
    "createdAt": "2022-04-04T23:51:58.098Z"
    "updatedAt": null,
    "createdByUser": "gmWbjzIKxW"
  }
}

This endpoint updates a specific custom field for assets.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the custom field.

Request Body

Provide any of the below optional properties for the custom field.

Parameter	Type	Required	Description
name	String	true	The name of the custom field.
options	Array of Strings	Required if `type` is `dropdown`.	A list of possible options for a dropdown.

Delete a specific custom field

curl 'https://api.onupkeep.com/api/v2/custom-fields/assets/eqvBjzLWXW'
  -H 'Session-Token: session_token_here'
  -X DELETE

{
  "success": true,
  "result": {
    "id": "eqvBjzLWXW"
    "name": "A different field name"
    "type": "number"
    "options": null,
    "decimalPrecision": 0,
    "createdAt": "2022-04-04T23:51:58.098Z"
    "updatedAt": null,
    "createdByUser": "gmWbjzIKxW"
  }
}

This endpoint deletes a specific custom field for assets.

HTTP Request

DELETE https://api.onupkeep.com/api/v2/custom-fields/assets/<ID>

URL Parameters

Parameter	Description
ID	The ID of the custom field.

Locations

Create a Location

curl 'https://api.onupkeep.com/api/v2/locations'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X POST
  -d '{
        "name": "Sherlock Holmes’ House",
        "address": "221B Baker Street, London NW1 6XE, UK",
        "longitude": 51.523767,
        "latitude": -0.1585557,
        "hideMap": "0",
        "parentLocation": "qwrKjyUWDW",
        "customFieldsLocation": [
          {
            "name": "Country",
            "value": "UK"
          }
        ]
      }'

{
  "success": true,
  "result": {
    "id": "jpSMgHPr11",
    "createdByUser": "lv6FZopMhz",
    "createdByUsername": "test@onupkeep.com",
    "name": "Sherlock Holmes’ House",
    "address": "221B Baker Street, London NW1 6XE, UK",
    "longitude": 51.523767,
    "latitude": -0.1585557,
    "hideMap": "0",
    "parentLocation": "qwrKjyUWDW",
    "customFieldsLocation": [
      {
        "id": "y2RwPe4kMS",
        "name": "Country",
        "value": "UK",
        "location": "jpSMgHPr11",
        "user": "qwrKjyUWDW",
        "createdAt": "2020-09-19T04:57:22.912Z",
        "updatedAt": "2020-09-19T04:57:22.912Z"
      }
    ],
    "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 location.

Parameter	Type	Required	Description
name	String	true	The name of the location.
address	String	false	The address of the location.
longitude	Float	false	Map coordinates.
latitude	Float	false	Map coordinates.
hideMap	String	false	Enables map view. Boolean as a string: "0" or "1".
parentLocation	String	false	The ID of the parent location.
customFieldsLocation	Array of objects	false	A list of custom fields of the location. Its child attributes are `name`, `value`, and `unit`.

Note

Custom fields can be added using this endpoint.

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": "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 gets all locations.

HTTP Request

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

Query Parameters

Parameter	Type	Default	Description
name	String	undefined	If set, the result will only include locations with that name.
createdByUser	String	undefined	If set, the result will only include locations created by this user.
parentLocation	String	undefined	If set, the result will only include sub locations of this parent location.
customFieldsLocation	Object	undefined	If set, the result will only include locations with matching custom field name, value, and unit. Example `https...?customFieldsLocations[name]=Country&customFieldsLocations[value]=UK`
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`. Second value: `ASC` or `DESC`.
includes	Array or String	undefined	Expandable objects are `createdByUser` and `parentLocation`.
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

Get a Specific Location

curl 'https://api.onupkeep.com/api/v2/locations/<ID>'
  -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"
    ],
    "createdAt": "2017-10-23T23:51:58.098Z",
    "updatedAt": "2017-10-27T20:36:24.563Z"
  }
}

This endpoint gets 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 get.

Query Parameters

Parameter	Type	Default	Description
includes	Array or String	undefined	Expandable objects are `createdByUser`, `assignedUsers`, `assignedTeams`, `assignedCustomers`, `assignedVendors`, `files`, `parentLocation`, and `subLocations`.

Update a Specific Location

curl 'https://api.onupkeep.com/api/v2/locations/<ID>'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X PATCH
  -d '{
        "name": "Conference Room",
        "customFieldsLocation": [
          {
            "name": "Floor",
            "value": "1st"
          }
        ]
      }'

{
  "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",
      "customFieldsLocation": [
        {
          "id": "AvmCM4NHrI",
          "name": "Floor",
          "value": "1st",
          "location": "jpSMgHPr11",
          "user": "lv6FZopMhz",
          "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 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	Default	Description
name	String	true	The name of the location.
address	String	false	The address of the location.
longitude	Float	false	Map coordinates.
latitude	Float	false	Map coordinates.
hideMap	String	false	Enables map view. Boolean as a string: "0" or "1".
parentLocation	String	false	The ID of the parent location.
customFieldsLocation	Array of objects	false	A list of custom fields of the location. Its child attributes are `name`, `value`, and `unit`.

Note

Custom fields can be added using this endpoint. Null value for customFieldsLocation will not delete custom fields. Use the Custom Fields for Locations endpoints to update and delete custom fields.

Delete a Specific Location

curl 'https://api.onupkeep.com/api/v2/locations/<ID>'
  -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.

Get a Custom Field for a Specific Location

curl 'https://api.onupkeep.com/api/v2/locations/<locationID>/custom-fields/<fieldID>'
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "result": {
    "id": "AvmCM4NHrI",
    "name": "Floor",
    "value": "1st",
    "location": "jpSMgHPr11",
    "user": "lv6FZopMhz",
    "createdAt": "2018-05-17T07:38:33.619Z",
    "updatedAt": "2018-05-17T07:38:33.619Z"
  }
}

This endpoint gets a custom field for a specific location.

HTTP Request

GET https://api.onupkeep.com/api/v2/locations/<locationID>/custom-fields/<fieldID>

URL Parameters

Parameter	Description
locationID	The ID of the location.
fieldID	The ID of the custom field.

Update a Custom Field for a Specific Location

curl 'https://api.onupkeep.com/api/v2/locations/<locationID>/custom-fields/<fieldID>'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X PATCH
  -d '{
        "value": "2nd",
      }'

{
  "success": true,
  "result": {
    "id": "AvmCM4NHrI",
    "name": "Floor",
    "value": "2nd",
    "location": "jpSMgHPr11",
    "user": "lv6FZopMhz",
    "createdAt": "2018-05-17T07:38:33.619Z",
    "updatedAt": "2018-05-17T07:38:33.619Z"
  }
}

This endpoint updates a custom field for a specific location.

HTTP Request

PATCH https://api.onupkeep.com/api/v2/locations/<locationID>/custom-fields/<fieldID>

URL Parameters

Parameter	Description
locationID	The ID of the location.
fieldID	The ID of the custom field.

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	Default	Description
name	String	undefined	The name of the custom field.
value	String	undefined	The value of the custom field.
unit	String	undefined	The unit of measurement.

Delete a Custom Field for a Specific Location

curl 'https://api.onupkeep.com/api/v2/locations/<locationID>/custom-fields/<fieldID>'
  -X DELETE
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "message": "1 custom field deleted"
}

This endpoint deletes a custom field for a specific location.

HTTP Request

DELETE https://api.onupkeep.com/api/v2/locations/<locationID>/custom-fields/<fieldID>

URL Parameters

Parameter	Description
locationID	The ID of the location.
fieldID	The ID of the custom field.

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 location.
userID	The ID of the user to be assigned to the 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 location.
userID	The ID of the user to be removed from the 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 location.
teamID	The ID of the team to be assigned to the 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 location.
teamID	The ID of the team to be removed from the 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 location.
customerID	The ID of the customer to be assigned to the 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 location.
customerID	The ID of the customer to be removed from the 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 location.
vendorID	The ID of the vendor to be assigned to the 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 location.
vendorID	The ID of the vendor to be removed from the location.

Parts

Create a Part

curl 'https://api.onupkeep.com/api/v2/parts'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X POST
  -d '{
        "name": "Flux Capacitor",
        "description": "This is what makes time travel possible.",
        "cost": 88.00,
        "quantity": 15,
        "minimumQuantity": 1,
        "partId": "654a1b433dc9596ef9af2a1f",
        "partName": "PT-1",
        "serial": "40161502",
        "category": "Compressor",
        "location": "jmHFWGVgd1",
        "customFieldsPart": [
          {
            "name": "inventor",
            "value": "Dr. Emmett Brown",
          }
        ]
      }'

{
  "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",
    "partId": "654a1b433dc9596ef9af2a1f",
    "partName": "PT-1",
    "createdByUser": "pCmWGVgfW",
    "customFieldsPart": [
      {
        "id": "7EcGy2GRS1",
        "name": "inventor",
        "value": "Dr. Emmett Brown",
        "partInventory": "1YHUWGVgdC",
        "user": "pCmWGVgfW",
        "createdAt": "2017-10-23T23:51:58.097Z",
        "updatedAt": "2017-10-23T23:51:58.097Z"
      }
    ],
    "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	The name of the part.
description	String	false	A description of the part.
cost	Float	false	Cost per unit for the part.
quantity	Number	false	The quantity on hand.
minimumQuantity	Number	false	UpKeep will notify you if the part quantity on hand drops below this number value.
serial	String	false	Synonymous with barcode.
area	String	false	Specific area within an assigned location.
details	String	false	Any additional details about the part.
category	String	false	The category of the part. Must be one of the configured categories for parts.
location	String	false	The ID of the location.
partId	String	false	ID of the parent part.
partNumber	String	false	Number of the parent part
customFieldsPart	Array of objects	false	A list of custom fields of the part. Its child attributes are `name`, `value`, and `unit`.

Note

Custom fields can be added using this endpoint.

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",
      "partId": "654a1b433dc9596ef9af2a1f",
      "partName": "PT-1",
      "serial": "40161502",
      "area": "Center console",
      "details": "Needs 1.21 gigawatts to power the Flux Capacitor.","category": "Filter",
      "location": "jmHFWGVgd1",
      "createdByUser": "pCmWGVgfW",
      "createdAt": "2017-10-23T23:51:58.097Z",
      "updatedAt": "2017-10-23T23:51:58.097Z"
    }
  ]
}

This endpoint gets all parts.

HTTP Request

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

Query Parameters

Parameter	Type	Default	Description
name	String	undefined	If set, the result will only include parts with that name.
category	String	undefined	If set, the result will only include parts with that category.
location	String	undefined	The ID of the location. If set, the result will only include parts assigned to this location.
partId	String	undefined	ID of the parent part.
partNumber	String	undefined	Number of the parent part
createdByUser	String	undefined	The ID of the user. If set, the result will only include parts created by this user.
customFieldsPart	Object	undefined	If set, the result will only include parts with matching custom field name, value, and unit. Example `https...?customFieldsPart[name]=inventor&customFieldsPart[value]=Dr. Emmett Brown&category=Compressor`
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`. Second value: `ASC` or `DESC`.
includes	Array or String	undefined	Expandable objects are `location`, `createdByUser`.
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

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",
    "partId": "654a1b433dc9596ef9af2a1f",
    "partName": "PT-1",
    "serial": "40161502",
    "area": "Center console",
    "details": "Needs 1.21 gigawatts to power the Flux Capacitor.","category": "Filter",
    "location": "jmHFWGVgd1",
    "createdByUser": "pCmWGVgfW",
    "files": [
      "MUfUCa0JBo",
      "FGyvo6raqZ"
    ],
    "customFieldsPart": [
      {
        "id": "7EcGy2GRS1",
        "name": "inventor",
        "value": "Dr. Emmett Brown",
        "partInventory": "1YHUWGVgdC",
        "user": "pCmWGVgfW",
        "createdAt": "2017-10-23T23:51:58.097Z",
        "updatedAt": "2017-10-23T23:51:58.097Z"
      }
    ],
    "createdAt": "2017-10-23T23:51:58.097Z",
    "updatedAt": "2017-10-23T23:51:58.097Z"
  }
}

This endpoint gets 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 get.

Query Parameters

Parameter	Type	Default	Description
includes	Array or String	undefined	Expandable objects are `location`, `createdByUser`, `files`.

Update a Specific Part

curl 'https://api.onupkeep.com/api/v2/parts/<ID>'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X PATCH
  -d '{
        "quantity": 100,
        "customFieldsPart": [
          {
            "name": "Manufacturer By",
            "value": "ABC Parts Inc",
          }
        ]
      }'

{
  "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": "Center console",
    "partId": "654a1b433dc9596ef9af2a1f",
    "partName": "PT-1",
    "details": "Needs 1.21 gigawatts to power the Flux Capacitor.",
    "category": "Filter",
    "location": "jmHFWGVgd1",
    "createdByUser": "pCmWGVgfW",
    "customFieldsPart": [
      {
        "id": "axdcV3NKaB",
        "name": "manufacturer",
        "value": "ABC Parts Inc",
        "partInventory": "1YHUWGVgdC",
        "user": "pCmWGVgfW",
        "createdAt": "2018-05-18T09:37:21.593Z",
        "updatedAt": "2018-05-18T09:37:21.593Z"
      },
      {
        "id": "7EcGy2GRS1",
        "name": "inventor",
        "value": "Dr. Emmett Brown",
        "partInventory": "1YHUWGVgdC",
        "user": "pCmWGVgfW",
        "createdAt": "2017-10-23T23:51:58.097Z",
        "updatedAt": "2017-10-23T23:51:58.097Z"
      }
    ],
    "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	Default	Description
name	String	true	The name of the part.
description	String	false	A description of the part.
cost	Float	false	Cost per unit for the part.
quantity	Number	false	The quantity on hand.
minimumQuantity	Number	false	UpKeep will notify you if the part quantity on hand drops below this number value.
partId	String	false	ID of the parent part.
partNumber	String	false	Number of the parent part
serial	String	false	Synonymous with barcode.
area	String	false	Specific area within an assigned location.
details	String	false	Any additional details about the part.
category	String	false	The category of the part. Must be one of the configured categories for parts.
location	String	false	The ID of the location.
customFieldsPart	Array of objects	false	A list of custom fields of the part. Its child attributes are `name`, `value`, and `unit`.

Note

Custom fields can be added using this endpoint. Null value for customFieldsPart will not delete custom fields. Use the Custom Fields for Parts endpoints to update and delete custom fields.

Delete a Specific Part

curl 'https://api.onupkeep.com/api/v2/parts/<ID>'
  -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.

Get a Custom Field for a Specific Part

curl 'https://api.onupkeep.com/api/v2/parts/<partID>/custom-fields/<fieldID>'
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "result": {
    "id": "axdcV3NKaB",
    "name": "manufacturer",
    "value": "ABC Parts Inc",
    "partInventory": "1YHUWGVgdC",
    "user": "pCmWGVgfW",
    "createdAt": "2018-05-18T09:37:21.593Z",
    "updatedAt": "2018-05-18T09:37:21.593Z"
  }
}

This endpoint gets a custom field for a specific part.

HTTP Request

GET https://api.onupkeep.com/api/v2/parts/<ID>/custom-fields/<fieldID>

URL Parameters

Parameter	Description
partID	The ID of the part.
fieldID	The ID of the custom field.

Update a Custom Field for a Specific Part

curl 'https://api.onupkeep.com/api/v2/parts/<partID>/custom-fields/<fieldID>'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X PATCH
  -d '{
        "value": "123 Parts Inc",
      }'

{
  "success": true,
  "result": {
    "id": "axdcV3NKaB",
    "name": "manufacturer",
    "value": "123 Parts Inc",
    "partInventory": "1YHUWGVgdC",
    "user": "pCmWGVgfW",
    "createdAt": "2018-05-18T09:37:21.593Z",
    "updatedAt": "2018-05-18T09:37:21.593Z"
  }
}

This endpoint updates a custom field for a specific part.

HTTP Request

PATCH https://api.onupkeep.com/api/v2/parts/<ID>/custom-fields/<fieldID>

URL Parameters

Parameter	Description
partID	The ID of the part.
fieldID	The ID of the custom field.

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	Default	Description
name	String	undefined	The name of the custom field.
value	String	undefined	The value of the custom field.
unit	String	undefined	The unit of measurement.

Delete a Custom Field for a Specific Part

curl 'https://api.onupkeep.com/api/v2/parts/<partID>/custom-fields/<fieldID>'
  -X DELETE
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "message": "1 custom field deleted"
}

This endpoint deletes a custom field for a specific part.

HTTP Request

DELETE https://api.onupkeep.com/api/v2/parts/<ID>/custom-fields/<fieldID>

URL Parameters

Parameter	Description
partID	The ID of the part.
fieldID	The ID of the custom field.

Assign Team to a Part

curl 'https://api.onupkeep.com/api/v2/parts/<partID>/teams/<teamID>'
  -H 'Session-Token: session_token_here'
  -X POST

{
  "success": true,
  "message": "team <teamID> assigned to part <partID>."
}

This endpoint assigns a team to a specific part.

HTTP Request

POST https://api.onupkeep.com/api/v2/parts/<partID>/teams/<teamID>

URL Parameters

Parameter	Description
partID	The ID of the part.
teamID	The ID of the team to be assigned to the part.

Remove Assigned Team from a Part

curl 'https://api.onupkeep.com/api/v2/parts/<partID>/teams/<teamID>'
  -H 'Session-Token: session_token_here'
  -X DELETE

{
  "success": true,
  "message": "team <teamID> removed from part <partID>"
}

This endpoint removes assigned team from a specific part.

HTTP Request

DELETE https://api.onupkeep.com/api/v2/parts/<partID>/teams/<teamID>

URL Parameters

Parameter	Description
partID	The ID of the part.
teamID	The ID of the team to be removed from the asset.

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 priority=1
  -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",
    "priority": 1,
    "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
priority	Number	false	0,1,2,3. 0 being lowest
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 gets all requests for your account.

HTTP Request

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

Query Parameters

Parameter	Type	Default	Description
title	String	undefined	If set, the result will only include requests with this title.
location	String	undefined	The ID of the location. If set, the result will only include requests assigned to this location.
asset	String	undefined	The ID of the asset. If set, the result will only include requests assigned to this asset.
team	String	undefined	The ID of the team. If set, the result will only include requests assigned to this team.
assignedToUser	String	undefined	The ID of the user. If set, the result will only include requests assigned to this user.
category	String	undefined	If set, the result will only include requests with this category.
requestedByUser	String	undefined	The ID of the user who created the request. If set, the result will show only requests requested by this user.
publicRequesterEmail	String	undefined	The email of the requester (request via request portal/via email). If set, the result will show only requests requested by this user. Request will have either requestedByUser or publicRequesterEmail set.
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`, `dueDate`, `endDueDate`. Second value: `ASC` or `DESC`.
includes	Array or String	undefined	Expandable objects are `asset`, `location`, `team`, `assignedToUser`, `assignedByUser`, `cancelledByUser`.
dueDateGreaterThan dueDateLessThan dueDateGreaterThanOrEqualTo dueDateLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?dueDateGreaterThanOrEqualTo=1598983706000&dueDateLessThanOrEqualTo=1599761306000`
endDueDateGreaterThan endDueDateLessThan endDueDateGreaterThanOrEqualTo endDueDateLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?endDueDateGreaterThanOrEqualTo=1598983706000&endDueDateLessThanOrEqualTo=1599761306000`
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

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 gets 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 get

Query Parameters

Parameter	Type	Default	Description
includes	Array or String	undefined	Expandable objects are `asset`, `location`, `team`, `assignedToUser`, `assignedByUser`, `cancelledByUser`, `files`, `formItems`, `parts`, `arrayOfUpdateItems`.

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
  --data-raw '{
    "title": "Repair sink",
    "description": "Sink broke yesterday",
    "priority": 1,
    "dueDate": 1515482422310,
    "asset": "gDK45aHe12",
    "location": "MD565aHenL",
    "image": "vcNGeIogMA",
    "image2": "rcOGeIogMA",
    "image3": "NOmGeIogBp",
    "image4": "qbOGeAIoCg",
    "image5": "NtAGeIogMA",
    "signatureImage": "cBOEgoIgMA",
    "files": [
      "CiOGeIogVC",
      "rqYED7B65S"
    ],
    "formTemplate": "XWqiqJlSc1",
    "formItems": [
      {
        "name": "Check & close all tanks",
        "type": "TASK"
      },
    ],
    "assignedToUser": "lv6FZopMhz",
    "estimatedDurationInHours": 5,
    "category" "Damage",
    "parts": [
      "j6BFY05V8P",
      "a67Fz05VaB"
    ],
    respectivePartQuantityUsed: [
      1,
      3
    ],
    additionalUsers: [
      "wk3BNzQW3X",
      "vs9BHaQVCd"
    ],
    "time": 20,
    "cost": 25,
    "customWOStatusId": "651c18ebf37a21595c159a9c"
  }'

{
  "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",
    "image": {
        "__type": "File",
        "name": "dfimg_request2.jpg",
        "url": "https://demo-api-upkeep.s3.amazonaws.com/dfimg_request2.jpg"
    },
    "image2": {...},
    "image3": {...},
    "image4": {...},
    "image5": {...},
    "signatureImage": {
        "__type": "File",
        "name": "sig_mv2.png",
        "url": "https://demo-api-upkeep.s3.amazonaws.com/sig_mv2.png"
    },
    "files": [
      "CiOGeIogVC",
      "rqYED7B65S"
    ],
    "requiresSignature": 1,
    "formItems": [
      {
        "id": "TuAExCvmwS",
        "name": "Check & close all tanks",
        "type": "TASK",
        "value": "OPEN"
      },
      {...},
      {...}
    ],
    "assignedByUser": "lv6FZopMhz",
    "assignedByUsername": "test@onupkeep.com",
    "estimatedDurationInHours" : 5,
    "priority": 1,
    "parts": [
          "j6BFY05V8P",
          "a67Fz05VaB"
        ],
    "respectivePartQuantityUsed": [
      1,
      3
    ],
    "additionalUsers": [
      "wk3BNzQW3X",
      "vs9BHaQVCd"
    ],
    "time": "20",
    "cost": "25",
    "customWOStatus": {
      "id": "651c18ebf37a21595c159a9c",
      "name": "Open - Pending Approval",
      "type": "open",
      "createdBy": "lv6FZopMhz",
      "deletedBy": null
    },
    "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 work order.

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
image	String	false	The ID of the file
image2	String	false	The ID of the file
image3	String	false	The ID of the file
image4	String	false	The ID of the file
image5	String	false	The ID of the file
signatureImage	String	false	The ID of the file
files	Array of String	false	A list of file IDs
formTemplate	String	false	ID of a form template (checklist)
formItems	Array of objects	false	A list of form items (tasks). Should include `name` and `type` keys. `type` should be one of `TASK`, `TEXT`, `NUMBER`, `CHECKLIST`, `MULTIPLE_CHOICE`, or `METER`. The `METER` type includes a `meter` key with the ID of the meter and the `MULTIPLE_CHOICE` type includes an `options` key with an array of available options. All types can optionally include a `value` key. Certain types have predefined `values`. `TASK`: `OPEN`, `ON_HOLD`, `IN_PROGRESS` `COMPLETE`. `CHECKLIST`: `PASS`, `FLAG`, `FAIL`. `MULTIPLE_CHOICE`: A value from the options list.
assignedToUser	String	false	id of user whom the Work Order is assigned
estimatedDurationInHours	Number	false
parts	Array of Strings	false	An array of Part IDs to include with the work order.
respectivePartQuantityUsed	Array of Numbers	false	The respective quantities of each part included in the parts array.
decreaseInventory	String	false	Can be "auto" or "manual". Default is "auto". If set to "auto", inventory will be automatically be decreased when a part is added to a work order. If set to "manual", inventory will NOT be decreased when a part is added to a work order.
time	Number	false	The total time spent on the work order.
cost	Number	false	The additional cost assigned to the work order.
additionalUsers	Array of Strings	false	An array of user IDs for additional workers assigned to the work order.
customWOStatusId	String	false	The unique identifier of the linked Custom Work Order Status.

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",
      "responseTime": 12,
      "time": "20",
      "cost": "25",
      "timeLog": [
        {
          "duration": 20,
          "category": {
            "name": "Vendor Time",
            "id": "eGPRxExf9m"
          },
          "assignedToUser": "5ZXaLRZ40I",
          "timers": [
            {
              "duration": 20,
              "status": "adjustment",
              "hourlyCost": 20,
              "createdByUser": "FFbCm9T26b",
              "createdAt": "2017-12-02T16:45:06.132Z"
            }
          ]
        }
      ],
      "category": "Electrical",
      "archivedStatus": "1",
      "formItems": [
        "YChe6OjzHC",
        "FuJBoOf8Di",
        "e2iFG6t7I9"
      ],
      "assignedByUser": "5ZXaLRZ40I",
      "assignedByUsername": "test@onupkeep.com",
      "priority": "1",
      "category": "Electrical",
      "parts": [
        "sDmjnbbpAL",
        "QhWwJbfGb4"
      ],
      "respectivePartQuantityUsed": [
        5,
        1
      ],
      "additionalUsers": [
        "vk6BHzQVCX",
        "lv6FZopMhz"
      ],
      "image": {
          "__type": "File",
          "name": "dfimg_request2.jpg",
          "url": "https://demo-api-upkeep.s3.amazonaws.com/dfimg_request2.jpg"
      },
      "image2": {...},
      "image3": {...},
      "image4": {...},
      "image5": {...},
      "signatureImage": {
          "__type": "File",
          "name": "sig_mv2.png",
          "url": "https://demo-api-upkeep.s3.amazonaws.com/sig_mv2.png"
      },
      "files": [
        "CiOGeIogVC",
        "rqYED7B65S"
      ],
      "requiresSignature": 1,
      "formItems": [
        {
          "id": "TuAExCvmwS",
          "name": "Check & close all tanks",
          "type": "TASK",
          "value": "OPEN"
        },
        {...},
        {...}
      ],
      "publicRequesterEmail": "test@onupkeep.com",
      "customWOStatus": {
        "id": "651c18ebf37a21595c159a9c",
        "name": "Open - Pending Approval",
        "type": "open",
        "createdBy": "lv6FZopMhz",
        "deletedBy": null
      },
      "createdAt": "2017-12-06T19:23:09.162Z",
      "updatedAt": "2017-12-08T18:41:44.335Z"
    }
  ]
}

HTTP Request

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

Query Parameters

Parameter	Type	Default	Description
title	String	undefined	If set, the result will only include requests with this title.
isComplete	String	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	String	undefined	If set, the result will only include this status. Allowed values `open`, `onHold`, `inProgress`, `complete`.
archivedStatus	String	undefined	If set to "1", the result will only include work orders that have been archived.
priority	String	undefined	If set, the result will only include work orders with this priority.
location	String	undefined	The ID of the location. If set, the result will only include work orders assigned to this location.
asset	String	undefined	The ID of the asset. If set, the result will only include requests work orders to this asset.
assignedToUser	String	undefined	The ID of the user. If set, the result will only include work orders assigned to this user.
assignedByUser	String	undefined	The ID of the user. If set, the result will only include work orders assigned by this user.
category	String	undefined	If set, the result will only include work orders with this category.
publicRequesterEmail	String	undefined	If set, the result will only include work orders created by this email on the public request portal.
customWOStatusId	String	undefined	If set, the result will only include work orders linked with the supplied `customWOStatusId`.
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`, `dueDate`, `endDueDate`, `dateCompleted`. Second value: `ASC` or `DESC`.
includes	Array or String	undefined	Expandable objects are `asset`, `location`, `assignedToUser`, `assignedByUser`, `requestedByUser`, `completedByUser`, `team`.
dueDateGreaterThan dueDateLessThan dueDateGreaterThanOrEqualTo dueDateLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?dueDateGreaterThanOrEqualTo=1598983706000&dueDateLessThanOrEqualTo=1599761306000`
endDueDateGreaterThan endDueDateLessThan endDueDateGreaterThanOrEqualTo endDueDateLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?endDueDateGreaterThanOrEqualTo=1598983706000&endDueDateLessThanOrEqualTo=1599761306000`
dateCompletedGreaterThan dateCompletedLessThan dateCompletedGreaterThanOrEqualTo dateCompletedLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?dateCompletedGreaterThanOrEqualTo=1598983706000&dateCompletedLessThanOrEqualTo=1599761306000`
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

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",
      "cost": "25",
      "additionalCosts": [
        {
            "amount": 5,
            "info": "Test cost 2",
            "category": "Other",
            "assignedToUser": "YMv1dUhTGy",
            "date": "2023-10-11T13:49:11.538Z",
            "includedInTotalCost": false
        },
        {
            "amount": 15,
            "info": "Test Description",
            "category": "Other",
            "assignedToUser": "sExVhCWGpA",
            "date": "2023-10-11T13:47:50.967Z",
            "includedInTotalCost": true
        },
        {
            "amount": 10,
            "info": "Test Additional Cost 1",
            "category": "Labor Cost",
            "assignedToUser": "sExVhCWGpA",
            "date": "2023-10-11T13:48:21.573Z",
            "includedInTotalCost": true
        }
      ],
      "responseTime": 12,
      "time": "20",
      "timeLog": [
        {
          "duration": 20,
          "category": {
            "name": "Vendor Time",
            "id": "eGPRxExf9m"
          },
          "assignedToUser": "5ZXaLRZ40I",
          "timers": [
            {
              "duration": 20,
              "status": "adjustment",
              "hourlyCost": 20,
              "createdByUser": "FFbCm9T26b",
              "createdAt": "2017-12-02T16:45:06.132Z"
            }
          ]
        }
      ],
      "location": "Mkr457Gkk3",
      "team": "PD6I909nLS",
      "category": "Electrical",
      "assignedByUser": "5ZXaLRZ40I",
      "assignedByUsername": "test@onupkeep.com",
      "priority": "1",
      "image": {
          "__type": "File",
          "name": "dfimg_request2.jpg",
          "url": "https://demo-api-upkeep.s3.amazonaws.com/dfimg_request2.jpg"
      },
      "image2": {...},
      "image3": {...},
      "image4": {...},
      "image5": {...},
      "signatureImage": {
          "__type": "File",
          "name": "sig_mv2.png",
          "url": "https://demo-api-upkeep.s3.amazonaws.com/sig_mv2.png"
      },
      "files": [
        "CiOGeIogVC",
        "rqYED7B65S"
      ],
      "requiresSignature": 1,
      "formItems": [
        {
          "id": "TuAExCvmwS",
          "name": "Check & close all tanks",
          "type": "TASK",
          "value": "OPEN"
        },
        {...},
        {...}
      ],
      "category": "Electrical",
      "formItems": [
        "YChe6OjzHC",
        "FuJBoOf8Di",
        "e2iFG6t7I9"
      ],
      "arrayOfUpdateItems": [
        "dGCW3cSjWv",
        "SPRXIDJDZ1"
      ],
      "parts": [
        "sDmjnbbpAL",
        "QhWwJbfGb4"
      ],
      "respectivePartQuantityUsed": [
        5,
        1
      ],
      "additionalUsers": [
        "vk6BHzQVCX",
        "lv6FZopMhz"
      ],
      "publicRequesterEmail": "test@onupkeep.com",
      "arrayOfLinkedWorkOrders": [
        {
          "linkType": "Relates to",
          "linkTo": [
            "GlqCpO2pn5", ... 
          ],
          "createdAt": "2017-12-08T19:39:46.189Z",
          "createdBy": "lv6FZopMhz"
        },
        {...},
        {...}
      ],
      "customWOStatus": {
        "id": "651c18ebf37a21595c159a9c",
        "name": "Open - Pending Approval",
        "type": "open",
        "createdBy": "lv6FZopMhz",
        "deletedBy": null
      },
      "createdAt": "2017-12-06T19:23:09.162Z",
      "updatedAt": "2017-12-08T18:41:44.335Z"
    }
}

This endpoint gets a specific work order.

The responseTime in response object is the time difference in hours between WorkOrder creation and its first status update.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the work order to get

Query Parameters

Parameter	Type	Default	Description
includes	Array or String	undefined	Expandable objects are `asset`, `location`, `assignedToUser`, `assignedByUser`, `completedByUser`, `team`, `formItems`, `parts`, `arrayOfUpdateItems`, `additionalUsers`, `files` , `formItems`.

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",
        category="Electrical",
        "image": "vcNGeIogMA",
        "image2": "rcOGeIogMA",
        "image3": "NOmGeIogBp",
        "image4": "qbOGeAIoCg",
        "image5": "NtAGeIogMA",
        "signatureImage": "cBOEgoIgMA",
        "files": [
          "CiOGeIogVC",
          "rqYED7B65S"
        ],
        "formTemplate": "XWqiqJlSc1",
        "formItems": [
          {
            "id": "9kJdmSvzmo",
            "name": "Shift",
            "type": "MULTIPLE_CHOICE",
            "options": [
              "1st",
              "2nd",
              "3rd"
            ],
            "value": "1st"
          },
          {
            "id": "9kJdmSvzmo",
            "name": "Record room temp",
            "type": "METER_READING",
            "meter": "hGZ8e2CGRy",
            "value": 90
          },
          {
            "id": "9kJdmSvzmo",
            "name": "Check sign in sheet; how many people were in the office today?",
            "type": "NUMBER",
            "value": 37
          },
          {
            "id": "9kJdmSvzmo",
            "name": "Who, if anyone, recorded a temp above 99 degrees?",
            "type": "TEXT",
            "value": "Alex"
          },
          {
            "id": "9kJdmSvzmo",
            "name": "Forehead thermometer is working",
            "type": "CHECKLIST",
            "value": "PASS"
          },
          {
            "name": "Check & close all tanks",
            "type": "TASK"
          },
        ],
        "customWOStatusId": "651c190af37a21595c159a9e"
      }'

{
  "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",
      "archivedStatus": "1",
      "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": {...},
      "signatureImage": {
          "__type": "File",
          "name": "sig_mv2.png",
          "url": "https://demo-api-upkeep.s3.amazonaws.com/sig_mv2.png"
      },
      "files": [
        "CiOGeIogVC",
        "rqYED7B65S"
      ],
      "requiresSignature": 1,
      "formItems": [
        {
          "id": "TuAExCvmwS",
          "name": "Check & close all tanks",
          "type": "TASK",
          "value": "OPEN"
        },
        {...},
        {...}
      ],
      "publicRequesterEmail": "test@onupkeep.com",
      "customWOStatus": {
        "id": "651c190af37a21595c159a9e",
        "name": "On Hold - Awaiting Prerequisites",
        "type": "onHold",
        "createdBy": "lv6FZopMhz",
        "deletedBy": null
      },
      "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	0,1,2,3. 0 being lowest
asset	String	id of asset
location	String	id of location
image	String	The ID of the file
image2	String	The ID of the file
image3	String	The ID of the file
image4	String	The ID of the file
image5	String	The ID of the file
signatureImage	String	The ID of the file
files	Array of String	A list of file IDs
formTemplate	String	ID of a form template (checklist)
formItems	Array of objects	A list of form items (tasks). Should include `name` and `type` keys. `type` should be one of `TASK`, `TEXT`, `NUMBER`, `CHECKLIST`, `MULTIPLE_CHOICE`, or `METER`. The `METER` type includes a `meter` key with the ID of the meter and the `MULTIPLE_CHOICE` type includes an `options` key with an array of available options. All types can optionally include a `value` key. Certain types have predefined `values`. `TASK`: `OPEN`, `ON_HOLD`, `IN_PROGRESS` `COMPLETE`. `CHECKLIST`: `PASS`, `FLAG`, `FAIL`. `MULTIPLE_CHOICE`: A value from the options list.
assignedToUser	String	id of user whom the Work Order is assigned
estimatedDurationInHours	Number
parts	Array of Strings	An array of Part IDs to include with the work order.
respectivePartQuantityUsed	Array of Numbers	The respective quantities of each part included in the parts array.
decreaseInventory	String	Can be "auto" or "manual". Default is "auto". If set to "auto", inventory will be automatically be decreased when a part is added to a work order. If set to "manual", inventory will NOT be decreased when a part is added to a work order.
archivedStatus	String	Allowed values - 0 (Unarchive), 1 (Archive)
time	Number	The total time spent on the work order.
cost	Number	The additional cost assigned to the work order.
additionalUsers	Array of Strings	An array of user IDs for additional workers assigned to the work order.
customWOStatusId	String	The unique identifier of the linked Custom Work Order Status.
additionalCosts	Array of Objects	The additional, itemized costs for the work order. See below for the properties. Objects without the `id` property will create additional costs, objects with the `id` property will modify those specific additional costs. To delete a specific cost item, include the cost `id` and set `deleteAdditionalCostItem` to `true`. Passing an empty array for `additionalCosts` will remove all existing additional costs for that work order.

Additional cost object

Parameter	Type	Required	Description
id	String	false	ID of the additional cost object. Only required to update or delete a specific cost item.
amount	Number	true	Cost amount.
info	String	true	This is a custom information attribute for a cost item.
category	String	true	This has to be the name of category like `Tax`, `Labor Cost` etc.
assignedToUser	String	true	Unique ID of the user to which the cost is assigned.
date	String	false	ISO string / unix timestamp. Optional. Defaults to the current timestamp.
includedInTotalCost	Boolean	false	Optional. Defaults to `false`
deleteAdditionalCostItem	Boolean	false	Set this field to `true` to delete a cost item.

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

Assign Additional Workers to a Work Order

curl 'https://api.onupkeep.com/api/v2/work-orders/<ID>/users/<userID>'
  -H 'Session-Token: session_token_here'
  -X POST

{
  "success": true,
  "message": "User <userID> assigned to work order <ID>"
}

This endpoint assigns additional workers to a specific work order.

HTTP Request

POST https://api.onupkeep.com/api/v2/work-orders/<ID>/users/<userID>

URL Parameters

Parameter	Description
ID	The ID of the work order.
userID	The ID of the user to be assigned to the work order.

Remove Additional Workers from a Work Order

curl 'https://api.onupkeep.com/api/v2/work-orders/<ID>/users/<userID>'
  -H 'Session-Token: session_token_here'
  -X DELETE

{
  "success": true,
  "message": "User <userID> removed from work order <ID>"
}

This endpoint removes additional workers from a specific work order.

HTTP Request

DELETE https://api.onupkeep.com/api/v2/work-orders/<ID>/users/<userID>

URL Parameters

Parameter	Description
ID	The ID of the work order.
userID	The ID of the user to be removed from the work order.

Assign Team to a Work Order

curl 'https://api.onupkeep.com/api/v2/work-orders/<ID>/teams/<teamID>'
  -H 'Session-Token: session_token_here'
  -X POST

{
  "success": true,
  "message": "team <teamID> assigned to work order <ID>"
}

This endpoint assigns team to a specific work order.

HTTP Request

POST https://api.onupkeep.com/api/v2/work-orders/<ID>/teams/<teamID>

URL Parameters

Parameter	Description
ID	The ID of the work order.
teamID	The ID of the team to be assigned to the work order.

Remove Assigned Team from a Work Order

curl 'https://api.onupkeep.com/api/v2/work-orders/<ID>/teams/<teamID>'
  -H 'Session-Token: session_token_here'
  -X DELETE

{
  "success": true,
  "message": "team <teamID> removed from work order <ID>"
}

This endpoint removes assigned team from a specific work order.

HTTP Request

DELETE https://api.onupkeep.com/api/v2/work-orders/<ID>/teams/<teamID>

URL Parameters

Parameter	Description
ID	The ID of the work order.
teamID	The ID of the team to be removed from the work order.

WorkOrder Cost Category

Get All WorkOrder Cost Categories

curl "https://api.onupkeep.com/api/v2/work-order-cost-categories"
  -H "Session-Token: session_token_here"

{
  "success": true,
  "results": [
    {
      "name": "Labor Cost",
      "objectId": "4uiIbWC8yp"
    },
    {
      "name": "Parts Cost",
      "objectId": "8IsPfkDPN1"
    },
    {
      "name": "Travel Cost",
      "objectId": "hmZqjbNvQs"
    },
    {
      "name": "Tax",
      "objectId": "FsysYkpYqn"
    },
    {
      "name": "Other",
      "objectId": "8eMYzFA0iK"
    }
  ]
}

Preventive Maintenance Triggers (PM Triggers)

Create a Preventive Maintenance Trigger

curl "https://api.onupkeep.com/api/v2/preventive-maintenance/"
  -H "Session-Token: session_token_here"
  -X POST
  --data-raw '{
      "trigger": {
        "name": "Title for PMTrigger",
        "scheduleType": "EVERY_N_MONTHS_ON_NTH_WEEKDAY",
        "rrdtstart": "2023-01-17T12:12:44",
        "rrinterval": 1,
        "rrtzid": "Asia/Kolkata",
        "rrfreq": "MONTHLY",
        "cadenceFreq": "MONTHLY",
        "cadenceType": "manual",
        "cadenceInterval": 1,
        "rrbyweekday": [ "MO" ],
        "rrbysetpos": [ 1 ]
      },
      "workOrder": {
        "title": "Title for workOrder"
      }
    }'

{
  "success": true,
  "result": {
    "trigger": {
      "id": "HG7ujJ8QKm",
      "name": "Title for PMTrigger",
      "createFirstWO": 1,
      "scheduleType": "EVERY_N_MONTHS_ON_NTH_WEEKDAY",
      "isNextOccurrenceBasedOnCompletion": null,
      "rrfreq": "MONTHLY",
      "rrdtstart": "2023-01-17T12:12:44.000Z",
      "rruntil": null,
      "rrinterval": 1,
      "rrtzid": "Asia/Kolkata",
      "cadenceInterval": 1,
      "cadenceFreq": "MONTHLY",
      "cadenceType": "manual",
      "nextTriggerDate": "2023-02-06T12:12:44.000Z",
      "rdates": null,
      "exdates": null,
      "scheduleHasEnded": false,
      "createdBy": "BRho3lxEyI",
      "createdAt": "2023-01-04T16:02:33.580Z",
      "updatedAt": "2023-01-04T16:02:34.897Z",
      "isPaused": null,
      "isArchived": null,
      "archivedAt": null,
      "archivedBy": null
    },
    "workOrder": {
      "title": "Title for workOrder",
      "priority": null,
      "category": null,
      "assignedToUser": null,
      "additionalUsers": null,
      "parts": null,
      "respectivePartQuantityUsed": null,
      "duration": null,
      "lastDueDate": "2023-02-06T12:12:44.000Z",
      "nextDueDate": "2023-03-06T12:12:44.000Z"
    }
  }
}

This endpoint creates a new Preventive Maintenance Trigger.

HTTP Request

POST https://api.onupkeep.com/api/v2/preventive-maintenance/

Request Body

Provide any of the below required fields and optional fields for the PM Triggers.

Parameter	Type	Required	Description
trigger	Object	true	Contains all trigger related data
workOrder	Object	true	Contains all workOrder specific data

Below are the properties that can be passed with trigger object.

Parameter	Type	Required	Description
name	String	true	Name of the trigger
createFirstWO	Boolean	false	Whether to create first WorkOrder instantly with trigger creation. Default value is "false".
scheduleType	String	true	Represents the frequency of repetition. Allowed values: "EVERY_N_DAYS", "EVERY_N_WEEKS", "EVERY_N_WEEKS_BY_DAY_OF_THE_WEEK", "EVERY_N_MONTHS", "EVERY_N_MONTHS_ON_NTH_WEEKDAY", "EVERY_N_MONTHS_ON_NTH_DAY_FROM_BEGINNING_OR_END", "EVERY_N_YEARS"
rrfreq	String	true	One value can be passed. Allowed values are `DAILY, WEEKLY, MONTHLY, YEARLY`
rrdtstart	String	true	Datetime field for starting the first WorkOrder creation. Eg; “2021-03-24T04:26:55.000Z”
rruntil	String	false	End date for trigger. Eg: "2023-01-09T14:27:06"
rrinterval	Integer	true	To set dueDate for workOrders. Eg: "2" for 2 weeks if "rrfreq" is "WEEKLY"
rrbyweekday	String	false	For repetition of workOrders on weekly basis. Allowed day codes- SU, MO, TU, WE, TH, FR, SA. eg ["SU", "TH"]. Eg: if "rrfreq" is "WEEKLY" and "rrbyweekday" is ["SU", "TH"]; then two workOrders will be created every week for Sunday & Thursday respectively.
rrbymonthday	String	false	For repetition of workOrders on montly basis when "rrfreq" is selected as "MONTHLY". Allowed day codes- 1, 2, ... 31. Eg: [1, 15]
rrbysetpos	Array of Integer	false	Example input for position of day eg: [1, 3, 5]
rrtzid	String	true	Timezone eg: "Asia/Kolkata"
isNextOccurrenceBasedOnCompletion	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.
cadenceType	String	false	Creation cadence for workOrders, when all next set of workOrders to be created until next interval. Allowed values: "EVERY_N_DAYS", "EVERY_N_WEEKS", "EVERY_N_WEEKS_BY_DAY_OF_THE_WEEK", "EVERY_N_MONTHS", "EVERY_N_MONTHS_ON_NTH_WEEKDAY", "EVERY_N_MONTHS_ON_NTH_DAY_FROM_BEGINNING_OR_END", "EVERY_N_YEARS"
cadenceInterval	Integer	false	Interval for trigger cadence according to cadenceType.
cadenceFreq	String	false	One value can be passed. Allowed values are `DAILY, WEEKLY, MONTHLY, YEARLY`
meter	String	false
meterCondition	String	false
meterConditionValue	String	false
meterDueInterval	Integer	false
meterDueFrequency	String	false

Below are the properties that can be passed with workOrder object.

Parameter	Type	Required	Description
title	String	true
priority	Integer	false	Priority in integer format. eg: 2
asset	String	false	ID of asset
location	String	false	ID of location
category	String	false	Name of category eg: "Electrical"
assignedToUser	String	false	ID of user whom the work order is assigned
additionalUsers	Array of String	false	Array of IDs of users eg: ["X8Gn34mUSY", "iO4FPJPBDA"]
parts	Array of String	false	Array of IDs of parts
respectivePartQuantityUsed	Array of Integer	false	Array of part quantity used in same order as of Array of parts.
duration	Integer	false	Duration of work order in hours

Get All Preventive Maintenance Triggers

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

{
  "success": true,
  "results": [
    {
      "trigger": {
        "id": "Z8rUVpxVcq",
        "name": "Title for PMTrigger",
        "createFirstWO": 1,
        "scheduleType": "EVERY_N_MONTHS_ON_NTH_WEEKDAY",
        "isNextOccurrenceBasedOnCompletion": null,
        "rrfreq": "MONTHLY",
        "rrdtstart": "2023-01-17T12:12:44.000Z",
        "rruntil": null,
        "rrinterval": 1,
        "rrtzid": "Asia/Kolkata",
        "cadenceInterval": 1,
        "cadenceFreq": "MONTHLY",
        "cadenceType": "manual",
        "nextTriggerDate": "2023-02-06T12:12:44.000Z",
        "rdates": null,
        "exdates": null,
        "scheduleHasEnded": false,
        "createdBy": "BRho3lxEyI",
        "createdAt": "2023-01-05T15:57:31.051Z",
        "updatedAt": "2023-01-05T15:57:32.465Z",
        "isPaused": null,
        "isArchived": null,
        "archivedAt": null,
        "archivedBy": null
      },
      "workOrder": {
        "title": "Work Order Title",
        "priority": 1,
        "category": "Electrical",
        "assignedToUser": null,
        "additionalUsers": null,
        "parts": null,
        "respectivePartQuantityUsed": null,
        "duration": 2,
        "lastDueDate": "2023-02-06T12:12:44.000Z",
        "nextDueDate": "2023-03-06T12:12:44.000Z"
      }
    }
  ]
}

This endpoint gets all PM Triggers for your account. A PM Trigger is responsible for creating recurring work orders based on the recurring frequency details passed for trigger. This end point only fetches list of all PM Trigger and not Work Orders.

HTTP Request

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

Query Parameters

Parameter	Type	Default	Description
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`. Second value: `ASC` or `DESC`.

Get a Specific Preventive Maintenance Trigger

curl "https://api.onupkeep.com/api/v2/preventive-maintenance/<ID>"
  -H "Session-Token: session_token_here"

{
  "success": true,
  "result": {
    "trigger": {
        "id": "Z8rUVpxVcq",
        "name": "Title for PMTrigger",
        "createFirstWO": 1,
        "scheduleType": "EVERY_N_MONTHS_ON_NTH_WEEKDAY",
        "isNextOccurrenceBasedOnCompletion": null,
        "rrfreq": "MONTHLY",
        "rrdtstart": "2023-01-17T12:12:44.000Z",
        "rruntil": null,
        "rrinterval": 1,
        "rrtzid": "Asia/Kolkata",
        "cadenceInterval": 1,
        "cadenceFreq": "MONTHLY",
        "cadenceType": "manual",
        "nextTriggerDate": "2023-02-06T12:12:44.000Z",
        "rdates": null,
        "exdates": null,
        "scheduleHasEnded": false,
        "createdBy": "BRho3lxEyI",
        "createdAt": "2023-01-05T15:57:31.051Z",
        "updatedAt": "2023-01-05T15:57:32.465Z",
        "isPaused": null,
        "isArchived": null,
        "archivedAt": null,
        "archivedBy": null
      },
      "workOrder": {
        "title": "Work Order Title",
        "priority": 1,
        "category": "Electrical",
        "assignedToUser": null,
        "additionalUsers": null,
        "parts": null,
        "respectivePartQuantityUsed": null,
        "duration": 2,
        "lastDueDate": "2023-02-06T12:12:44.000Z",
        "nextDueDate": "2023-03-06T12:12:44.000Z"
      }
  }
}

This endpoint gets a specific PM-Trigger.

HTTP Request

GET https://api.onupkeep.com/api/v2/preventive-maintenance/<ID>

URL Parameters

Parameter	Description
ID	The ID of the PM-Trigger to get

Update a Preventive Maintenance Trigger

curl "https://api.onupkeep.com/api/v2/preventive-maintenance/<ID>"
  -H "Session-Token: session_token_here"
  -X PATCH
  --data-raw '{
      "trigger": {
        "rrinterval": 1,
        "scheduleType": "EVERY_N_MONTHS_ON_NTH_WEEKDAY",
        "rrfreq": "MONTHLY",
        "rrtzid": "Asia/Kolkata",
        "rrbyweekday": [ "MO" ],
        "rrbysetpos": [ 3 ]
      },
      "workOrder": {
        "priority": 1,
        "duration": 12,
        "category": "Inspection"
      }
    }'

{
  "success": true,
  "result": {
    "trigger": {
      "id": "Z8rUVpxVcq",
      "name": "Title for PMTrigger",
      "createFirstWO": 1,
      "scheduleType": "EVERY_N_MONTHS_ON_NTH_WEEKDAY",
      "isNextOccurrenceBasedOnCompletion": null,
      "rrfreq": "MONTHLY",
      "rrdtstart": "2023-01-05T23:07:01.000Z",
      "rruntil": null,
      "rrinterval": 1,
      "rrtzid": "Asia/Kolkata",
      "cadenceInterval": 1,
      "cadenceFreq": "MONTHLY",
      "cadenceType": "manual",
      "nextTriggerDate": "2023-01-05T18:18:36.373Z",
      "rdates": null,
      "exdates": null,
      "scheduleHasEnded": false,
      "createdBy": "BRho3lxEyI",
      "createdAt": "2023-01-05T15:57:31.051Z",
      "updatedAt": "2023-01-05T17:48:36.385Z",
      "isPaused": null,
      "isArchived": null,
      "archivedAt": null,
      "archivedBy": null
    },
    "workOrder": {
      "title": "Work Order Title",
      "priority": 1,
      "category": "Inspection",
      "assignedToUser": null,
      "additionalUsers": null,
      "parts": null,
      "respectivePartQuantityUsed": null,
      "duration": 12,
      "lastDueDate": null,
      "nextDueDate": "2023-01-15T23:07:01.000Z"
    }
  }
}

This endpoint updates a PM Trigger.

HTTP Request

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

Request Body

Provide any of the below required fields and optional fields for the PM Triggers.

Parameter	Type	Required	Description
trigger	Object	false	Contains all trigger related data
workOrder	Object	false	Contains all workOrder specific data

Below are the properties that can be passed with trigger object.

Parameter	Type	Required	Description
name	String	false	Name of the trigger
createFirstWO	Boolean	false	Whether to create first WorkOrder instantly with trigger creation. Default value is "false".
scheduleType	String	false	Represents the frequency of repetition. Allowed values: "EVERY_N_DAYS", "EVERY_N_WEEKS", "EVERY_N_WEEKS_BY_DAY_OF_THE_WEEK", "EVERY_N_MONTHS", "EVERY_N_MONTHS_ON_NTH_WEEKDAY", "EVERY_N_MONTHS_ON_NTH_DAY_FROM_BEGINNING_OR_END", "EVERY_N_YEARS"
rrfreq	String	false	One value can be passed. Allowed values are `DAILY, WEEKLY, MONTHLY, YEARLY`
rrdtstart	String	false	Datetime field for starting the first WorkOrder creation. Eg; “2021-03-24T04:26:55.000Z”
rruntil	String	false	End date for trigger. Eg: "2023-01-09T14:27:06"
rrinterval	Integer	false	To set dueDate for workOrders. Eg: "2" for 2 weeks if "rrfreq" is "WEEKLY"
rrbyweekday	Array of String	false	For repetition of workOrders on weekly basis. Allowed day codes- SU, MO, TU, WE, TH, FR, SA. eg ["SU", "TH"]. Eg: if "rrfreq" is "WEEKLY" and "rrbyweekday" is ["SU", "TH"]; then two workOrders will be created every week for Sunday & Thursday respectively.
rrbymonthday	Array of Integer	false	For repetition of workOrders on montly basis when "rrfreq" is selected as "MONTHLY". Allowed day codes- 1, 2, ... 31. Eg: [1, 15]
rrbysetpos	Array of Integer	false	Example input for position of day eg: [1, 3, 5, -1, -2 ...]
rrtzid	String	false	Timezone eg: "Asia/Kolkata"
isNextOccurrenceBasedOnCompletion	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.
cadenceType	String	false	Creation cadence for workOrders, when all next set of workOrders to be created until next interval. Allowed values: "EVERY_N_DAYS", "EVERY_N_WEEKS", "EVERY_N_WEEKS_BY_DAY_OF_THE_WEEK", "EVERY_N_MONTHS", "EVERY_N_MONTHS_ON_NTH_WEEKDAY", "EVERY_N_MONTHS_ON_NTH_DAY_FROM_BEGINNING_OR_END", "EVERY_N_YEARS"
cadenceInterval	Integer	false	Interval for trigger cadence according to cadenceType.
cadenceFreq	String	false	One value can be passed. Allowed values are `DAILY, WEEKLY, MONTHLY, YEARLY`
meter	String	false
meterCondition	String	false
meterConditionValue	String	false
meterDueInterval	Integer	false
meterDueFrequency	String	false

Below are the properties that can be passed with workOrder object.

Parameter	Type	Required	Description
title	String	false
priority	Integer	false	To specify priority for workOrder
asset	String	false	ID of asset
location	String	false	ID of location
category	String	false	Name of category eg: "Electrical"
assignedToUser	String	false	ID of user whom the work order is assigned
additionalUsers	Array of String	false	Array of IDs of users eg: ["X8Gn34mUSY", "iO4FPJPBDA"]
parts	Array of String	false	Array of IDs of parts
respectivePartQuantityUsed	Array of Integer	false	Array of quantities for provided Array of parts in same sequence.
duration	Integer	false	Duration of work order in hours

Delete a Specific PM-Trigger

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

{
  "success": true,
  "data": [
    {
      "trigger": {...},
      "workOrder": {...}
    }
  ],
  "message": "1 trigger deleted"
}

This endpoint deletes a specific PM-Trigger.

HTTP Request

DELETE https://api.onupkeep.com/api/v2/preventive-maintenance/<ID>

URL Parameters

Parameter	Description
ID	The ID of the PM-Trigger to delete

Legacy Recurring Work Orders (SUNSET AS OF VERSION 2022-09-14)

Create a Legacy Recurring Work Order (SUNSET)

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 Legacy Recurring Work Orders (SUNSET)

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 gets 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	Type	Default	Description
title	String	undefined	If set, only work orders with this title will be included.
status	String	undefined	If set, only work orders with this status will be included. Allowed values `open`, `onHold`, `inProgress`, `complete`.
archivedStatus	String	undefined	If set to "1", only work orders that have been archived will be included.
priority	String	undefined	If set, only work orders with this priority will be included.
category	String	undefined	If set, only work orders with this category will be included.
asset	String	undefined	The ID of the asset. If set, only work orders associated with this asset will be included.
location	String	undefined	The ID of the location. If set, only work orders assigned to this location will be included.
recurringSchedule	String	undefined	If set, only work orders with this repeating schedule will be included.
rescheduledBasedOnCompletion	String	undefined	Send 'true' or 'false' to filter Work Orders rescheduled based on completion.
assignedToUser	String	undefined	The ID of the user. If set, only work orders assigned to this user will be included.
assignedByUser	String	undefined	The ID of the user. If set, only work orders assigned by this user will be included.
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`, `dueDate`, `endDueDate`, `dateCompleted`. Second value: `ASC` or `DESC`.
includes	Array or String	undefined	Expandable objects are `asset`, `location`, `assignedToUser`, `assignedByUser`, `requestedByUser`, `completedByUser`, `team`.
dueDateGreaterThan dueDateLessThan dueDateGreaterThanOrEqualTo dueDateLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?dueDateGreaterThanOrEqualTo=1598983706000&dueDateLessThanOrEqualTo=1599761306000`
endDueDateGreaterThan endDueDateLessThan endDueDateGreaterThanOrEqualTo endDueDateLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?endDueDateGreaterThanOrEqualTo=1598983706000&endDueDateLessThanOrEqualTo=1599761306000`
dateCompletedGreaterThan dateCompletedLessThan dateCompletedGreaterThanOrEqualTo dateCompletedLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?dateCompletedGreaterThanOrEqualTo=1598983706000&dateCompletedLessThanOrEqualTo=1599761306000`
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

Get a Specific Legacy Recurring Work Order (SUNSET)

curl "https://api.onupkeep.com/api/v2/preventative-maintenance/<ID>"
  -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 gets 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 get

Query Parameters

Parameter	Type	Default	Description
includes	Array or String	undefined	Expandable objects are `asset`, `location`, `assignedToUser`, `assignedByUser`, `completedByUser`, `team`, `formItems`, `parts`, `arrayOfUpdateItems`, `additionalUsers`, `files` , `formItems`.

Update a Legacy Recurring Work Order (SUNSET)

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 Legacy Recurring Work Order (SUNSET)

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 (SUNSET AS OF VERSION 2022-09-14)

Get The Schedule of Legacy Recurring Work Orders (SUNSET)

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 gets 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	Type	Default	Description
utcOffset	Number	0	Difference between UTC and your time-zone in minutes.
title	String	undefined	If set, only work orders with this title will be included.
category	String	undefined	If set, only work orders with this category will be included.
asset	String	undefined	The ID of the asset. If set, only work orders associated with this asset will be included.
location	String	undefined	The ID of the location. If set, only work orders assigned to this location will be included.
recurringSchedule	String	undefined	If set, only work orders with this repeating schedule will be included.
rescheduledBasedOnCompletion	String	undefined	Send 'true' or 'false' to filter Work Orders rescheduled based on completion.
assignedToUser	String	undefined	The ID of the user. If set, only work orders assigned to this user will be included.
assignedByUser	String	undefined	The ID of the user. If set, only work orders assigned by this user will be included.
offset	Number	undefined	Offset for pagination. The pagination is based on root Work Orders i.e. Preventative Maintenance Work Orders.
limit	Number	undefined	Limit for pagination. The pagination is based on root Work Orders i.e. Preventative Maintenance Work Orders.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`, `dueDate`, `endDueDate`, `dateCompleted`. Second value: `ASC` or `DESC`.
includes	Array or String	undefined	Expandable objects are `asset`, `location`, `assignedToUser`, `assignedByUser`, `requestedByUser`, `completedByUser`, `team`.
dueDateGreaterThan dueDateLessThan dueDateGreaterThanOrEqualTo dueDateLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?dueDateGreaterThanOrEqualTo=1598983706000&dueDateLessThanOrEqualTo=1599761306000`
endDueDateGreaterThan endDueDateLessThan endDueDateGreaterThanOrEqualTo endDueDateLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?endDueDateGreaterThanOrEqualTo=1598983706000&endDueDateLessThanOrEqualTo=1599761306000`
dateCompletedGreaterThan dateCompletedLessThan dateCompletedGreaterThanOrEqualTo dateCompletedLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?dateCompletedGreaterThanOrEqualTo=1598983706000&dateCompletedLessThanOrEqualTo=1599761306000`
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

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 gets all meters for your account.

HTTP Request

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

Query Parameters

Parameter	Type	Default	Description
name	String	undefined	If set, the result will only include meters with that name.
asset	String	undefined	The ID of the asset. If set, the result will only include meters assigned to this asset.
location	String	undefined	The ID of the location. If set, the result will only include meters assigned to this location.
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`. Second value: `ASC` or `DESC`.
includes	Array or String	undefined	Expandable objects are `asset`, `location`, `createdByUser`.
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

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 gets 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 get

Query Parameters

Parameter	Type	Default	Description
includes	Array or String	undefined	Expandable objects are `asset`, `location`, `createdByUser`, `lastReading`.

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
  -d date="2018-01-30T10:05:20.402Z"

{
  "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
date	String or Number	false	Meter reading timestamp field. Must be an ISO 8601 timestamp, or Unix time in miliseconds.

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.

Update a Specific Meter Reading

curl "https://api.onupkeep.com/api/v2/meters/<meterID>/readings/<readingId>"
  -H "Session-Token: session_token_here"
  -X PATCH
  -d value=12.34
  -d date="2018-01-30T10:05:20.402Z"

{
  "success": true,
  "result": {
    "id": "iGIkXrVtGS",
    "date": "2018-01-30T10:05:20.402Z",
    "meter": "GvWe2sCUkY",
    "value": 12.34,
    "createdByUser": "lv6FZopMhz",
    "createdAt": "2017-06-30T11:05:49.425Z",
    "updatedAt": "2018-01-30T10:05:20.425Z"
  }
}

This updates a specific meter reading.

HTTP Request

PATCH https://api.onupkeep.com/api/v2/meters/<meterID>/readings/<readingId>

Request Body

Provide any of the below fields for the meter reading.

Parameter	Type	Required	Description
value	Number	false
date	String or Number	false	Meter reading timestamp field. Must be an ISO 8601 timestamp, or Unix time in miliseconds.

URL Parameters

Parameter	Description
meterID	The ID of the meter
readingID	The ID of the meter reading

Delete a Specific Meter Reading

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

{
  "success": true,
  "message": "deleted reading record: <readingId>"
}

This deletes a reading from a specific meter.

HTTP Request

DELETE https://api.onupkeep.com/api/v2/meters/<meterID>/readings/<readingId>

URL Parameters

Parameter	Description
meterID	The ID of the meter
readingID	The ID of the meter reading

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 gets all readings for a meter.

HTTP Request

GET https://api.onupkeep.com/api/v2/meters/<meterID>/readings

Query Parameters

Parameter	Type	Default	Description
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
includes	Array or String	undefined	Expandable objects are `createdByUser`, `meter`.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`. Second value: `ASC` or `DESC`.
dateGreaterThan dateLessThan dateGreaterThanOrEqualTo dateLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?dateGreaterThanOrEqualTo=1598983706000&dateLessThanOrEqualTo=1599761306000`
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

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,
    "lastValueForWorkOrder": 0,
    "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'.
lastValueForWorkOrder	Number	false	The baseline value for the meter trigger.
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,
      "lastValueForWorkOrder": 0,
      "assignedToUser": "qTmhmORg85",
      "createdByUser": "lv6FZopMhz",
      "createdAt": "2018-02-05T05:06:24.570Z",
      "updatedAt": "2018-02-05T05:06:24.570Z"
    }
  ]
}

This endpoint gets all notifications for a particular meter.

HTTP Request

GET https://api.onupkeep.com/api/v2/meters/<meterID>/notifications

Query Parameters

Parameter	Type	Default	Description
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
includes	Array or String	undefined	Expandable objects are `assignedToUser`, `createdByUser`.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`. Second value: `ASC` or `DESC`.
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

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,
    "lastValueForWorkOrder": 0,
    "assignedToUser": "qTmhmORg85",
    "createdByUser": "lv6FZopMhz",
    "createdAt": "2018-02-05T05:06:24.570Z",
    "updatedAt": "2018-02-05T05:06:24.570Z"
  }
}

This endpoint gets 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 get
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 lastValueForWorkOrder=200

{
  "success": true,
  "result": {
    "id": "LNbrsMFfMy",
    "title": "Change breakers every 100 hours",
    "triggerFrequency": "EVERY_TIME_REACHES",
    "description": "Triggers every 100 hours",
    "triggerValue": 100,
    "lastValueForWorkOrder": 200,
    "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'.
lastValueForWorkOrder	Number	false	The baseline value for the meter trigger.
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",
        "customFieldsPO": [
          {
            "name": "SAPPONumber",
            "value": "110-235"
          }
        ]
      }'

{
  "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": "Recommended by engineering team",
    "companyName": "AB Inc",
    "companySlogan": "Time is money",
    "companyStreet": "23 Chester Avenue",
    "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",
    "customFieldsPO": [
      {
        "id": "gmWTEJ77op",
        "name": "SAPPONumber",
        "value": "110-235",
        "purchaseOrder": "XHUi1SyW0t",
        "user": "7w6jIHFdEr",
        "createdAt": "2020-09-23T20:12:16.889Z",
        "updatedAt": "2020-09-23T20:12:16.889Z"
      }
    ],
    "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 the 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 of objects	false	A list of parts of the purchase order. Its child attributes are `id` and `quantity`.
vendor	String	false	The ID of the vendor.
description	String	false
category	String	false	The category of the purchase order. Must be one of the configured categories for purchase orders.
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
customFieldsPO	Array of objects	false	A list of custom fields of the purchase order. Its child attributes are `name`, `value`, and `unit`.

Note

Custom fields can be added using this endpoint.

Get All Purchase Orders

curl 'https://api.onupkeep.com/api/v2/purchase-orders'
  -H 'Session-Token: session_token_here'

{
  "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",
      "partsPendingQuantities": {
          "t0RYP2jIPz": 5
      },
      "totalQuantity": 5,
      "totalCost": 60,
      "tax": 12,
      "shippingCost": 120,
      "otherCost": 1300,
      "requisitioner": "Mark Boucher",
      "shippingMethod": "Ground",
      "fobPoint": "184.83",
      "terms": "T & C apply",
      "notes": "Recommended by engineering team",
      "companyName": "AB Inc",
      "companySlogan": "Time is money",
      "companyStreet": "23 Chester Avenue",
      "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 gets all purchase orders.

HTTP Request

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

Query Parameters

Parameter	Type	Default	Description
title	String	undefined	If set, the result will only include purchase orders with that title.
status	String	undefined	If set, the result will only include purchase orders with that status.
vendor	String	undefined	If set, the result will only include purchase orders with that vendor.
category	String	undefined	If set, the result will only include purchase orders with that category.
createdByUser	String	undefined	The ID of the user. If set, the result will only include parts created by this user.
customFieldsPO	Object	undefined	If set, the result will only include purchase orders with matching custom field name, value, and unit. Example `https...?customFieldsPO[name]=SAPPONumber&customFieldsPO[value]=110-235`
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`, `dueDate`, `poDate`, `fulfilledAt`, `approvedAt`, `declinedAt`. Second value: `ASC` or `DESC`.
includes	Array or String	undefined	Expandable objects are `vendor`, `createdByUser`, `approvedByUser`, `fulfilledByUser`, `declinedByUser`.
dueDateGreaterThan dueDateLessThan dueDateGreaterThanOrEqualTo dueDateLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?dueDateGreaterThanOrEqualTo=1598983706000&dueDateLessThanOrEqualTo=1599761306000`
poDateGreaterThan poDateLessThan poDateGreaterThanOrEqualTo poDateLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?poDateGreaterThanOrEqualTo=1598983706000&poDateLessThanOrEqualTo=1599761306000`
fulfilledAtGreaterThan fulfilledAtLessThan fulfilledAtGreaterThanOrEqualTo fulfilledAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?fulfilledAtGreaterThanOrEqualTo=1598983706000&fulfilledAtLessThanOrEqualTo=1599761306000`
approvedAtGreaterThan approvedAtLessThan approvedAtGreaterThanOrEqualTo approvedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?approvedAtGreaterThanOrEqualTo=1598983706000&approvedAtLessThanOrEqualTo=1599761306000`
declinedAtGreaterThan declinedAtLessThan declinedAtGreaterThanOrEqualTo declinedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?declinedAtGreaterThanOrEqualTo=1598983706000&declinedAtLessThanOrEqualTo=1599761306000`
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

Get a Specific Purchase Order

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

{
  "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",
    "arrayOfUpdateItems": [
      "GnH5qjCybL"
    ],
    "customFieldsPO": [
      {
        "id": "gmWTEJ77op",
        "name": "SAPPONumber",
        "value": "110-235",
        "purchaseOrder": "XHUi1SyW0t",
        "user": "7w6jIHFdEr",
        "createdAt": "2020-09-23T20:12:16.889Z",
        "updatedAt": "2020-09-23T20:12:16.889Z"
      }
    ],
    "createdAt": "2018-06-08T09:15:46.452Z",
    "updatedAt": "2018-06-08T09:15:46.452Z"
  }
}

This endpoint gets 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 get.

Query Parameters

Parameter	Type	Default	Description
includes	Array or String	undefined	Expandable objects are `vendor`, `parts`, `createdByUser`, `approvedByUser`, `fulfilledByUser`, `declinedByUser`, and `arrayOfUpdateItems`.

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",
        "customFieldsPO": [
          {
            "name": "SAPPurchaseGroup",
            "value": "3937" 
          }
        ]
      }'

{
  "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",
    "arrayOfUpdateItems": [
      "GnH5qjCybL"
    ],
    "customFieldsPO": [
      {
        "id": "qrRapzY159",
        "name": "SAPPurchaseGroup",
        "value": "3937",
        "purchaseOrder": "XHUi1SyW0t",
        "user": "7w6jIHFdEr",
        "createdAt": "2020-09-23T20:18:00.975Z",
        "updatedAt": "2020-09-23T20:18:00.975Z"
      },
      {
        "id": "gmWTEJ77op",
        "name": "SAPPONumber",
        "value": "110-235",
        "purchaseOrder": "XHUi1SyW0t",
        "user": "7w6jIHFdEr",
        "createdAt": "2020-09-23T20:12:16.889Z",
        "updatedAt": "2020-09-23T20:12:16.889Z"
      }
    ],
    "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	Default	Description
title	String	undefined	true
status	String	undefined	Allowed values 'awaiting', 'approved', 'declined', 'fulfilled'
parts	Array of objects	undefined	A list of parts of the purchase order. Its child attributes are `id` and `quantity`.
vendor	String	undefined	The ID of the vendor.
description	String	undefined
category	String	undefined	The category of the purchase order. Must be one of the configured categories for purchase orders.
dueDate	String	undefined
poDate	String	undefined	Date of purchase order.
tax	Number	undefined
shippingCost	Number	undefined
otherCost	Number	undefined
requisitioner	String	undefined
shippingMethod	String	undefined
fobPoint	String	undefined	Free on board shipping point.
terms	String	undefined
notes	String	undefined
companyName	String	undefined
companySlogan	String	undefined
companyStreet	String	undefined
companyCity	String	undefined
companyState	String	undefined
companyZip	String	undefined
companyPhone	String	undefined
companyFax	String	undefined
shippingName	String	undefined
shippingCompany	String	undefined
shippingStreet	String	undefined
shippingCity	String	undefined
shippingState	String	undefined
shippingZip	String	undefined
shippingPhone	String	undefined
shippingFax	String	undefined
customFieldsPO	Array of objects	undefined	A list of custom fields of the purchase order. Its child attributes are `name`, `value`, and `unit`.

Note

Custom fields can be added using this endpoint. Null value for customFieldPO will not delete custom fields. Use the Custom Fields for Purchase Orders endpoints to update and delete custom fields.

For updating parts in Purchase order, it is 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 endpoint 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	Default	Description
statusAction	String	undefined	Allowed value: `partially-fulfilled`
partsReceived	Object	undefined	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.

Create an Update Message for a Specific Purchase Order

curl 'https://api.onupkeep.com/api/v2/purchase-orders/<ID>/update-messages'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X POST
  -d '{
        "text": "Will be delivered soon"
      }'

{
  "success": true,
  "message": "update message added"
}

This endpoint creates an update message for a specific purchase order.

HTTP Request

POST https://api.onupkeep.com/api/v2/purchase-orders/<ID>/update-messages

Request Body

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

Parameter	Type	Required	Description
text	String	true	A short update message.

URL Parameters

Parameter	Description
ID	The ID of the purchase order.

Get a Custom Field for a Specific Purchase Order

curl 'https://api.onupkeep.com/api/v2/purchase-orders/<purchaseOrderID>/custom-fields/<fieldID>'
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "result": {
    "id": "AvmCM4NHrI",
    "name": "Floor",
    "value": "1st",
    "location": "jpSMgHPr11",
    "user": "lv6FZopMhz",
    "createdAt": "2018-05-17T07:38:33.619Z",
    "updatedAt": "2018-05-17T07:38:33.619Z"
  }
}

This endpoint gets a custom field for a specific purchase order.

HTTP Request

GET https://api.onupkeep.com/api/v2/purchase-orders/<purchaseOrderID>/custom-fields/<fieldID>

URL Parameters

Parameter	Description
purchaseOrderID	The ID of the purchase order.
fieldID	The ID of the custom field.

Update a Custom Field for a Specific Purchase Order

curl 'https://api.onupkeep.com/api/v2/purchase-orders/<purchaseOrderID>/custom-fields/<fieldID>'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X PATCH
  -d '{
        "value": "2nd",
      }'

{
  "success": true,
  "result": {
    "id": "AvmCM4NHrI",
    "name": "Floor",
    "value": "2nd",
    "location": "jpSMgHPr11",
    "user": "lv6FZopMhz",
    "createdAt": "2018-05-17T07:38:33.619Z",
    "updatedAt": "2018-05-17T07:38:33.619Z"
  }
}

This endpoint updates a custom field for a specific purchase order.

HTTP Request

PATCH https://api.onupkeep.com/api/v2/purchase-orders/<purchaseOrderID>/custom-fields/<fieldID>

URL Parameters

Parameter	Description
purchaseOrderID	The ID of the location.
fieldID	The ID of the custom field.

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	Default	Description
name	String	undefined	The name of the custom field.
value	String	undefined	The value of the custom field.
unit	String	undefined	The unit of measurement.

Delete a Custom Field for a Specific Purchase Order

curl 'https://api.onupkeep.com/api/v2/purchase-orders/<purchaseOrderID>/custom-fields/<fieldID>'
  -X DELETE
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "message": "1 custom field deleted"
}

This endpoint deletes a custom field for a specific purchase order.

HTTP Request

DELETE https://api.onupkeep.com/api/v2/purchase-orders/<purchaseOrderID>/custom-fields/<fieldID>

URL Parameters

Parameter	Description
purchaseOrderID	The ID of the purchase order.
fieldID	The ID of the custom field.

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 gets all Purchase Order Categories.

HTTP Request

GET https://api.onupkeep.com/api/v2/purchase-order-categories/

Query Parameters

Parameter	Type	Default	Description
name	String	undefined	If set, the result will only include purchase order categories with that name.
offset	Number	undefined	Offset for pagination.
limit	Number	undefined	Limit for pagination.
orderBy	String	createdAt DESC	Sorting for pagination. First value is the field: `createdAt`, `updatedAt`. Second value: `ASC` or `DESC`.
createdAtGreaterThan createdAtLessThan createdAtGreaterThanOrEqualTo createdAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?createdAtGreaterThanOrEqualTo=1598983706000&createdAtLessThanOrEqualTo=1599761306000`
updatedAtGreaterThan updatedAtLessThan updatedAtGreaterThanOrEqualTo updatedAtLessThanOrEqualTo	Number	undefined	Value must be unix timestamp in milliseconds. Example `https...?updatedAtGreaterThanOrEqualTo=1598983706000&updatedAtLessThanOrEqualTo=1599761306000`

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 gets 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 get

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

Webhooks

Webhooks enable you to push data in real-time and sync your applications with UpKeep as events are taking place within your account. A webhook endpoint is just more code on your server, which could be written in any language, or it can even be from hosted services, such as AWS, Zapier, or Workato.

You can set up your webhooks by navigating to the Settings page and selecting the Webhooks header or programatically using the Webhooks endpoints. You can enter any endpoint as the destination for events and which event types to subscribe to. You also have the option of disabling a webhook temporarily.

Learn more about webhooks here.

Create a Webhook

curl 'https://api.onupkeep.com/api/v2/webhooks'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X POST
  -d '{
        "title": "Zapier Webhook",
        "endpoint": "https://hooks.zapier.com/hooks/catch/1234567/abcdef/",
        "events": ["*"]
      }'

{
  "success": true,
  "result": {
    "id": "110",
    "endpoint": "https://hooks.zapier.com/hooks/catch/1234567/abcdef/",
    "events": [
      "WORK_ORDER_CREATED",
      "WORK_ORDER_UPDATED",
      "WORK_ORDER_STATUS_UPDATED",
      "WORK_ORDER_DELETED",
      "PM_WORK_ORDER_CREATED",
      "PM_WORK_ORDER_UPDATED",
      "PM_WORK_ORDER_DELETED",
      "WORK_ORDER_SCHEDULE_CREATED",
      "WORK_ORDER_SCHEDULE_UPDATED",
      "WORK_ORDER_SCHEDULE_STATUS_UPDATED",
      "WORK_ORDER_SCHEDULE_DELETED",
      "PURCHASE_ORDER_UPDATED",
      "PURCHASE_ORDER_CREATED",
      "PURCHASE_ORDER_DELETED",
      "PURCHASE_ORDER_APPROVED",
      "PURCHASE_ORDER_DECLINED",
      "REQUEST_CREATED",
      "REQUEST_UPDATED",
      "REQUEST_APPROVED",
      "REQUEST_REJECTED"
    ],
    "title": "Zapier Integration",
    "enabled": false
  }
}

This endpoint creates a webhook.

HTTP Request

POST https://api.onupkeep.com/api/v2/webhooks

Request Body

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

Parameter	Type	Required	Description
title	String	true	The title of the webhook.
endpoint	String	true	The endpoint to register for the webhook.
events	Array	false	To enable all events: `*` Possible event values: `WORK_ORDER_CREATED` `WORK_ORDER_UPDATED` `WORK_ORDER_STATUS_UPDATED` `WORK_ORDER_DELETED` `PM_WORK_ORDER_CREATED` `PM_WORK_ORDER_UPDATED` `PM_WORK_ORDER_DELETED` `WORK_ORDER_SCHEDULE_CREATED` `WORK_ORDER_SCHEDULE_UPDATED` `WORK_ORDER_SCHEDULE_STATUS_UPDATED` `WORK_ORDER_SCHEDULE_DELETED` `PURCHASE_ORDER_UPDATED` `PURCHASE_ORDER_CREATED` `PURCHASE_ORDER_DELETED` `PURCHASE_ORDER_APPROVED` `PURCHASE_ORDER_DECLINED` `REQUEST_CREATED` `REQUEST_UPDATED` `REQUEST_APPROVED` `REQUEST_REJECTED`

Get All Webhooks

curl 'https://api.onupkeep.com/api/v2/webhooks'
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "results": [
    {
      "id": "110",
      "endpoint": "https://hooks.zapier.com/hooks/catch/1234567/abcdef/",
      "events": [
        "WORK_ORDER_CREATED",
        "WORK_ORDER_UPDATED",
        "WORK_ORDER_STATUS_UPDATED",
        "WORK_ORDER_DELETED",
        "PM_WORK_ORDER_CREATED",
        "PM_WORK_ORDER_UPDATED",
        "PM_WORK_ORDER_DELETED",
        "WORK_ORDER_SCHEDULE_CREATED",
        "WORK_ORDER_SCHEDULE_UPDATED",
        "WORK_ORDER_SCHEDULE_STATUS_UPDATED",
        "WORK_ORDER_SCHEDULE_DELETED",
        "PURCHASE_ORDER_UPDATED",
        "PURCHASE_ORDER_CREATED",
        "PURCHASE_ORDER_DELETED",
        "PURCHASE_ORDER_APPROVED",
        "PURCHASE_ORDER_DECLINED",
        "REQUEST_CREATED",
        "REQUEST_UPDATED",
        "REQUEST_APPROVED",
        "REQUEST_REJECTED"
      ],
      "title": "Zapier Integration",
      "enabled": false
    }
  ]
}

This endpoint gets all webhooks.

HTTP Request

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

Get a Specific Webhook

curl 'https://api.onupkeep.com/api/v2/webhooks/<ID>'
  -H 'Session-Token: session_token_here'

{
  "success": true,
  "result": {
    "id": "110",
    "endpoint": "https://hooks.zapier.com/hooks/catch/1234567/abcdef/",
    "events": [
      "WORK_ORDER_CREATED",
      "WORK_ORDER_UPDATED",
      "WORK_ORDER_STATUS_UPDATED",
      "WORK_ORDER_DELETED",
      "PM_WORK_ORDER_CREATED",
      "PM_WORK_ORDER_UPDATED",
      "PM_WORK_ORDER_DELETED",
      "WORK_ORDER_SCHEDULE_CREATED",
      "WORK_ORDER_SCHEDULE_UPDATED",
      "WORK_ORDER_SCHEDULE_STATUS_UPDATED",
      "WORK_ORDER_SCHEDULE_DELETED",
      "PURCHASE_ORDER_UPDATED",
      "PURCHASE_ORDER_CREATED",
      "PURCHASE_ORDER_DELETED",
      "PURCHASE_ORDER_APPROVED",
      "PURCHASE_ORDER_DECLINED",
      "REQUEST_CREATED",
      "REQUEST_UPDATED",
      "REQUEST_APPROVED",
      "REQUEST_REJECTED"
    ],
    "title": "Zapier Integration",
    "enabled": false
  }
}

This endpoint gets a specific webhook.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the webhook to get.

Update a Specific Webhook

curl 'https://api.onupkeep.com/api/v2/webhooks/<ID>'
  -H 'Session-Token: session_token_here'
  -H 'Content-Type: application/json'
  -X PATCH
  -d '{
        "enabled": true
      }'

{
  "success": true,
  "result": {
    "id": "110",
    "endpoint": "https://hooks.zapier.com/hooks/catch/1234567/abcdef/",
    "events": [
      "WORK_ORDER_CREATED",
      "WORK_ORDER_UPDATED",
      "WORK_ORDER_STATUS_UPDATED",
      "WORK_ORDER_DELETED",
      "PM_WORK_ORDER_CREATED",
      "PM_WORK_ORDER_UPDATED",
      "PM_WORK_ORDER_DELETED",
      "WORK_ORDER_SCHEDULE_CREATED",
      "WORK_ORDER_SCHEDULE_UPDATED",
      "WORK_ORDER_SCHEDULE_STATUS_UPDATED",
      "WORK_ORDER_SCHEDULE_DELETED",
      "PURCHASE_ORDER_UPDATED",
      "PURCHASE_ORDER_CREATED",
      "PURCHASE_ORDER_DELETED",
      "PURCHASE_ORDER_APPROVED",
      "PURCHASE_ORDER_DECLINED",
      "REQUEST_CREATED",
      "REQUEST_UPDATED",
      "REQUEST_APPROVED",
      "REQUEST_REJECTED"
    ],
    "title": "Zapier Integration",
    "enabled": true
  }
}

This endpoint updates a specific webhook.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the webhook to update.

Request Body

Parameter	Type	Default	Description
title	String	undefined	The title of the webhook.
endpoint	String	undefined	The endpoint to register for the webhook.
events	Array	undefined	To enable all events: `*` Possible event values: `WORK_ORDER_CREATED` `WORK_ORDER_UPDATED` `WORK_ORDER_STATUS_UPDATED` `WORK_ORDER_DELETED` `PM_WORK_ORDER_CREATED` `PM_WORK_ORDER_UPDATED` `PM_WORK_ORDER_DELETED` `WORK_ORDER_SCHEDULE_CREATED` `WORK_ORDER_SCHEDULE_UPDATED` `WORK_ORDER_SCHEDULE_STATUS_UPDATED` `WORK_ORDER_SCHEDULE_DELETED` `PURCHASE_ORDER_UPDATED` `PURCHASE_ORDER_CREATED` `PURCHASE_ORDER_DELETED` `PURCHASE_ORDER_APPROVED` `PURCHASE_ORDER_DECLINED` `REQUEST_CREATED` `REQUEST_UPDATED` `REQUEST_APPROVED` `REQUEST_REJECTED`
enabled	Boolean	undefined	Enables webhook.

Delete a Specific Webhook

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

{
  "success": true,
  "message": "1 webhook deleted"
}

This endpoint deletes a specific webhook.

HTTP Request

DELETE https://api.onupkeep.com/api/v2/webhooks/<ID>

URL Parameters

Parameter	Description
ID	The ID of webhook to delete.

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.