Guides

Resource API Overview

Suggest Edits

One of the most powerful features of the Resource API is that the API itself can inform you of what objects may be related to each other in the Deputy install, as well as what data elements make up each item. The Resource API itself is in many ways, the best documentation for the Resource API.

For example by sending an INFO request with the GET method to an endpoint, it will return all the data elements which make up that object. Eg below is the OperationalUnit object

{
    "fields": {
        "Id": "Integer",
        "Creator": "Integer",
        "Created": "DateTime",
        "Modified": "DateTime",
        "Company": "Integer",
        "WorkType": "VarChar",
        "ParentOperationalUnit": "Integer",
        "OperationalUnitName": "VarChar",
        "Active": "Bit",
        "PayrollExportName": "VarChar",
        "Address": "Integer",
        "Contact": "Integer",
        "RosterSortOrder": "Integer",
        "ShowOnRoster": "Bit",
        "Colour": "VarChar",
        "RosterActiveHoursSchedule": "Integer",
        "DailyRosterBudget": "Float",
        "OperationalUnitType": "Integer"
    },
    "joins": {
        "CompanyObject": "Company",
        "ParentOperationalUnitObject": "OperationalUnit",
        "AddressObject": "Address",
        "ContactObject": "Contact",
        "RosterActiveHoursScheduleObject": "Schedule"
    },
    "assocs": {
        "OperationUnit": "ShiftTemplate",
        "EmployeeSalaryOpunits": "EmployeeAgreement",
        "OperationalUnit": "Event",
        "ManagementEmployeeOperationalUnit": "Employee",
        "TrainingModule": "TrainingModule",
        "RosterEmployeeOperationalUnit": "Employee",
        "TaskGroupOpUnit": "TaskGroupSetup"
    },
    "count": 21
}

This was retrieved by sending a GET to https://{install}.{geo}.deputy.com/api/v1/resource/OperationalUnit/INFO

As you can see, it displays a count of the records in the database for this object, as well as what joins can be performed, such as CompanyObject.

Resource API options

There are four main options in the Resource API

  • INFO - This allows you to retrieve what data elements make up an object as well as what joins can be performed
  • QUERY - Which allows you to retrieve objects from the Deputy install
  • BULK - Which as the name implies, allows for bulk uploads of data into the Deputy system for the specified endpoint.
  • DELETE - Allows specific items to be deleted on each resource.

These are accessed by appending the relevant type to the end of the URL. For example to find all information about the Timesheet object in the Resource API you can send a GET request to
https://{install}.{geo}.deputy.com/api/v1/Resource/Timesheet/INFO

Resource API modifiers/filters

When using the QUERY option as part of a Resource API you can include a payload that filters the response. For example you can search a specific time period. Below is a list of the modifiers/filters supported by the Resource API in search.

  • eq - Equals
  • gt - Greater than
  • ge - Greater than or equal to
  • lt - Less than
  • le - Less than or equal to
  • lk - Like (Can put in % characters to match to a pattern)
  • nk - Not like
  • ne - Not equal to
  • in - In a given set of array values
  • nn - Not in a given set of array values
  • is - Is something other than 0 or NULL
  • ns - Not something. Meaning either 0 or NULL

Resource API query options

When using the /QUERY endpoint for the resource API, you have access to a number of options to assist getting the data you want, in a format that you need. Items such as aggregation, pagination, and max results can all be controlled using various parameters in a POST request to the resource query API.

Search - This allows you to specifically target data by using filters on data elements. For example, the below JSON will search for and return all records with an id of 1. It's possible to include multiple search filters by adding "s2", "s3" and so on to the search object.

{"search":{
            "s1":{"field":"Id","data": 1, "type": "eq"}
    }}

You are also able to search into related objects by including a join as well.

{
  "search": {
    "s1": {"field": "Id", "data": 1, "type": "eq" }
  },
  "join": ["TimesheetObject"]
}

Sort - This allows you to sort the response, for example if you wanted to sort the employee records ascending by first name, you would use this query

