Staff Tools
Manage staff members, create and update shifts, view schedules, perform bulk shift operations, and ask staff when they can work.
Required scope: staff:read for read tools, staff:write for write tools
Tools Overview
| Tool | Description | Read-only? |
|---|---|---|
list_staff | List staff members | Yes |
get_staff | Get staff member details | Yes |
get_staff_schedule | Get staff shifts for a date | Yes |
get_shift_history | View the audit trail for a shift | Yes |
create_staff | Create a new staff member | No |
update_staff | Update a staff member | No |
create_staff_shift | Create a new shift | No |
update_staff_shift | Update an existing shift | No |
delete_staff_shift | Delete a shift | No |
repeat_staff_shift | Copy a shift onto one or more target dates | No |
move_staff_shift | Move a shift to a new date, time, or staff member | No |
bulk_delete_shifts | Delete every shift within a date range | No |
bulk_update_shifts | Change start/end time on every shift in a date range | No |
mark_shifts_open | Clear staff assignments and mark shifts as open | No |
get_staff_availability | Get when a staff member can work, and their days off waiting for an OK | Yes |
set_staff_availability | Set a staff member's usual week, specific dates, or both | No |
send_staff_availability_link | Ask one or more staff members for their availability | No |
get_training_progress | Who has finished their training, and each person's next lesson | Yes |
get_role_training | The lessons each job role gets, and how many people finished | Yes |
change_role_training | Add or remove a job role's lessons, or go back to Dash's picks | No |
list_staff
List staff members.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
search | string | No | Search by name |
limit | integer | No | Number of results (default 10) |
get_staff
Get staff member details.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
staff_id | integer | Yes | The staff ID |
get_staff_schedule
Get staff shifts for a date, optionally filtered by staff member.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
date | string | No | Date to get shifts for |
staff_id | integer | No | Filter by specific staff member |
staff_search | string | No | Search by staff name |
get_shift_history
View the audit trail for a shift: who created it, every edit, and status changes.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
shift_id | integer | Yes | The shift ID |
Response Fields
Returns shift_id and a logs array. Each log entry includes the user who made the change, the field(s) changed, old and new values, and a timestamp.
create_staff
Create a new staff member.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
first_name | string | Yes | First name |
last_name | string | Yes | Last name |
email | string | No | Email address |
phone | string | No | Phone number |
employment_type | string | No | Employment type: full_time, part_time, casual, contractor |
user_confirmed | boolean | Yes | Must be true to create |
update_staff
Update a staff member.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
staff_id | integer | Yes | The staff member ID |
first_name | string | No | New first name |
last_name | string | No | New last name |
email | string | No | New email |
phone | string | No | New phone |
status | string | No | New status: active, inactive |
user_confirmed | boolean | Yes | Must be true to update |
create_staff_shift
Create a new staff shift.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
staff_id | integer | Yes | The staff member ID |
shift_date | string | Yes | Date of the shift (YYYY-MM-DD) |
start_time | string | Yes | Shift start time (HH:MM, 24-hour format) |
end_time | string | Yes | Shift end time (HH:MM, 24-hour format) |
location_id | integer | No | Location ID |
break_type | string | No | Break type: Meal Break, Rest Break, Other |
break_time | string | No | Break duration: 15 min, 30 min, 45 min, 1 hour |
break_payment | string | No | Break payment: Paid, Unpaid |
notes | string | No | Shift notes |
user_confirmed | boolean | Yes | Must be true to create |
update_staff_shift
Update an existing staff shift.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
shift_id | integer | Yes | The shift ID |
start_time | string | No | New start time (HH:MM, 24-hour format) |
end_time | string | No | New end time (HH:MM, 24-hour format) |
break_type | string | No | Break type: Meal Break, Rest Break, Other |
break_time | string | No | Break duration: 15 min, 30 min, 45 min, 1 hour |
break_payment | string | No | Break payment: Paid, Unpaid |
remove_break | boolean | No | Set to true to remove the break |
notes | string | No | Updated notes |
user_confirmed | boolean | Yes | Must be true to update |
delete_staff_shift
Delete a staff shift.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
shift_id | integer | Yes | The shift ID to delete |
user_confirmed | boolean | Yes | Must be true to delete |
repeat_staff_shift
Copy a shift onto one or more target dates, keeping the same staff member and times.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
shift_id | integer | Yes | The shift ID to repeat |
dates | array of strings | Yes | Target dates in YYYY-MM-DD format |
Response Fields
Returns source_shift_id, created_shift_ids (array of new shift IDs), and count.
move_staff_shift
Move a shift to a new date, time, or staff member — the drag-and-drop equivalent.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
shift_id | integer | Yes | The shift ID to move |
shift_date | string | Yes | New shift date (YYYY-MM-DD) |
start_time | string | Yes | New start time (HH:MM) |
end_time | string | Yes | New end time (HH:MM) |
staff_id | integer | No | New staff ID. Omit to leave the assignment unchanged or to make the shift open. |
Response Fields
Returns success and the updated shift object including staff and location.
bulk_delete_shifts
Delete every shift within a date range. This is destructive and requires explicit user confirmation.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Start of range (YYYY-MM-DD) |
end_date | string | Yes | End of range (YYYY-MM-DD) |
user_confirmed | boolean | Yes | Must be true — user must confirm deletion |
Response Fields
Returns success and deleted_count.
bulk_update_shifts
Change start_time or end_time on every shift within a date range. At least one of new_start_time or new_end_time must be provided.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Start of range (YYYY-MM-DD) |
end_date | string | Yes | End of range (YYYY-MM-DD) |
new_start_time | string | No | New start time (HH:MM). Required if new_end_time not given. |
new_end_time | string | No | New end time (HH:MM). Required if new_start_time not given. |
only_unpublished | boolean | No | Default true — only update unpublished/draft shifts. |
Response Fields
Returns success and updated_count.
mark_shifts_open
Clear the staff assignment on every shift within a date range and mark them as OPEN.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Start of range (YYYY-MM-DD) |
end_date | string | Yes | End of range (YYYY-MM-DD) |
Response Fields
Returns success and affected_count.
get_staff_availability
Get a staff member's usual week, their answers for upcoming dates, and any days off they asked for that are still waiting for an OK.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
staff_id | integer | Yes | The staff ID |
Response Fields
Returns staff_id, name, and the availability object
(week, set_by, dates), plus time_off_waiting_for_ok: a list of time_off_id, dates and
reason for each pending day-off request.
set_staff_availability
Set a staff member's usual week, their answers for specific dates, or both. Days left out of week
keep their current hours. Same rules as Update Staff Availability.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
staff_id | integer | Yes | The staff ID |
week | object | No | Keyed by day, monday to sunday. Each day takes on (boolean), start and end (HH:MM, 24-hour). |
dates | array | No | Rows of date (YYYY-MM-DD, required), on, start and end. on: false means they can't work that date. |
Response Fields
Returns success, a message, and the updated availability object.
send_staff_availability_link
Ask one or more staff members when they can work. Each gets their own link by email and, where your account has texting set up, by text. Same rules as Ask Staff for Availability.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
staff_ids | array of integers | Yes | The staff IDs to ask |
kind | string | No | weekly (default) or dates |
from_date | string | For dates | First date to ask about (YYYY-MM-DD) |
to_date | string | For dates | Last date to ask about (YYYY-MM-DD), three months at most after from_date |
reply_by | string | No | Date to answer by (YYYY-MM-DD). Anyone who has not answered gets one reminder the day before. |
email | boolean | No | Send by email. Default true. |
text | boolean | No | Send by text. Default true. |
Response Fields
Returns success, a message such as "Sent to 6 people.", request_id, sent, and not_reached
(names nothing could be sent to).
Related
- Staff REST API - REST API endpoints for staff
- Schedule Tools - Week copy, templates, insights, demand, and understaffing
- Time Off Tools - Manage staff time-off requests
- Settings Tools - View business locations for shift assignment
get_training_progress
How far each active staff member is with their training. The numbers match the Staff list's Training column and Team training.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
staff_id | integer | No | One staff member. Leave out for everyone |
Each person has a status: done, in_progress, not_started, no_login (they cannot log in yet, so they cannot start) or none. See Training progress for the full shape.
get_role_training
Every job role plus "Everyone else" (staff with no job role): its lessons in order with their ids, picked_by (dash or owner), people and finished. No parameters.
change_role_training
Change the lessons a job role gets. Everyone with the role, including new hires, gets the new list. Lessons people already finished stay finished. Needs the staff:write scope.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
role | string | Yes | The job role's name, or Everyone else |
add | string[] | No | Lesson ids or exact titles to add at the end |
remove | string[] | No | Lesson ids or exact titles to take off |
use_dash_picks | boolean | No | true replaces the list with Dash's picks again |
Once changed, the role reads picked_by: owner and Dash no longer replaces its list when the shop starts selling something new.