Upkeep API Docs

Login

Provides you a session token that can be used to make requests as a logged in user.

Endpoint: https://api.onupkeep.com/api/public/login

Method: POST

Content-Type: application/json

Parameters:

  • username - User name of upkeep account.
  • password - Password of upkeep account.

On success the session token will be returned.

                    {
                        "sessionToken": "r:ee091a894626a62d9dc09073884d91ba"
                    }
                

Logout

Invalidates the session token.

Endpoint: https://api.onupkeep.com/api/public/logout

Method: POST

Content-Type: application/json

Parameters:

  • sessionToken - The session token obtained from login.

On success success message message will be returned in message key.

                    {
                        "message": "Successfully logged out"
                    }
                

Work Order Status Change

Changes status of your upkeep work order.

Endpoint: https://api.onupkeep.com/api/public/workorder-status

Content-Type: application/json

Method: POST

Parameters:

  • sessionToken - The session token obtained from login.
  • id - Id of the work order whose status is to be changed.
  • status - New status of the work order allowed values are- 'open', 'complete', 'onHold', 'inProgress'.

On success success message message will be returned in message key. For example if the request was to change status to onHold.

                    {
                        "message": "status changed to onHold"
                    }
                

Work Order List

Provides all the work orders of user's company.

Endpoint: https://api.onupkeep.com/api/public/workorders

Method: POST

Content-Type: application/json

Parameters:

  • sessionToken - The session token obtained from login.
  • offset - (Optional) Integer representing offset value for pagination.
  • limit - (Optional) Integer representing limit value for pagination.
  • filters - (Optional) Array of objects for filters. Each object will have type and value keys
    type- Workorder field to filter on eg 'status'
    value- Value of field to filter eg.
    "filters": [{"type": "status", "value": "complete"}]
Note- filters are currently allowed on 'status' field only and the allowed values are- 'open', 'complete', 'onHold', 'inProgress'.

On success array of work order object will be returned having the keys- id, status, title, description, dueDate, endDueDate, dateCompleted, completedBy,completedById, createdAt, workOrderNo, category, time, cost, assignedBy, assignedById, assignedTo, assignedToId, asset, assetId, location,locationId, team, teamId, requestedBy, requestedById, formItems(array of objects having keys formName, formValue if set) (keys not set will be excluded). Response will be similar to.

                    [
                         {
                            "id": "wfhn43LMh3",
                            "status": "open",
                            "title": "Repair sink",
                            "dueDate": "2016-10-22T01:00:00.000Z",
                            "createdAt": "2016-10-20T10:17:13.712Z",
                            "updatedAt": "2016-10-20T10:17:13.712Z",
                            "endDueDate": "2016-10-20T10:17:13.712Z",
                            "dateCompleted": "2016-10-20T10:17:13.712Z",
                            "workOrderNo": "150",
                            "assignedBy": "abc@xyz.com",
                            "assignedById": "LfGn43LMh3",
                            "assignedTo": "def@xyz.com",
                            "assignedToId": "Lhhn43LMh3",
                            "completedBy": "def@xyz.com",
                            "completedById": "Nfhnt3LMh3",
                            "asset": "printer",
                            "assetId": "gHhn43LMh3",
                            "location": "New York",
                            "locationId": "Kfhn03LMh3",
                            "category": "Damage",
                            "cost": "100",
                            "time": "30",
                            "team": "Hardware Group",
                            "teamId": "Prfhn43LML",
                            "requestedBy": "ghi@xyz.com",
                            "requestedById": "FfhnFFLMh3",
                            "formItems": [
                                            {
                                                "formName": "English",
                                                "formValue": "87"
                                            },
                                            {
                                                "formName": "Math",
                                                "formValue": "88"
                                            }
                                          ]

                          }
                          ...
                    ]
                

Assets list

Fetches list of Asset items.

Endpoint: https://api.onupkeep.com/api/public/assets

Method: POST

Content-Type: application/json

Parameters:

  • sessionToken - The session token obtained from login.
  • offset - (Optional) Integer representing offset value for pagination.
  • limit - (Optional) Integer representing limit value for pagination.