{
  "search": {
		"sort": {
    	"FirstName: "asc"
  	}
	}

To sort the response in a descending manner, you would set the field name to "desc"

{
	"sort": {
    "FirstName: "desc"
  }
}

Join - Join allows you to add data from related objects in the resource API. For example with the TimesheetPayReturn endpoint you are able to add the Timesheet object as additional data in the response. For a detailed walkthrough on joins check out the Getting Timesheets from Deputy guide.

Assoc - Assoc allows you to add data from associated objects in the resource API. For example if you wanted to include the category data in a response from the Journal resource query endpoint you would use thi payload

{
  "assoc": ["Category"]
	}

Aggr - Aggr allows you to aggregate data results. For example if you want to know how much time was captured in timesheets on a specific date you would use this payload. First it defines the search field as date and the type as an 'equal' matching, before what aggregates should be included in the response.

You can use the following types for aggregation

Sum - The total sum of an item for example hours
Count - The total count of the times a defined element appears
CountDistinct - The total unique count of a defined element. For example, if you wanted to know how many unique dates were returned in a response you might use CountDistinct on the date element.

{"search":{
            "s1":{"field":"Date","data": "2022-05-06", "type": "eq"}
    },
    "aggr": {
        "TotalTime": "sum"
    }}

Group - Group allows you to group data by individual data fields. For example if you wanted to group by operational unit you would run a query like this.

{
   "group":["OperationalUnit"]
 }

Start - The resource API returns 500 records by default and at this time this limit cannot be increased. Instead using the start option in the query, you are able to skip records, allowing you to perform basic pagination on the resource endpoints. If for example you wanted to skip the first fifty records, the payload would look like this.

{
    "start": 50
}

Max - There may be times where you only want a specific amount of data to be returned and this can be achieved using the max modifier. For example if you wanted a maximum response of twenty records, the payload would look like this.

{
    "max": 20
}

Putting it all together

It's possible to combine all these filter and aggregating options into one payload to really pinpoint the data you are looking for. In the below example we are retrieving the total number of hours worked by an employee named Bob for any work area which contains the name bar inside it. We are also using the aggregate function to find the TotalTime worked and grouping by the OperationalUnit.

This example shows just how powerful the resource API can be, and how easy it is to pin down the very specific data your users may be looking for.

{"search":{
           "s1":{"field":"DisplayName",data:"Bob%",type:"lk",join:"EmployeeObject"},
            "s2":{field:"OperationalUnitName",data:"%Bar%",type:"lk",join:"OperationalUnitObject"}} ,
        "join":["EmployeeObject","OperationalUnitObject"],
        "aggr":{"TotalTime":"sum"} ,  // remove this if you don't want grouping
        "group":["OperationalUnit"]   // remove this if you don't want grouping
    }

Resource API objects

Below is a list of the Resource objects available:

  • Address
  • Category
  • Comment
  • Company
  • CompanyPeriod
  • Contact
  • Country
  • CustomAppData
  • CustomField
  • CustomFieldData
  • Employee
  • EmployeeAgreement
  • EmployeeAgreementHistory
  • EmployeeAppraisal
  • EmployeeAvailability
  • EmployeeHistory
  • EmployeePaycycle
  • EmployeePaycycleReturn
  • EmployeeRole
  • EmployeeSAlaryOpunitCosting
  • EmployeeWorkplace
  • EmploymentCondition
  • EmploymentContract
  • EmploymentContractLeaveRules
  • Event
  • Geo
  • Journal
  • Kiosk
  • Leave
  • LeaveAccrual
  • LeavePayLine
  • LeaveRules
  • Memo
  • OperationalUnit
  • PayPeriod
  • PayRules
  • PublicHoliday
  • Roster
  • RosterOpen
  • RosterSwap
  • SalesData
  • Schedule
  • SmsLog
  • State
  • StressProfile
  • SystemUsageBalance
  • SystemUsageTracking
  • Task
  • TaskGroup
  • TaskGroupSetup
  • TaskOpunitConfig
  • TaskSetup
  • Team
  • Timesheet
  • TimesheetPayReturn
  • TrainingModule
  • TrainingRecord
  • Webhook

Updated over 1 year ago