NAV Navbar
shell
  • Introduction
  • Authentication
  • Users
  • Customers
  • Vendors
  • Teams
  • Assets
  • Locations
  • Parts
  • Requests
  • Work Orders
  • Preventative Maintenance
  • Work Order Schedule
  • Meters
  • Common Use Cases
  • Errors
  • Introduction

    Welcome to the UpKeep API! You can use our API to control and gain access to data such as work orders and assets.

    The UpKeep API is enabled only for accounts on the Business Plus Plan or Enterprise Plan. For more information click here.

    Authentication

    The UpKeep API uses session tokens to authorize API calls. Session tokens can be generated with the credentials of any user in your account.

    Log In

    curl "https://api.onupkeep.com/api/v2/auth"
      -X POST
      -d email="user@onupkeep.com"
      -d password="password"
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "sessionToken": "r:4a25eddbf5aj42jk323f1472724hc43f",
        "expiresAt": "2018-12-31T00:00:00.000Z"
      }
    }
    

    This endpoint returns a session token for a valid email and password.

    HTTP Request

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

    Request Body

    Provide a valid email and password.

    Parameter Type Required
    email String true
    password String true

    Log Out

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "session deleted"
    }
    

    This endpoint invalidates an existing session.

    HTTP Request

    DELETE https://api.onupkeep.com/api/v2/auth/

    Users

    Create a User

    curl "https://api.onupkeep.com/api/v2/users/"
      -H "Session-Token: session_token_here"
      -X POST
      -d email="user@onupkeep.com"
      -d password="mypassword"
      -d accountType="ADMIN"
      -d firstName="Marty"
      -d lastName="McFly"
      -d phoneNumber="800-123-4567"
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "id": "fjQXLsOvG7",
        "accountType": "ADMIN",
        "email": "user@onupkeep.com",
        "firstName": "Marty",
        "lastName": "McFly",
        "phoneNumber": "800-123-4567",
        "createdAt": "2017-12-06T19:23:09.162Z",
        "updatedAt": "2017-12-08T18:41:44.335Z"
      }
    }
    

    This endpoint creates a new user.

    HTTP Request

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

    Request Body

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

    Parameter Type Required Description
    email String true
    accountType String true must be one of the following: ADMIN, TECH, VIEW_ONLY, REQUESTER, LIMITED_TECH
    password String true
    firstName String false
    lastName String false
    phoneNumber String false

    Get All Users

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "results": [
        {
          "id": "fjQXLsOvG7",
          "accountType": "ADMIN",
          "email": "user@onupkeep.com",
          "firstName": "Marty",
          "lastName": "McFly",
          "phoneNumber": "800-123-4567",
          "createdAt": "2017-12-06T19:23:09.162Z",
          "updatedAt": "2017-12-08T18:41:44.335Z"
        }
      ]
    }
    

    This endpoint retrieves all users for your account.

    HTTP Request

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

    Query Parameters

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

    Get a Specific User

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "id": "fjQXLsOvG7",
        "accountType": "ADMIN",
        "email": "user@onupkeep.com",
        "firstName": "Marty",
        "lastName": "McFly",
        "phoneNumber": "800-123-4567",
        "createdAt": "2017-12-06T19:23:09.162Z",
        "updatedAt": "2017-12-08T18:41:44.335Z"
      }
    }
    

    This endpoint retrieves a specific user.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the user to retrieve

    Update a Specific User

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "id": "fjQXLsOvG7",
        "accountType": "ADMIN",
        "email": "user@onupkeep.com",
        "firstName": "Marty",
        "lastName": "McFly",
        "phoneNumber": "800-123-4567",
        "createdAt": "2017-12-06T19:23:09.162Z",
        "updatedAt": "2017-12-08T18:41:44.335Z"
      }
    }
    

    This endpoint updates a specific user.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the user to retrieve

    Request Body

    Provide any of the below fields of the asset in the payload to update those specific fields. Null values are allowed to erase the value unless otherwise stated.

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

    Customers

    Create a Customer

    curl "https://api.onupkeep.com/api/v2/customers/"
      -H "Session-Token: session_token_here"
      -X POST
      -d name="Mark Boucher"
      -d email="user@onupkeep.com"
      -d phoneNumber="800-123-4567"
      -d description="A1 sevices manager"
      -d address="421 E Drachman, Hudson Street"
      -d website="www.aoneserv.com"
      -d type="Daily-User"
      -d billingName="Mark Boucher Sr"
      -d billingAddressLine1="345 B"
      -d billingAddressLine2="Jackson Street"
      -d billingAddressLine3="CA"
    

    The above command returns JSON structured like this:

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "results": [
        {
          "id": "fjQXLsOvG7",
          "name": "Mark Boucher",
          "email": "user@onupkeep.com",
          "description": "A1 sevices manager",
          "address": "421 E Drachman, Hudson Street",
          "phoneNumber": "800-123-4567",
          "website": "www.aoneserv.com",
          "type": "Daily-User",
          "billingName": "Mark Boucher Sr",
          "billingAddressLine1": "345 B",
          "billingAddressLine2": "Jackson Street",
          "billingAddressLine3": "CA",
          "customFieldsCustomer": [
            {
              "id": "fjQXLsOvG7",
              "name": "Title",
              "value": "Manager",
              "createdByUser": "lv6FZopMhz",
              "updatedByUser": "lv6FZopMhz",
              "customer": "fjQXLsOvG7",
              "createdAt": "2018-03-20T05:47:32.690Z",
              "updatedAt": "2018-03-20T05:47:32.690Z"
              }
          ],
          "createdAt": "2017-12-06T19:23:09.162Z",
          "updatedAt": "2017-12-08T18:41:44.335Z"
        }
      ]
    }
    

    This endpoint retrieves all customers for your account.

    HTTP Request

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

    Query Parameters

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

    Get a Specific Customer

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "id": "fjQXLsOvG7",
        "name": "Mark Boucher",
        "email": "user@onupkeep.com",
        "description": "A1 sevices manager",
        "address": "421 E Drachman, Hudson Street",
        "phoneNumber": "800-123-4567",
        "website": "www.aoneserv.com",
        "type": "Daily-User",
        "billingName": "Mark Boucher Sr",
        "billingAddressLine1": "345 B",
        "billingAddressLine2": "Jackson Street",
        "billingAddressLine3": "CA",
        "customFieldsCustomer": [
          {
            "id": "fjQXLsOvG7",
            "name": "Title",
            "value": "Manager",
            "createdByUser": "lv6FZopMhz",
            "updatedByUser": "lv6FZopMhz",
            "customer": "fjQXLsOvG7",
            "createdAt": "2018-03-20T05:47:32.690Z",
            "updatedAt": "2018-03-20T05:47:32.690Z"
            }
          ],
        "createdAt": "2017-12-06T19:23:09.162Z",
        "updatedAt": "2017-12-08T18:41:44.335Z"
      }
    }
    

    This endpoint retrieves a specific customer.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the customer to retrieve

    Update a Specific Customer

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

    The above command returns JSON structured like this:

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

    The above command returns JSON structured like this:

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "results": [
        {
          "id": "fjQXLsOvG7",
          "businessName": "AVC Inc.",
          "email": "user@onupkeep.com",
          "description": "A1 sevices manager",
          "businessAddress": "421 E Drachman, Hudson Street",
          "phoneNumber": "800-123-4567",
          "website": "www.aoneserv.com",
          "type": "Raw-Material",
          "mainPointOfContact": "Mark Boucher",
          "customFieldsVendor": [
            {
              "id": "4mFPJFLwxa",
              "name": "Title",
              "value": "Manager",
              "createdByUser": "lv6FZopMhz",
              "updatedByUser": "lv6FZopMhz",
              "vendor": "fjQXLsOvG7",
              "createdAt": "2018-03-20T05:53:25.017Z",
              "updatedAt": "2018-03-20T05:53:25.017Z"
            }
          ],
          "createdAt": "2017-12-06T19:23:09.162Z",
          "updatedAt": "2017-12-08T18:41:44.335Z"
        }
      ]
    }
    

    This endpoint retrieves all vendors for your account.

    HTTP Request

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

    Query Parameters

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

    Get a Specific Vendor

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "id": "fjQXLsOvG7",
        "businessName": "AVC Inc.",
        "email": "user@onupkeep.com",
        "description": "A1 sevices manager",
        "businessAddress": "421 E Drachman, Hudson Street",
        "phoneNumber": "800-123-4567",
        "website": "www.aoneserv.com",
        "type": "Raw-Material",
        "mainPointOfContact": "Mark Boucher",
        "customFieldsVendor": [
          {
            "id": "4mFPJFLwxa",
            "name": "Title",
            "value": "Manager",
            "createdByUser": "lv6FZopMhz",
            "updatedByUser": "lv6FZopMhz",
            "vendor": "fjQXLsOvG7",
            "createdAt": "2018-03-20T05:53:25.017Z",
            "updatedAt": "2018-03-20T05:53:25.017Z"
            }
          ],
        "createdAt": "2017-12-06T19:23:09.162Z",
        "updatedAt": "2017-12-08T18:41:44.335Z"
      }
    }
    

    This endpoint retrieves a specific vendor.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the vendors to retrieve

    Update a Specific Vendor

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

    The above command returns JSON structured like this:

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "name": "Team Doc",
        "description": "Marty! I need you to go back with me! Back to the future!",
        "createdAt": "2017-12-06T19:23:09.162Z",
        "updatedAt": "2017-12-08T18:41:44.335Z"
      }
    }
    

    This endpoint creates a new team.

    HTTP Request

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

    Request Body

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

    Parameter Type Required
    name String true
    description String true

    Get All Teams

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "results": [
        {
          "id": "fjQXLsOvG7",
          "name": "Team Doc",
          "description": "Marty! I need you to go back with me! Back to the future!",
          "createdAt": "2017-12-06T19:23:09.162Z",
          "updatedAt": "2017-12-08T18:41:44.335Z"
        }
      ]
    }
    

    This endpoint retrieves all teams for your account.

    HTTP Request

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

    Query Parameters

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

    Get a Specific Team

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "id": "fjQXLsOvG7",
        "name": "Team Doc",
        "description": "Marty! I need you to go back with me! Back to the future!",
        "createdAt": "2017-12-06T19:23:09.162Z",
        "updatedAt": "2017-12-08T18:41:44.335Z"
      }
    }
    

    This endpoint retrieves a specific team.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the team to retrieve

    Update a Specific Team

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "id": "fjQXLsOvG7",
        "name": "Team Marty",
        "description": "Marty! I need you to go back with me! Back to the future!",
        "createdAt": "2017-12-06T19:23:09.162Z",
        "updatedAt": "2017-12-08T18:41:44.335Z"
      }
    }
    

    This endpoint updates a specific team.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the team to retrieve

    Request Body

    Provide any of the below fields of the asset 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
    

    The above command returns JSON structured like this:

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

    This endpoint deletes a specific team.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the team to retrieve

    Get All Users for a Specific Team

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "results": [
        {
          "id": "fjQXLsOvG7",
          "accountType": "ADMIN",
          "email": "user@onupkeep.com",
          "firstName": "Marty",
          "lastName": "McFly",
          "phoneNumber": "800-123-4567",
          "createdAt": "2017-12-06T19:23:09.162Z",
          "updatedAt": "2017-12-08T18:41:44.335Z"
        }
      ]
    }
    

    This endpoint retrieves all users for a specific team.

    HTTP Request

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

    URL Parameters

    Parameter Description
    teamID The ID of the team to retrieve

    Add User to a Specific Team

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

    The above command returns JSON structured like this:

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "1 user removed from team <teamID>"
    }
    

    This endpoint removes users for a specific team.

    HTTP Request

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

    URL Parameters

    Parameter Description
    teamID The ID of the desired team
    userID The ID of the user to remove from the team

    Assets

    Create an Asset

    curl "https://api.onupkeep.com/api/v2/assets/"
      -H "Session-Token: session_token_here"
      -X POST
      -d name="The Deluxe Power Generator"
      -d UPCNumber="S5614B09118"
      -d model="Deluxe 5500"
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": [
        {
          "id": "fjQXLsOvG7",
          "UPCNumber": "S5614B09118",
          "additionalInformation": "2 feet by 2 feet",
          "model": "Deluxe 5500",
          "name": "The Ultra Power Generator",
          "notes": "Oldest generator in use",
          "serial": "1234567",
          "location": "OPkIOYYZ0F",
          "image": {
            "name": "image_generator_001.jpg",
            "url": "https://upkeep-production.s3.amazonaws.com/image_generator_001.jpg"
          },
          "status": "active",
          "description": "The Generator Powering Life Support for the Space Station",
          "category": "Generators",
          "assignedToUsername": "abc@def.com",
          "assignedToUser": "BZuHycQMog",
          "createdByUsername": "zys@abce.com",
          "createdByUser": "DNbSREeodF",
          "updatedAt": "2017-11-16T15:01:01",
          "createdAt": "2017-11-16T15:01:01"
        }
      ]
    }
    

    This endpoint creates a new asset.

    HTTP Request

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

    Request Body

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

    Parameter Type Required
    UPCNumber String false
    additionalInformation String false
    model String false
    name String true
    notes String false
    serial String false
    location String (ID) false
    status String; "active" or "not-active" false
    description String false
    category String, one of the set categories on your UpKeep account false
    assignedToUser String, the ID of the user object to assign to false

    Get All Assets

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "results": [
        {
          "id": "fjQXLsOvG7",
          "UPCNumber": "S5614B09118",
          "additionalInformation": "2 feet by 2 feet",
          "model": "Deluxe 5500",
          "name": "The Ultra Power Generator",
          "notes": "Oldest generator in use",
          "numberOfIncompleteWorkOrders": 55,
          "serial": "1234567",
          "location": "OPkIOYYZ0F",
          "image": {
            "name": "image_generator_001.jpg",
            "url": "https://upkeep-production.s3.amazonaws.com/image_generator_001.jpg"
          },
          "status": "active",
          "description": "The Generator Powering Life Support for the Space Station",
          "category": "Generators",
          "assignedToUsername": "abc@def.com",
          "assignedToUser": "BZuHycQMog",
          "createdByUsername": "zys@abce.com",
          "createdByUser": "DNbSREeodF",
          "updatedAt": "2017-11-16T15:01:01",
          "createdAt": "2017-11-16T15:01:01"
        }
      ]
    }
    

    This endpoint retrieves all assets for your account.

    HTTP Request

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

    Query Parameters

    Parameter Default Description
    name undefined If set, the result will only include assets with that name.
    UPCNumber undefined If set, the result will only include assets with this UPCNumber.
    model undefined If set, the result will only include assets with this model.
    serial undefined If set, the result will only include assets with this serial number.
    location undefined (ID) If set, the result will only include assets belonging to this location.
    status undefined If set, the result will only include assets with this status.
    category undefined If set, the result will only include assets with this category.
    assignedToUser undefined (ID) If set, the result will only include assets assigned to this user.
    createdByUser undefined (ID) If set, the result will only include assets created by this user.
    offset undefined (Number) offset for pagination.
    limit undefined (Number) limit for pagination.
    includes undefined (Array) send 'location','assignedToUser', 'createdByUser' to expand respective object
    orderBy createdAt DESC (String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

    Get a Specific Asset

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": [
        {
          "id": "fjQXLsOvG7",
          "UPCNumber": "S5614B09118",
          "additionalInformation": "2 feet by 2 feet",
          "model": "Deluxe 5500",
          "name": "The Ultra Power Generator",
          "notes": "Oldest generator in use",
          "numberOfIncompleteWorkOrders": 55,
          "serial": "1234567",
          "location": "OPkIOYYZ0F",
          "image": {
            "name": "image_generator_001.jpg",
            "url": "https://upkeep-production.s3.amazonaws.com/image_generator_001.jpg"
          },
          "status": "active",
          "description": "The Generator Powering Life Support for the Space Station",
          "category": "Generators",
          "assignedToUsername": "abc@def.com",
          "assignedToUser": "BZuHycQMog",
          "createdByUsername": "zys@abce.com",
          "createdByUser": "DNbSREeodF",
          "customFieldsAsset": [
            {
              "id": "AI5uBGp7nz",
              "name": "Width",
              "value": "10",
              "asset": "fjQXLsOvG7",
              "unit": "cm",
              "createdAt": "2018-03-20T06:54:48.325Z",
              "updatedAt": "2018-03-20T06:54:48.325Z"
            }
       ],
          "updatedAt": "2017-11-16T15:01:01",
          "createdAt": "2017-11-16T15:01:01"
        }
      ]
    }
    

    This endpoint retrieves a specific asset.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the asset to retrieve

    Query Parameters

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

    Update a Specific Asset

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": [
        {
          "id": "fjQXLsOvG7",
          "UPCNumber": "S5614B09118",
          "additionalInformation": "2 feet by 2 feet",
          "model": "Deluxe 5500",
          "name": "The Amazing Power Generator",
          "notes": "Oldest generator in use",
          "numberOfIncompleteWorkOrders": 55,
          "serial": "1234567",
          "location": "OPkIOYYZ0F",
          "image": {
            "name": "image_generator_001.jpg",
            "url": "https://upkeep-production.s3.amazonaws.com/image_generator_001.jpg"
          },
          "status": "active",
          "description": "The Generator Powering Life Support for the Space Station",
          "category": "Generators",
          "assignedToUsername": "abc@def.com",
          "assignedToUser": "BZuHycQMog",
          "createdByUsername": "zys@abce.com",
          "createdByUser": "DNbSREeodF",
          "updatedAt": "2017-11-16T15:01:01",
          "createdAt": "2017-11-16T15:01:01"
        }
      ]
    }
    

    This endpoint updates a specific asset.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the asset to update

    Request Body

    Provide any of the below fields of the asset in the payload to update those specific fields. Null values are allowed to erase the value unless otherwise stated.

    Parameter Type
    UPCNumber String
    additionalInformation String
    model String
    name String
    notes String
    serial String
    location String (ID)
    status String; "active" or "not-active"
    description String
    category String, one of the set categories on your UpKeep account
    assignedToUser String, the ID of the user object to assign to

    Delete a Specific Asset

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

    The above command returns JSON structured like this:

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

    This endpoint deletes a specific asset

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the asset to delete

    Assign User to an Asset

    curl "https://api.onupkeep.com/api/v2/assets/<assetID>/users/<userID>"
      -H "Session-Token: session_token_here"
      -X POST
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "user <userID> assigned to asset <assetID>"
    }
    

    This endpoint assigns user to a specific asset.

    HTTP Request

    POST https://api.onupkeep.com/api/v2/assets/<assetID>/users/<userID>

    URL Parameters

    Parameter Description
    assetID The ID of the desired asset
    userID The ID of the user to be assigned to asset.

    Remove Assigned User from an Asset

    curl "https://api.onupkeep.com/api/v2/assets/<assetID>/users/<userID>"
      -H "Session-Token: session_token_here"
      -X DELETE
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "user <userID> removed from asset <assetID>"
    }
    

    This endpoint removes assigned user from a specific asset.

    HTTP Request

    DELETE https://api.onupkeep.com/api/v2/assets/<assetID>/users/<userID>

    URL Parameters

    Parameter Description
    assetID The ID of the desired asset
    userID The ID of the user to be removed from asset.

    Assign Team to an Asset

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "team <teamID> assigned to asset <assetID>"
    }
    

    This endpoint assigns team to a specific asset.

    HTTP Request

    POST https://api.onupkeep.com/api/v2/assets/<assetID>/teams/<teamID>

    URL Parameters

    Parameter Description
    assetID The ID of the desired asset
    teamID The ID of the team to be assigned to asset.

    Remove Assigned Team from an Asset

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "team <teamID> removed from asset <assetID>"
    }
    

    This endpoint removes assigned team from a specific asset.

    HTTP Request

    DELETE https://api.onupkeep.com/api/v2/assets/<assetID>/teams/<teamID>

    URL Parameters

    Parameter Description
    assetID The ID of the desired asset
    teamID The ID of the team to be removed from asset.

    Assign Customer to an Asset

    curl "https://api.onupkeep.com/api/v2/assets/<assetID>/customers/<customerID>"
      -H "Session-Token: session_token_here"
      -X POST
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "customer <customerID> assigned to asset <assetID>"
    }
    

    This endpoint assigns customer to a specific asset.

    HTTP Request

    POST https://api.onupkeep.com/api/v2/assets/<assetID>/customers/<customerID>

    URL Parameters

    Parameter Description
    assetID The ID of the desired asset
    customerID The ID of the customer to be assigned to asset.

    Remove Assigned Customer from an Asset

    curl "https://api.onupkeep.com/api/v2/assets/<assetID>/customers/<customerID>"
      -H "Session-Token: session_token_here"
      -X DELETE
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "customer <customerID> removed from asset <assetID>"
    }
    

    This endpoint removes assigned customer from a specific asset.

    HTTP Request

    DELETE https://api.onupkeep.com/api/v2/assets/<assetID>/customers/<customerID>

    URL Parameters

    Parameter Description
    assetID The ID of the desired asset
    customerID The ID of the customer to be removed from asset.

    Assign Vendor to an Asset

    curl "https://api.onupkeep.com/api/v2/assets/<assetID>/vendors/<vendorID>"
      -H "Session-Token: session_token_here"
      -X POST
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "vendor <vendorID> assigned to asset <assetID>"
    }
    

    This endpoint assigns vendor to a specific asset.

    HTTP Request

    POST https://api.onupkeep.com/api/v2/assets/<assetID>/vendors/<vendorID>

    URL Parameters

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

    Remove Assigned Vendor from an Asset

    curl "https://api.onupkeep.com/api/v2/assets/<assetID>/vendors/<vendorID>"
      -H "Session-Token: session_token_here"
      -X DELETE
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "vendor <vendorID> removed from asset <assetID>"
    }
    

    This endpoint removes assigned vendor from a specific asset.

    HTTP Request

    DELETE https://api.onupkeep.com/api/v2/assets/<assetID>/vendors/<vendorID>

    URL Parameters

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

    Locations

    Create a Location

    curl "https://api.onupkeep.com/api/v2/locations/"
      -H "Session-Token: session_token_here"
      -X POST
      -d name="Sherlock Homes' House"
      -d address="221B Baker Street, London NW1 6XE, UK"
      -d longitude=51.523767
      -d latitude=-0.1585557
      -d hideMap="0"
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": [
        {
          "id": "jpSMgHPr11",
          "createdByUser": "lv6FZopMhz",
          "createdByUsername": "test@onupkeep.com",
          "name": "Sherlock Homes' House",
          "address": "221B Baker Street, London NW1 6XE, UK",
          "longitude": 51.523767,
          "latitude": -0.1585557,
          "hideMap": "0",
          "createdAt": "2017-10-23T23:51:58.098Z",
          "updatedAt": "2017-10-27T20:36:24.563Z"
        }
      ]
    }
    

    This endpoint creates a new location.

    HTTP Request

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

    Request Body

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

    Parameter Type Required
    name String true
    address String false
    longitude Float false
    latitude Float false
    hideMap Boolean as a string; "0" or "1" false

    Get All Locations

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "results": [
        {
          "id": "jpSMgHPr11",
          "createdByUser": "lv6FZopMhz",
          "createdByUsername": "test@onupkeep.com",
          "name": "Tutorial: Meeting Room",
          "address": "11087 Sunset Blvd, Los Angeles, CA 90049, USA",
          "longitude": -118.25525040000002,
          "latitude": 34.07583059999999,
          "hideMap": "0",
          "createdAt": "2017-10-23T23:51:58.098Z",
          "updatedAt": "2017-10-27T20:36:24.563Z"
        }
      ]
    }
    

    This endpoint retrieves all locations for your account.

    HTTP Request

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

    Query Parameters

    Parameter Default Description
    name undefined If set, the result will only include locations with that name.
    createdByUser undefined (ID) If set, the result will only include locations created by this user.
    offset undefined (Number) offset for pagination.
    limit undefined (Number) limit for pagination.
    includes undefined (Array) send 'createdByUser' to expand respective object.
    orderBy createdAt DESC (String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

    Get a Specific Location

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

    The above command returns JSON structured like this:

    {
      "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",
        "createdAt": "2017-10-23T23:51:58.098Z",
        "updatedAt": "2017-10-27T20:36:24.563Z"
      }
    }
    

    This endpoint retrieves a specific asset.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the location to retrieve

    Query Parameters

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

    Update a Specific Location

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": [
        {
          "id": "jpSMgHPr11",
          "createdByUser": "lv6FZopMhz",
          "createdByUsername": "test@onupkeep.com",
          "name": "Conference Room",
          "address": "11087 Sunset Blvd, Los Angeles, CA 90049, USA",
          "longitude": -118.25525040000002,
          "latitude": 34.07583059999999,
          "hideMap": "0",
          "createdAt": "2017-10-23T23:51:58.098Z",
          "updatedAt": "2017-10-27T20:36:24.563Z"
        }
      ]
    }
    

    This endpoint updates a specific location.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the location to update

    Request Body

    Provide any of the below fields of the location in the payload to update those specific fields. Null values are allowed to erase the value unless otherwise stated.

    Parameter Type
    name String
    address String
    longitude Float
    latitude Float
    hideMap Boolean as a string; "0" or "1"

    Delete a Specific Location

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

    The above command returns JSON structured like this:

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

    This endpoint deletes a specific location

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the location to delete

    Assign User to a Location

    curl "https://api.onupkeep.com/api/v2/locations/<locationID>/users/<userID>"
      -H "Session-Token: session_token_here"
      -X POST
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "user <userID> assigned to location <locationID>"
    }
    

    This endpoint assigns user to a specific location.

    HTTP Request

    POST https://api.onupkeep.com/api/v2/locations/<locationID>/users/<userID>

    URL Parameters

    Parameter Description
    locationID The ID of the desired location
    userID The ID of the user to be assigned to location.

    Remove Assigned User from a Location

    curl "https://api.onupkeep.com/api/v2/locations/<locationID>/users/<userID>"
      -H "Session-Token: session_token_here"
      -X DELETE
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "user <userID> removed from location <locationID>"
    }
    

    This endpoint removes assigned user from a specific location.

    HTTP Request

    DELETE https://api.onupkeep.com/api/v2/locations/<locationID>/users/<userID>

    URL Parameters

    Parameter Description
    locationID The ID of the desired location
    userID The ID of the user to be removed from location.

    Assign Team to a Location

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "team <teamID> assigned to location <locationID>"
    }
    

    This endpoint assigns team to a specific asset.

    HTTP Request

    POST https://api.onupkeep.com/api/v2/locations/<locationID>/teams/<teamID>

    URL Parameters

    Parameter Description
    locationID The ID of the desired location
    teamID The ID of the team to be assigned to location.

    Remove Assigned Team from a Location

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "team <teamID> removed from location <locationID>"
    }
    

    This endpoint removes assigned team from a specific location.

    HTTP Request

    DELETE https://api.onupkeep.com/api/v2/locations/<locationID>/teams/<teamID>

    URL Parameters

    Parameter Description
    locationID The ID of the desired location
    teamID The ID of the team to be removed from location.

    Assign Customer to a Location

    curl "https://api.onupkeep.com/api/v2/locations/<locationID>/customers/<customerID>"
      -H "Session-Token: session_token_here"
      -X POST
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "customer <customerID> assigned to location <locationID>"
    }
    

    This endpoint assigns customer to a specific location.

    HTTP Request

    POST https://api.onupkeep.com/api/v2/locations/<locationID>/customers/<customerID>

    URL Parameters

    Parameter Description
    locationID The ID of the desired location
    customerID The ID of the customer to be assigned to location.

    Remove Assigned Customer from a Location

    curl "https://api.onupkeep.com/api/v2/locations/<locationID>/customers/<customerID>"
      -H "Session-Token: session_token_here"
      -X DELETE
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "customer <customerID> removed from location <locationID>"
    }
    

    This endpoint removes assigned customer from a specific location.

    HTTP Request

    DELETE https://api.onupkeep.com/api/v2/locations/<locationID>/customers/<customerID>

    URL Parameters

    Parameter Description
    locationID The ID of the desired location
    customerID The ID of the customer to be removed from location.

    Assign Vendor to a Location

    curl "https://api.onupkeep.com/api/v2/locations/<locationID>/vendors/<vendorID>"
      -H "Session-Token: session_token_here"
      -X POST
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "vendor <vendorID> assigned to location <locationID>"
    }
    

    This endpoint assigns vendor to a specific location.

    HTTP Request

    POST https://api.onupkeep.com/api/v2/locations/<locationID>/vendors/<vendorID>

    URL Parameters

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

    Remove Assigned Vendor from a Location

    curl "https://api.onupkeep.com/api/v2/locations/<locationID>/vendors/<vendorID>"
      -H "Session-Token: session_token_here"
      -X DELETE
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "vendor <vendorID> removed from location <locationID>"
    }
    

    This endpoint removes assigned vendor from a specific location.

    HTTP Request

    DELETE https://api.onupkeep.com/api/v2/locations/<locationID>/vendors/<vendorID>

    URL Parameters

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

    Parts

    Create a Part

    curl "https://api.onupkeep.com/api/v2/parts/"
      -H "Session-Token: session_token_here"
      -X POST
      -d name="Flux Capacitor"
      -d description="This is what makes time travel possible."
      -d cost=88.00
      -d quantity=15
      -d minimumQuantity=1
      -d serial=40161502
      -d category="Compressor",
      -d location="jmHFWGVgd1"
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": [
        {
          "id": "1YHUWGVgdC",
          "name": "Flux Capacitor",
          "description": "This is what makes time travel possible.",
          "cost": "88.00",
          "quantity": "15",
          "minimumQuantity": "1",
          "serial": "40161502",
          "category": "Compressor",
          "location": "jmHFWGVgd1",
          "createdByUser": "pCmWGVgfW",
          "createdAt": "2017-10-23T23:51:58.097Z",
          "updatedAt": "2017-10-23T23:51:58.097Z"
        }
      ]
    }
    

    This endpoint creates a new part.

    HTTP Request

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

    Request Body

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

    Parameter Type Required Description
    name String true
    description String false
    cost Float false
    quantity Number false
    minimumQuantity Number false
    serial String false
    area String false
    details String false
    category String false
    location String (ID) false id of the location

    Get All Parts

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "results": [
        {
          "id": "1YHUWGVgdC",
          "image": {
            "name": "dfimg_part_du.jpg",
            "url": "https://upkeep-production.s3.amazonaws.com/dfimg_part_du.jpg"
          },
          "name": "Flux Capacitor",
          "description": "This is what makes time travel possible.",
          "cost": "88.00",
          "quantity": "5",
          "minimumQuantity": "1",
          "serial": "40161502",
          "area": "Mark street",
          "details": "additional details",
          "category": "Filter",
          "location": "jmHFWGVgd1",
          "createdByUser": "pCmWGVgfW",
          "createdAt": "2017-10-23T23:51:58.097Z",
          "updatedAt": "2017-10-23T23:51:58.097Z"
        }
      ]
    }
    

    This endpoint retrieves all parts for your account.

    HTTP Request

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

    Query Parameters

    Parameter Default Description
    name undefined If set the result will only include parts with that name.
    category undefined If set the result will only include parts with that category.
    location undefined (ID) If set the result will only include parts belonging to this location.
    createdByUser undefined (ID) If set the result will only include parts created by this user.
    offset undefined (Number) offset for pagination.
    limit undefined (Number) limit for pagination.
    includes undefined (Array) send 'location', createdByUser' to expand respective object.
    orderBy createdAt DESC (String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

    Get a Specific Part

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "id": "1YHUWGVgdC",
        "image": {
          "name": "dfimg_part_du.jpg",
          "url": "https://upkeep-production.s3.amazonaws.com/dfimg_part_du.jpg"
        },
        "name": "Flux Capacitor",
        "description": "This is what makes time travel possible.",
        "cost": "88.00",
        "quantity": "5",
        "minimumQuantity": "1",
        "serial": "40161502",
        "area": "Mark street",
        "details": "additional details",
        "category": "Filter",
        "location": "jmHFWGVgd1",
        "createdByUser": "pCmWGVgfW",
        "createdAt": "2017-10-23T23:51:58.097Z",
        "updatedAt": "2017-10-23T23:51:58.097Z"
      }
    }
    

    This endpoint retrieves a specific part.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the part to retrieve

    Query Parameters

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

    Update a Specific Part

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": [
        {
        "id": "1YHUWGVgdC",
        "image": {
          "name": "dfimg_part_du.jpg",
          "url": "https://upkeep-production.s3.amazonaws.com/dfimg_part_du.jpg"
        },
        "name": "Flux Capacitor",
        "description": "This is what makes time travel possible.",
        "cost": "88.00",
        "quantity": "100",
        "minimumQuantity": "1",
        "serial": "40161502",
        "area": "Mark street",
        "details": "additional details",
        "category": "Filter",
        "location": "jmHFWGVgd1",
        "createdByUser": "pCmWGVgfW",
        "createdAt": "2017-10-23T23:51:58.097Z",
        "updatedAt": "2017-10-23T23:51:58.097Z"
        }
      ]
    }
    

    This endpoint updates a specific part.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the part to update

    Request Body

    Provide any of the below fields of the part in the payload to update those specific fields. Null values are allowed to erase the value unless otherwise stated.

    Parameter Type
    name String
    description String
    cost Float
    quantity Number
    minimumQuantity Number
    serial String
    area String
    details String
    category String
    location String (ID)

    Delete a Specific Part

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

    The above command returns JSON structured like this:

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

    This endpoint deletes a specific part

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the part to delete

    Requests

    Create a Request

    curl "https://api.onupkeep.com/api/v2/requests/"
      -H "Session-Token: session_token_here"
      -X POST
      -d title="Repair sink"
      -d description="Sink broke yesterday"
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "id": "9shLaaHeMQ",
        "title": "Repair sink",
        "description": "Sink broke yesterday",
        "status": "open",
        "requestedByUser": "8PhLFaHelk",
        "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

    Events After Request is Created

    If the API returns with status 200:

    1. If your account has a Zapier integration enabled, data will be sent to Zapier for the new request trigger

    2. "New Request" emails will be sent to admins alerting them.

    Get All Requests

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "results": [
        {   
          "id": "hn5PE6HXAG", 
          "title": "Broken light in the production room",
          "description": "There is a light that is out in the production room.  Hint: Approving this request will move it to the work orders section",
          "image": {
              "__type": "File",
              "name": "dfimg_request2.jpg",
              "url": "https://demo-api-upkeep.s3.amazonaws.com/dfimg_request2.jpg"
          },
          "requestedByUser": "8PhLFaHelk",
          "createdAt": "2018-01-09T03:43:23.769Z",
          "updatedAt": "2018-01-09T03:43:23.769Z"           
        }
      ]
    }
    

    This endpoint retrieves all requests for your account.

    HTTP Request

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

    Query Parameters

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

    Get a Specific Request

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {   
          "id": "hn5PE6HXAG", 
          "title": "Tutorial: Broken light in the production room",
          "description": "There is a light that is out in the production room.  Hint: Approving this request will move it to the work orders section",
          "image": {
              "__type": "File",
              "name": "dfimg_request2.jpg",
              "url": "https://demo-api-upkeep.s3.amazonaws.com/dfimg_request2.jpg"
            },
          "publicRequesterEmail": "test@abc.com",  
          "createdAt": "2018-01-09T03:43:23.769Z",
          "updatedAt": "2018-01-09T03:43:23.769Z"           
      }
    }
    

    This endpoint retrieves a specific requests.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the request to retrieve

    Query Parameters

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

    Cancel a Specific Request

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

    The above command returns JSON structured like this:

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

    1. The requester will be sent an email informing him or her about request cancellation.

    Delete a Specific Request

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

    The above command returns JSON structured like this:

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

    This endpoint deletes a specific request.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the request to delete

    Work Orders

    Create a Work Order

    curl "https://api.onupkeep.com/api/v2/work-orders/"
      -H "Session-Token: session_token_here"
      -X POST
      -d title="Repair sink"
      -d description="Sink broke yesterday"
      -d priority=1
      -d dueDate=1515482422310
      -d asset="gDK45aHe12"
      -d location="MD565aHenL"
      -d assignedToUser="lv6FZopMhz"
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "id": "6yDTWLAEmh",
        "workOrderNo": "006",
        "title": "Repair sink",
        "description": "Sink broke yesterday",
        "status": "open",
        "dueDate": "2018-01-09T07:20:22.310Z",
        "assignedToUser": "vk6BHzQVCX",
        "assignedToUsername": "test@onupkeep.com",
        "asset": "knyWfDnXWo",
        "location": "cXRAu708NU",
        "assignedByUser": "lv6FZopMhz",
        "assignedByUsername": "test@onupkeep.com",
        "priority": 1,
        "createdAt": "2018-01-09T07:56:53.743Z",
        "updatedAt": "2018-01-09T07:56:53.743Z"
      }
    }
    

    This endpoint creates a new Work Order.

    HTTP Request

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

    Request Body

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

    Parameter Type Required Description
    title String true
    description String false
    priority Number false 0,1,2,3. 0 being lowest
    dueDate Number false timestamp in milliseconds
    asset String false id of asset
    location String false id of location
    assignedToUser String false id of user whom the Work Order is assigned

    Events After Work Order is Created

    If the API returns with status 200:

    1. If your account has a Zapier integration enabled, data will be sent to Zapier for the new Work Order trigger.

    2. If a user is assigned to the work order, an email will be sent to him or her. If it is assigned to no one, emails will be sent to admins.

    Get All Work Orders

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

    The above command returns JSON structured like this:

    {
      "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",
          "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": {...},
          "publicRequesterEmail": "test@onupkeep.com",
          "createdAt": "2017-12-06T19:23:09.162Z",
          "updatedAt": "2017-12-08T18:41:44.335Z"
        }
      ]
    }
    

    This endpoint retrieves all work orders for your account.

    HTTP Request

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

    Query Parameters

    Parameter Default Description
    title undefined If set, only work orders with this title will be included.
    isComplete undefined If set to "0", the result will only include work orders that have not been completed. If set to "1", the result will only include work orders that have been completed.
    status undefined If set, the work orders fetched will be of the specified status only(allowed values 'open','onHold','inProgress', 'complete')
    asset undefined (ID) If set, only work orders associated with this asset will be included.
    location undefined (ID) If set, only work orders belonging to this location will be included.
    category undefined If set, only work orders with this category will be included.
    assignedToUser undefined (ID) If set, only work orders assigned to this user will be included.
    assignedByUser undefined (ID) If set, only work orders assigned by this user will be included.
    publicRequesterEmail undefined If set, only work orders created by this email on the public request portal will be included.
    offset undefined (Number) offset for pagination.
    limit undefined (Number) limit for pagination.
    includes undefined (Array) send 'asset', 'location', 'assignedToUser', 'team' to expand respective object.
    orderBy createdAt DESC (String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt', 'dueDate', 'dateCompleted'. Second value: "ASC" or "DESC".

    Get a Specific Work Order

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

    The above command returns JSON structured like this:

    {
      "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",
          "location": "Mkr457Gkk3",
          "team": "PD6I909nLS",
          "category": "Electrical",
          "assignedByUser": "5ZXaLRZ40I",
          "assignedByUsername": "test@onupkeep.com",
          "priority": "1",
          "formItems": [
            "YChe6OjzHC",
            "FuJBoOf8Di",
            "e2iFG6t7I9"
          ],
          "image": {
             "__type": "File",
             "name": "dfimg_request2.jpg",
             "url": "https://demo-api-upkeep.s3.amazonaws.com/dfimg_request2.jpg"
          },
          "image2": {...},
          "image3": {...},
          "image4": {...},
          "image5": {...},
          "arrayOfUpdateItems": [
            "dGCW3cSjWv",
            "SPRXIDJDZ1"
          ],
          "parts": [
            "sDmjnbbpAL",
            "QhWwJbfGb4"
          ],
          "respectivePartQuantityUsed": [
            5,
            1
          ],
          "additionalUsers": [
            "vk6BHzQVCX",
            "lv6FZopMhz"
          ],
          "publicRequesterEmail": "test@onupkeep.com",
          "createdAt": "2017-12-06T19:23:09.162Z",
          "updatedAt": "2017-12-08T18:41:44.335Z"
        }
    }
    

    This endpoint retrieves a specific work order.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the work order to retrieve

    Query Parameters

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

    Update a Specific Work Order

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
          "id": "HW2I379ErS",
          "workOrderNo": "014",
          "title": "Repair Sink",
          "description": "Warp drive has been malfunctioning, check the coils that generate the warp field.",
          "status": "onHold",
          "dueDate": "2017-12-06T19:23:09.162Z",
          "dateCompleted": "2017-12-06T19:23:09.162Z",
          "assignedToUser": "5ZXaLRZ40I",
          "assignedToUsername": "5ZXaLRZ40I",
          "completedByUser": "5ZXaLRZ40I",
          "asset": "kW6I379ELS",
          "location": "Mkr457Gkk3",
          "team": "PD6I909nLS",
          "category": "Electrical",
          "assignedByUser": "5ZXaLRZ40I",
          "assignedByUsername": "test@onupkeep.com",
          "priority": "1",
          "image": {
             "__type": "File",
             "name": "dfimg_request2.jpg",
             "url": "https://demo-api-upkeep.s3.amazonaws.com/dfimg_request2.jpg"
          },
          "image2": {...},
          "image3": {...},
          "image4": {...},
          "image5": {...},
          "publicRequesterEmail": "test@onupkeep.com",
          "createdAt": "2017-12-06T19:23:09.162Z",
          "updatedAt": "2017-12-08T18:41:44.335Z"
        }
    }
    

    This endpoint updates a specific Work Order.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the Work Order to update

    Request Body

    Provide any of the below fields of the part in the payload to update those specific fields. Null values are allowed to erase the value unless otherwise stated.

    Parameter Type Description
    title String
    description String
    status String Allowed values- open, onHold, inProgress, complete
    dueDate Number timestamp in milliseconds

    Events After Work Order is Updated

    If the API returns with status 200:

    1. If the work order status is updated and your account has a Zapier integration enabled, data will be sent to Zapier for the status change trigger.

    Delete a Specific Work Order

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "1 work order deleted"
    }
    

    This endpoint deletes a specific work order.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the work order to delete

    Preventative Maintenance

    Create a Preventative Maintenance Work Order

    curl "https://api.onupkeep.com/api/v2/preventative-maintenance/"
      -H "Session-Token: session_token_here"
      -X POST
      -d title="Check Oil"
      -d description="Confirm the tractor is optimal"
      -d priority=1
      -d recurringSchedule="daily"
      -d dueDate=1515482422310
      -d endDueDate=1517279400000
      -d asset="gDK45aHe12"
      -d location="MD565aHenL"
      -d assignedToUser="lv6FZopMhz"
    
    

    The above command returns JSON structured like this:

    {
      "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",
        "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
    assignedToUser String false id of user whom the Work Order is assigned

    Events After Work Order is Created

    If the API returns with status 200:

    1. If your account has a Zapier integration enabled, data will be sent to Zapier for the new Work Order trigger.

    2. If a user is assigned to the work order, an email will be sent to him or her. If it is assigned to no one, emails will be sent to admins.

    Get All Preventative Maintenance Work Orders

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

    The above command returns JSON structured like this:

    {
      "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",
          "assignedByUser": "lv6FZopMhz",
          "assignedByUsername": "test@onupkeep.com",
          "priority": 1,
          "description": "Confirm the tractor is optimal",
          "createdAt": "2018-01-09T07:56:53.743Z",
          "updatedAt": "2018-01-09T07:56:53.743Z"
        }
      ]
    }
    

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

    HTTP Request

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

    Query Parameters

    Parameter Default Description
    title undefined If set, only work orders with this title will be included.
    asset undefined (ID) If set, only work orders associated with this asset will be included.
    location undefined (ID) If set, only work orders belonging to this location will be included.
    recurringSchedule undefined If set, only work orders with this repeating schedule will be included.
    assignedToUser undefined (ID) If set, only work orders assigned to this user will be included.
    assignedByUser undefined (ID) If set, only work orders assigned by this user will be included.
    offset undefined (Number) offset for pagination.
    limit undefined (Number) limit for pagination.
    includes undefined (Array) send 'asset', 'location', 'assignedToUser', 'team' to expand respective object.
    orderBy createdAt DESC (String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt', 'dueDate'. Second value: "ASC" or "DESC".

    Get a Specific Preventative Maintenance Work Order

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

    The above command returns JSON structured like this:

    {
      "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",
        "assignedToUsername": "test@onupkeep.com",
        "asset": "knyWfDnXWo",
        "location": "cXRAu708NU",
        "assignedByUser": "lv6FZopMhz",
        "assignedByUsername": "test@onupkeep.com",
        "priority": 1,
        "description": "Confirm the tractor is optimal",
        "createdAt": "2018-01-09T07:56:53.743Z",
        "updatedAt": "2018-01-09T07:56:53.743Z"
      }
    }
    

    This endpoint retrieves a specific work order.

    HTTP Request

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

    URL Parameters

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

    Query Parameters

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

    Delete a Specific Preventative Maintenance Work Order

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "message": "1 work order deleted"
    }
    

    This endpoint deletes a specific work order.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the work order to delete

    Work Order Schedule

    Get The Schedule of Preventative Maintenance Work Orders

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

    The above command returns JSON structured like this:

    {
      "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",
          "assignedByUser": "lv6FZopMhz",
          "assignedByUsername": "test@onupkeep.com",
          "priority": 1,
          "description": "Confirm the tractor is optimal",
          "createdAt": "2018-01-09T07:56:53.743Z",
          "updatedAt": "2018-01-09T07:56:53.743Z"
        }
      ]
    }
    

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

    HTTP Request

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

    Query Parameters

    Parameter Default Description
    utcOffset 0 Difference between UTC and your time-zone in minutes.
    title undefined If set, only work orders with this title will be included.
    asset undefined (ID) If set, only work orders associated with this asset will be included.
    location undefined (ID) If set, only work orders belonging to this location will be included.
    category undefined If set, only work orders with this category will be included.
    assignedToUser undefined (ID) If set, only work orders assigned to this user will be included.
    assignedByUser undefined (ID) If set, only work orders assigned by this user will be included.
    includes undefined (Array) send 'asset', 'location', 'assignedToUser', 'team' to expand respective object.

    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"
    

    The above command returns JSON structured like this:

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "results": [
        {
          "id": "WEeI86SMu4",
          "name": "Mileage",
          "units": "KMPL",
          "frequency": 7,
          "createdByUser": "lv6FZopMhz",
          "location": "M75FZevseo",
          "asset": "KXi4CS5Nft",
          "createdAt": "2018-01-30T10:19:24.141Z",
          "updatedAt": "2018-01-30T10:19:24.141Z"
        }
      ]
    }
    

    This endpoint retrieves all meters for your account.

    HTTP Request

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

    Query Parameters

    Parameter Default Description
    name undefined If set the result will only include meters with that name.
    asset undefined (ID) If set the result will only include meters with that asset.
    location undefined (ID) If set the result will only include meters with that location.
    offset undefined (Number) offset for pagination.
    limit undefined (Number) limit for pagination.
    includes undefined (Array) send 'asset', 'location', 'lastReading' to expand respective object.
    orderBy createdAt DESC (String) Sorting for pagination. First value is the field: 'createdAt', 'updatedAt'. Second value: "ASC" or "DESC".

    Get a Specific Meter

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "id": "WEeI86SMu4",
        "name": "Mileage",
        "units": "KMPL",
        "frequency": 7,
        "createdByUser": "lv6FZopMhz",
        "location": "M75FZevseo",
        "asset": "KXi4CS5Nft",
        "lastReading": "IwOZ7ulcv5",
        "createdAt": "2018-01-30T10:19:24.141Z",
        "updatedAt": "2018-01-30T10:19:24.141Z"
      }
    }
    

    This endpoint retrieves a specific meter.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the meter to retrieve

    Query Parameters

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

    Update a Specific Meter

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

    The above command returns JSON structured like this:

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

    The above command returns JSON structured like this:

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

    The above command returns JSON structured like this:

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

    This adds a reading to meter.

    HTTP Request

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

    Request Body

    Provide any of the below required fields and optional fields for the meter reading.

    Parameter Type Required Description
    value Number true

    URL Parameters

    Parameter Description
    meterID The ID of the meter

    Events After Reading is Added

    If the API returns with status 200:

    1. If a Work Order trigger is set via meter notification, Specified Work Order will be created if conditions are met.

    Get All Readings for a Meter

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "results": [
        {
          "id": "iGIkXrVtGS",
          "date": "2018-01-30T10:05:20.402Z",
          "meter": "GvWe2sCUkY",
          "value": 1,
          "createdByUser": "lv6FZopMhz",
          "createdAt": "2018-01-30T10:05:20.425Z",
          "updatedAt": "2018-01-30T10:05:20.425Z"
        }
      ]
    }
    

    This endpoint retrieves all readings for a meter.

    HTTP Request

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

    Query Parameters

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

    URL Parameters

    Parameter Description
    meterID The ID of the meter

    Create a Meter Notification

    curl "https://api.onupkeep.com/api/v2/meters/<meterID>/notifications"
      -H "Session-Token: session_token_here"
      -X POST
      -d title="Reading less than 100"
      -d description="Triggers when reading is less than 100"
      -d triggerValue=100
      -d triggerFrequency="ONE_TIME_IS_LESS_THAN"
      -d assignedToUser="qTmhmORg85"
    

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "id": "LNbrsMFfMy",
        "title": "Reading less than 100",
        "triggerFrequency": "ONE_TIME_IS_LESS_THAN",
        "description": "Triggers when reading is less than 100",
        "triggerValue": 100,
        "assignedToUser": "qTmhmORg85",
        "createdByUser": "lv6FZopMhz",
        "createdAt": "2018-02-05T05:06:24.570Z",
        "updatedAt": "2018-02-05T05:06:24.570Z"
      }
    }
    

    This endpoint creates a new meter notification for particular meter.

    HTTP Request

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

    Request Body

    Provide any of the below required fields and optional fields for meter notifications.

    Parameter Type Required Description
    title String true Title of Work Order to create on trigger.
    triggerValue Number true Value to be compared for trigger.
    triggerFrequency String true Comparison operator for trigger. Allowed values- 'ONE_TIME_IS_GREATER_THAN', 'ONE_TIME_IS_LESS_THAN', 'EVERY_TIME_IS_LESS_THAN', 'EVERY_TIME_IS_GREATER_THAN', 'EVERY_TIME_IS_EQUAL_TO', 'EVERY_TIME_REACHES'.
    description String false Work Order description.
    assignedToUser String false (ID) of User assigned.

    URL Parameters

    Parameter Description
    meterID The ID of the meter

    Get All Meter Notifications

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "results": [
        {
          "id": "LNbrsMFfMy",
          "title": "Reading less than 100",
          "triggerFrequency": "ONE_TIME_IS_LESS_THAN",
          "description": "Triggers when reading is less than 100",
          "triggerValue": 100,
          "assignedToUser": "qTmhmORg85",
          "createdByUser": "lv6FZopMhz",
          "createdAt": "2018-02-05T05:06:24.570Z",
          "updatedAt": "2018-02-05T05:06:24.570Z"
        }
      ]
    }
    

    This endpoint retrieves all notifications for particular meter.

    HTTP Request

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

    Query Parameters

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

    URL Parameters

    Parameter Description
    meterID The ID of the meter

    Get a Specific Meter Notification

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "id": "LNbrsMFfMy",
        "title": "Reading less than 100",
        "triggerFrequency": "ONE_TIME_IS_LESS_THAN",
        "description": "Triggers when reading is less than 100",
        "triggerValue": 100,
        "assignedToUser": "qTmhmORg85",
        "createdByUser": "lv6FZopMhz",
        "createdAt": "2018-02-05T05:06:24.570Z",
        "updatedAt": "2018-02-05T05:06:24.570Z"
      }
    }
    

    This endpoint retrieves a specific meter notification.

    HTTP Request

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

    URL Parameters

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

    Query Parameters

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

    Update a Specific Meter Notification

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

    The above command returns JSON structured like this:

    {
      "success": true,
      "result": {
        "id": "LNbrsMFfMy",
        "title": "Reading less than 100",
        "triggerFrequency": "ONE_TIME_IS_LESS_THAN",
        "description": "Triggers when reading is less than 100",
        "triggerValue": 100,
        "assignedToUser": "MtmhmKKg56",
        "createdByUser": "lv6FZopMhz",
        "createdAt": "2018-02-05T05:06:24.570Z",
        "updatedAt": "2018-02-05T05:06:24.570Z"
      }
    }
    

    This endpoint updates a specific meter notification.

    HTTP Request

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

    URL Parameters

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

    Request Body

    Provide any of the below fields of the asset in the payload to update those specific fields. Null values are allowed to erase the value unless otherwise stated.

    Parameter Type Required Description
    title String false Title of Work Order to create on trigger.
    triggerValue Number false Value to be compared for trigger.
    triggerFrequency String false Comparison operator for trigger. Allowed values- 'ONE_TIME_IS_GREATER_THAN', 'ONE_TIME_IS_LESS_THAN', 'EVERY_TIME_IS_LESS_THAN', 'EVERY_TIME_IS_GREATER_THAN', 'EVERY_TIME_IS_EQUAL_TO', 'EVERY_TIME_REACHES'.
    description String false Work Order description.
    assignedToUser String false (ID) of User assigned.

    Delete a Specific Meter Notification

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

    The above command returns JSON structured like this:

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

    Common Use Cases

    The work-order API returns all single work orders for your UpKeep account. A common use case for UpKeep’s APIs are to utilize the fetch work order API with specific filters to run your own reports. For example, if you wanted to generate a report on a specific set of work orders, you may want to use the filter where userAssignedTo equals Tom to pull all work orders. From the response, you’ll be able to pull a report and aggregate things like the total time, cost, and average time to completion for this group of individuals.

    You may also want to generate a report for all preventative work orders. To do this you’ll want to use our preventative maintenance API to find all of the root preventative maintenance work orders. To find the schedules of the preventative maintenance work orders, you’ll use the ID of the root PM work orders and pass the root preventative maintenance work order into the “get work order schedule” API. With that data, you will receive an array of all of the PMs that match the criteria so you can do aggregate reporting on PMs.

    A common use case for the parts API may be to update and increase the quantity of a given part after you have received new inventory. This could be a trigger set up from another system that tracks when new inventory has arrived at your facility.

    A common use case for the asset API may be to utilize your tracking system to update the asset’s location. You can do that utilizing the “update a specific asset” API. First, you may want to utilize the “get all locations” API to find the ID of the correct location and pass in the location ID into the “update asset” API to update the asset’s location.

    A common use case for utilizing the requests API would be to set up integrations with your company’s work order request system. You may want to create UpKeep requests through our API without needing to manually enter the same information in.

    Use the users API, to add, remove or update a specific user from your UpKeep account.

    Errors

    The UpKeep API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- See the accompanying message.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- The object requested is hidden for administrators only.
    404 Not Found -- The specified object could not be found.
    405 Method Not Allowed -- You tried to access a object with an invalid method.
    406 Not Acceptable -- You requested a format that isn't json.
    429 Too Many Requests -- You're requesting too many objects! Slow down!
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

    If the API Endpoint returns an error of status 500 or 400, the body of the request will contain a message property. Below are common messages:

    Message Meaning
    {field} cannot be null The {field} in your POST or PATCH request must contain a value.
    invalid filter key: {field} The {field} in your GET request does not exist.
    {field} not in schema The {field} with a value in your POST request does not exist.
    {field} is not allowed to be set! The {field} in your PATCH request cannot be edited.

    For any other errors, please contact info@onupkeep.com