On success array of asset objects will be returned with key shown below. Any keys with unset value will be skipped.

                    [
                        {
                            "id": "OTHNmL0szz",
                            "location": {
                                "id": "oo8lyqIDG3",
                                "name": "delhi",
                                "address": "Delhi, India",
                                "longitude": 77.22739580000007,
                                "latitude": 28.6618976
                                },
                            "name": "Printer",
                            "model": "JGT Laser 23",
                            "barcodeSerial": "Per patch mx",
                            "parentAssetId": "uPScwR46ra",
                            "description": "Laser printer",
                            "isActive": true,
                            "additionalInformation": "Works fine"
                        }

                        ...
                    ]
                

Fetch particular asset

Fetches particular asset by id.

Endpoint: https://api.onupkeep.com/api/public/assets/:id

Method: POST

Content-Type: application/json

Parameters:

  • sessionToken - The session token obtained from login.

For example to fetch asset with id OTHNmL0szz call will be made to https://api.onupkeep.com/api/public/assets/OTHNmL0szz .On success asset object will be returned with key shown below. Any keys with unset value will be skipped.

                    {
                            "id": "OTHNmL0szz",
                            "location": {
                                "id": "oo8lyqIDG3",
                                "name": "delhi",
                                "address": "Delhi, India",
                                "longitude": 77.22739580000007,
                                "latitude": 28.6618976
                                },
                            "name": "Printer",
                            "model": "JGT Laser 23",
                            "barcodeSerial": "Per patch mx",
                            "parentAssetId": "uPScwR46ra",
                            "description": "Laser printer",
                            "isActive": true,
                            "additionalInformation": "Works fine"
                        }
                

Locations list

Fetches list of location items.

Endpoint: https://api.onupkeep.com/api/public/locations

Method: POST

Content-Type: application/json

Parameters:

  • sessionToken - The session token obtained from login.
  • offset - (Optional) Integer representing offset value for pagination.
  • limit - (Optional) Integer representing limit value for pagination.

On success array of location objects will be returned with key shown below. Any keys with unset value will be skipped.

                    [
                        {
                            "id": "oo8lyqIDG3",
                            "name": "delhi",
                            "address": "Delhi, India",
                            "longitude": 77.22739580000007,
                            "latitude": 28.6618976
                        }

                        ...
                    ]
                

Fetch particular location

Fetches particular location by id.

Endpoint: https://api.onupkeep.com/api/public/locations/:id

Method: POST

Content-Type: application/json

Parameters:

  • sessionToken - The session token obtained from login.

For example to fetch location with id oo8lyqIDG3 call will be made to https://api.onupkeep.com/api/public/locations/oo8lyqIDG3 .On success asset object will be returned with key shown below. Any keys with unset value will be skipped.

                    {
                            "id": "oo8lyqIDG3",
                            "name": "delhi",
                            "address": "Delhi, India",
                            "longitude": 77.22739580000007,
                            "latitude": 28.6618976
                        }
                

Work Order Creation

Creates new work order.

Endpoint: https://api.onupkeep.com/api/public/workorder

Method: POST

Content-Type: application/json

Parameters:

  • sessionToken - The session token obtained from login.
  • title - String representing the title of the work order.
  • additionalInfo - (Optional) String representing the additional details of the work order.
  • priority - (Optional) Integer representing the priority of the work order allowed values-0,1,2,3. 0 is default.
  • dueDate - (Optional) Integer representing the timestamp ie milli-seconds(not seconds) passed since Jan 01 1970 UTC.
  • assetId - (Optional) Id of the asset.
  • locationId - (Optional) Id of the location.
  • userAssignedId - (Optional) Id of user who has been assigned this work order.

On success the id(id of the workorder created) and workOrderNo(workorder serial number) will be returned.

                    {
                        "id": "MC6CwMlBWL"
                        "workOrderNo": "165"
                    }
                

Work Order Request Creation (Without Login)

Creates new workorder request.

Endpoint: https://api.onupkeep.com/api/public/request

Method: POST

Content-Type: application/json

Parameters:

  • emailAddress - Email id of the person requesting.
  • roleId - Role id of the company/firm/facility.
  • title - String representing the title of the work order request.
  • additionalInfo - (Optional) String representing the additional details of the work order.

On success the id(id of the workorder request created) and title(title of work order) request will be returned.


                    {
                        "id": "u6h3J4iaIZ",
                        "title": "fix system"
                    }
                    

Error Format

All the error will have code and message

                    {
                        "code": 400
                        "message": "invalid session token"
                    }