Deputy

Deputy

This connector reads and updates a Deputy install through its API (https://<install>.<region>.deputy.com/api/v1): employees, locations and areas, rosters (shifts), timesheets, leave, unavailability, memos and any other record through Deputy's resource query API.

Personal data: employee records hold names, dates of birth, contact details, addresses and pay data. Read only what the task needs.

Setup (5 minutes, needs a Deputy system administrator)

1. Note your install address from the browser bar when logged in, e.g. mycompany.au.deputy.com (regions: au, eu, uk, na for the US). Put it into DEPUTY_HOST without https://.
2. Open https://<your install address>/exec/devapp/oauth_clients, add an OAuth client (name and any description; the client id itself is not used), then click Get an Access Token.
3. Copy the permanent token at once (it is shown only once) into DEPUTY_ACCESS_TOKEN. It works only on this install and acts as the user who created it, with that user's permissions; a system administrator sees every location. deputy_get_me is the install check.

Words: Deputy calls a location (workplace) a Company, an area (department) an OperationalUnit, a shift a Roster and actual worked time a Timesheet. A leave type is a LeaveRules record.

Workflow

• Who am I: deputy_get_me. The token user's own data: deputy_get_my_rosters, deputy_get_my_timesheets, deputy_get_my_leave, deputy_get_my_unavailability, deputy_get_my_locations, deputy_get_my_colleagues.
• Structure: deputy_list_locations (ids are the location ids), deputy_list_areas (each area belongs to a location; shifts and timesheets use area ids).
• People: deputy_list_employees, deputy_get_employee, deputy_query_employees for filters, deputy_get_employee_shift_status for who is working now.
• Schedule: deputy_list_rosters covers 12 hours back to 36 hours ahead; deputy_query_rosters for any period (filter on Date, Employee, OperationalUnit). To plan: deputy_save_shift (new or, with roster_id, update), deputy_copy_rosters (repeat last week), deputy_publish_rosters (choose the notification).
• Time: deputy_query_timesheets, deputy_get_timesheet. Clock on and off: deputy_start_timesheet, deputy_pause_timesheet, deputy_end_timesheet. Fix or add a past timesheet: deputy_save_timesheet. Approve for payroll: deputy_approve_timesheet (approvals of time).
• Leave: deputy_query_leave, deputy_get_employee_leave; leave types with deputy_query_resource and object LeaveRules. Book with deputy_add_leave; approve, decline or cancel with deputy_update_leave (status 1, 2 or 3).
• Availability: deputy_get_employee_unavailability, deputy_query_availability, deputy_add_unavailability.
• Employees: deputy_add_employee, deputy_update_employee, deputy_invite_employee, deputy_terminate_employee (reversible) and deputy_reactivate_employee. Manager notes: deputy_post_journal. News feed: deputy_post_memo.
• Anything else (teams, public holidays, events, training, custom fields, sales data, pay periods): deputy_get_resource_info lists an object's fields, deputy_query_resource searches it, deputy_get_resource reads one record.

Switched off at install: deputy_delete_employee, deputy_discard_rosters and deputy_discard_timesheet; they cannot be undone, so an admin switches them on when the team needs them.

Query tools (deputy_query_* and deputy_query_resource) send POST but only read. Body: search with clauses {"s1":{"field":"Date","type":"ge","data":"2026-11-01"},"s2":{"field":"Date","type":"le","data":"2026-11-07"}} (all must match; operators eq, ne, gt, ge, lt, le, in, not in, starts, contains, is, is not), sort ({"Date":"asc"}), join (["EmployeeObject"]) and paging.

Reading the answers

• Ids are integers. StartTime / EndTime and the start / end inputs are Unix timestamps in seconds; Date fields are local dates of the location (2026-11-03T00:00:00+11:00). Convert with the location's time zone.
• Roster Employee 0 is an open shift; Published false is a draft. Timesheet TimeApproved, PayRuleApproved, Discarded, IsInProgress give the state; TotalTime is hours.
• Leave Status: 0 awaiting approval, 1 approved, 2 declined, 3 cancelled, 4 pay approved.
• Adding or updating a shift answers 200 with an empty body; check with deputy_query_rosters.

Paging: an answer holds at most 500 records. Query tools take max (up to 500) and start (offset); when a page is full, call again with start raised by max. The list tools without paging return everything Deputy allows in one answer.

Errors: 401 means a wrong token or a token of another install, 403 a missing permission of the token's user, 404 a wrong install address or record id, 400 a bad field name in a filter (check deputy_get_resource_info).