wheniwork_create_shift

Create one shift on a schedule — assigned to a user, or open (user_id 0). Created as a draft unless published is true. Undo by editing it or unpublishing. When I Work: POST /2/shifts.

destructive

Argument	Type	Description
color	string	Hex colour without #, e.g. cc0000.
notes	string	Shift notes shown to the employee.
site_id	integer	Job site for the shift.
user_id	integer	The user to assign. 0 (or omitted on create) makes it an open shift.
end_time*	string	Shift end, date-time with offset.
is_shared	boolean	For an open shift: a shared open shift.
published	boolean	Publish it immediately (default: draft).
break_time	number	Unpaid break length in hours, e.g. 0.5.
start_time*	string	Shift start, date-time with offset, e.g. 2026-10-05T08:00:00-05:00.
location_id*	integer	The schedule (location) the shift belongs to id.
position_id	integer	Position for the shift.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "location_id",
    "start_time",
    "end_time"
  ],
  "properties": {
    "color": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{3,6}$",
      "description": "Hex colour without #, e.g. cc0000."
    },
    "notes": {
      "type": "string",
      "description": "Shift notes shown to the employee."
    },
    "site_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Job site for the shift.",
      "exclusiveMinimum": 0
    },
    "user_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "The user to assign. 0 (or omitted on create) makes it an open shift."
    },
    "end_time": {
      "type": "string",
      "description": "Shift end, date-time with offset."
    },
    "is_shared": {
      "type": "boolean",
      "description": "For an open shift: a shared open shift."
    },
    "published": {
      "type": "boolean",
      "description": "Publish it immediately (default: draft)."
    },
    "break_time": {
      "type": "number",
      "minimum": 0,
      "description": "Unpaid break length in hours, e.g. 0.5."
    },
    "start_time": {
      "type": "string",
      "description": "Shift start, date-time with offset, e.g. 2026-10-05T08:00:00-05:00."
    },
    "location_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "The schedule (location) the shift belongs to id.",
      "exclusiveMinimum": 0
    },
    "position_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Position for the shift.",
      "exclusiveMinimum": 0
    }
  }
}

wheniwork_create_time_off_request

Create a time-off request for a user (default the calling user). It starts pending; cancel it with wheniwork_update_time_off_request (status 1). Get type ids from wheniwork_list_time_off_types. When I Work: POST /2/requests.

destructive

Argument	Type	Description
paid	boolean	Whether it is paid time off.
hours	number	Hours of paid time off to use.
type_id	integer	Time-off type id (Personal, Sick, Holiday...).
user_id	integer	Who is taking time off (default the calling user).
end_time*	string	End of the time off, full date-time.
start_time*	string	Start of the time off, full date-time.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "start_time",
    "end_time"
  ],
  "properties": {
    "paid": {
      "type": "boolean",
      "description": "Whether it is paid time off."
    },
    "hours": {
      "type": "number",
      "minimum": 0,
      "description": "Hours of paid time off to use."
    },
    "type_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Time-off type id (Personal, Sick, Holiday...).",
      "exclusiveMinimum": 0
    },
    "user_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Who is taking time off (default the calling user).",
      "exclusiveMinimum": 0
    },
    "end_time": {
      "type": "string",
      "description": "End of the time off, full date-time."
    },
    "start_time": {
      "type": "string",
      "description": "Start of the time off, full date-time."
    }
  }
}

wheniwork_get_account

Fetch the When I Work account (workplace) the token acts on — company name, plan and settings; for a parent account also its child accounts. A cheap way to confirm the credentials work. When I Work: GET /2/account.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

wheniwork_get_shift

Fetch one shift by id, including its breaks and publish state. When I Work: GET /2/shifts/{id}.

read-only

Argument	Type	Description
shift_id*	integer	The shift id.
include_repeating_shifts_to	string	Also expand the shift's repeating series up to this date. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. "Mon, 05 Oct 2026 08:00:00 -0500").

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "shift_id"
  ],
  "properties": {
    "shift_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "The shift id.",
      "exclusiveMinimum": 0
    },
    "include_repeating_shifts_to": {
      "type": "string",
      "description": "Also expand the shift's repeating series up to this date. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\")."
    }
  }
}

wheniwork_get_time_off_request

Fetch one time-off request by id, with its message thread and users. When I Work: GET /2/requests/{request_id}.

read-only

Argument	Type	Description
request_id*	integer	The time-off request id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "request_id"
  ],
  "properties": {
    "request_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "The time-off request id.",
      "exclusiveMinimum": 0
    }
  }
}

wheniwork_get_user

Fetch one user by id — name, email, role, positions, schedules, wage. When I Work: GET /2/users/{id}.

read-only

Argument	Type	Description
user_id*	integer	The user id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "user_id"
  ],
  "properties": {
    "user_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "The user id.",
      "exclusiveMinimum": 0
    }
  }
}

wheniwork_list_annotations

List schedule annotations — announcements, business-closed days and blackout dates when time off is not allowed. Defaults to today through one year out. When I Work: GET /2/annotations.

read-only

Argument	Type	Description
end_date	string	End of the range (default one year after start). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. "Mon, 05 Oct 2026 08:00:00 -0500").
start_date	string	Start of the range (default the start of today). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. "Mon, 05 Oct 2026 08:00:00 -0500").
no_time_off	boolean	Only annotations that block time off.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "end_date": {
      "type": "string",
      "description": "End of the range (default one year after start). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\")."
    },
    "start_date": {
      "type": "string",
      "description": "Start of the range (default the start of today). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\")."
    },
    "no_time_off": {
      "type": "boolean",
      "description": "Only annotations that block time off."
    }
  }
}

wheniwork_list_availability

List availability events — when people said they can or cannot work, including recurring patterns that fall in the window. Defaults to the caller, from now to two weeks out. When I Work: GET /2/availabilityevents.

read-only

Argument	Type	Description
end	string	End of the window (default two weeks from now). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. "Mon, 05 Oct 2026 08:00:00 -0500").
start	string	Start of the window (default now). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. "Mon, 05 Oct 2026 08:00:00 -0500").
user_id	integer	Whose availability (default the calling user).
include_all	boolean	Everyone's availability, not just one user's — managers only.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "end": {
      "type": "string",
      "description": "End of the window (default two weeks from now). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\")."
    },
    "start": {
      "type": "string",
      "description": "Start of the window (default now). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\")."
    },
    "user_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Whose availability (default the calling user).",
      "exclusiveMinimum": 0
    },
    "include_all": {
      "type": "boolean",
      "description": "Everyone's availability, not just one user's — managers only."
    }
  }
}

wheniwork_list_eligible_users_for_shift

Find who could take an open shift — either an existing shift (shift_id) or a hypothetical one (start, end, position_id and location_id all required). When I Work: GET /2/shifts/eligible.

read-only

Argument	Type	Description
end	string	End of the potential shift (required without shift_id). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. "Mon, 05 Oct 2026 08:00:00 -0500").
start	string	Start of the potential shift (required without shift_id). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. "Mon, 05 Oct 2026 08:00:00 -0500").
shift_id	integer	An existing shift's id.
is_shared	boolean	Whether it is a shared open shift.
location_id	integer	Schedule of the potential shift (required without shift_id).
position_id	integer	Position of the potential shift (required without shift_id).
include_objects	boolean	Include the users' schedules and positions in the output.

Input schema (JSON)

wheniwork_list_locations

List the schedules in the account. The API calls a schedule a "location"; its id is the location_id every shift belongs to. When I Work: GET /2/locations.

read-only

Argument	Type	Description
only_unconfirmed	boolean	Only schedules whose address is unconfirmed.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "only_unconfirmed": {
      "type": "boolean",
      "description": "Only schedules whose address is unconfirmed."
    }
  }
}

wheniwork_list_positions

List the positions (job roles such as Cashier or Dishwasher) in the account. When I Work: GET /2/positions.

read-only

Argument	Type	Description
show_deleted	boolean	Include deleted positions.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "show_deleted": {
      "type": "boolean",
      "description": "Include deleted positions."
    }
  }
}

wheniwork_list_shift_swaps

List shift requests: swaps, drops and alerts, with the shifts and users involved. Status: 0 pending, 1 approved, 2 declined, 3 completed, 4 canceled, 5 expired. Type: 1 swap, 2 drop, 3 alert. start and end must be given together. When I Work: GET /2/swaps.

read-only

Argument	Type	Description
end	string	End of the shift window (give with start). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. "Mon, 05 Oct 2026 08:00:00 -0500").
page	integer	Page of results to load (the response says whether there are `more`).
type	array	One or more types.
limit	integer	Maximum number of results.
start	string	Start of the shift window (give with end). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. "Mon, 05 Oct 2026 08:00:00 -0500").
status	array	One or more statuses.
user_id	array	One or more user ids.
shift_id	array	One or more shift ids.

wheniwork_list_shifts

List scheduled shifts in a time window — who works when, where and in which position — optionally including open shifts and unpublished drafts. Answers "who is on on Friday?" and "what open shifts are left?". When I Work: GET /2/shifts.

read-only

Argument	Type	Description
end	string	End of the window. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. "Mon, 05 Oct 2026 08:00:00 -0500").
limit	integer	Maximum number of results.
start	string	Start of the window. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. "Mon, 05 Oct 2026 08:00:00 -0500").
deleted	boolean	Also return deleted_ids: shifts deleted in the window.
user_id	integer	Only this user's shifts.
location_id	array	One or more schedule (location) ids.
unpublished	boolean	Include unpublished (draft) shifts — supervisor or above.
include_open	boolean	Include open (unassigned) shifts from the user's schedules.

wheniwork_list_time_off_requests

List time-off requests in a date range, with the requesting users. Status: 0 pending, 1 canceled, 2 accepted, 3 expired, 4 denied. When I Work: GET /2/requests.

read-only

Argument	Type	Description
end	string	End date, yyyy-mm-dd.
page	integer	Page of results to load (the response says whether there are `more`).
type	integer	Only this request type.
limit	integer	Maximum number of results.
start	string	Start date, yyyy-mm-dd.
max_id	integer	Only requests created before this request id.
sortby	string	'created' sorts newest first; anything else sorts by status then last update.
status	integer	Only requests with this status.
user_id	array	One or more user ids.

wheniwork_list_time_off_types

List the time-off types (e.g. Personal, Sick, Holiday) and whether each allows paid time. Their ids are the type_id for a new request. When I Work: GET /2/requesttypes.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

wheniwork_list_times

List clocked time entries — actual hours worked, clock-in/out times, length and approval state. Use only_open to see who is clocked in right now. When I Work: GET /2/times.

read-only

Argument	Type	Description
end	string	End of the window. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. "Mon, 05 Oct 2026 08:00:00 -0500").
start	string	Start of the window. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. "Mon, 05 Oct 2026 08:00:00 -0500").
user_id	array	One or more user ids.
only_open	boolean	Only times with no end yet (people currently clocked in).
updated_at	string	Only times updated since this timestamp. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. "Mon, 05 Oct 2026 08:00:00 -0500").

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "end": {
      "type": "string",
      "description": "End of the window. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\")."
    },
    "start": {
      "type": "string",
      "description": "Start of the window. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\")."
    },
    "user_id": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": 0
      },
      "minItems": 1,
      "description": "One or more user ids."
    },
    "only_open": {
      "type": "boolean",
      "description": "Only times with no end yet (people currently clocked in)."
    },
    "updated_at": {
      "type": "string",
      "description": "Only times updated since this timestamp. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\")."
    }
  }
}

wheniwork_list_users

List the employees, supervisors, managers and admins in the account, optionally limited to some schedules or searched by name/email. Role codes: 1 admin, 2 manager, 3 employee, 5 supervisor. When I Work: GET /2/users.

read-only

Argument	Type	Description
search	string	Search first name, last name or email.
location_id	array	One or more schedule (location) ids.
only_deleted	boolean	Only deleted/archived users (supervisor or above).
only_pending	boolean	Only pending users.
show_deleted	boolean	Include deleted users (supervisor or above).
show_pending	boolean	Include users who have not accepted their invite (default true).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "search": {
      "type": "string",
      "description": "Search first name, last name or email."
    },
    "location_id": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": 0
      },
      "minItems": 1,
      "description": "One or more schedule (location) ids."
    },
    "only_deleted": {
      "type": "boolean",
      "description": "Only deleted/archived users (supervisor or above)."
    },
    "only_pending": {
      "type": "boolean",
      "description": "Only pending users."
    },
    "show_deleted": {
      "type": "boolean",
      "description": "Include deleted users (supervisor or above)."
    },
    "show_pending": {
      "type": "boolean",
      "description": "Include users who have not accepted their invite (default true)."
    }
  }
}

wheniwork_publish_shifts

Publish draft shifts so employees can see them. Publishing does not itself send notifications. Undo with wheniwork_unpublish_shifts. When I Work: POST /2/shifts/publish.

destructive

Argument	Type	Description
ids*	array	The shift ids to publish.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "ids"
  ],
  "properties": {
    "ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "exclusiveMinimum": 0
      },
      "maxItems": 1000,
      "minItems": 1,
      "description": "The shift ids to publish."
    }
  }
}

wheniwork_unpublish_shifts

Return published shifts to draft, hiding them from employees. Undo with wheniwork_publish_shifts. When I Work: POST /2/shifts/unpublish.

destructive

Argument	Type	Description
ids*	array	The shift ids to unpublish.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "ids"
  ],
  "properties": {
    "ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "exclusiveMinimum": 0
      },
      "maxItems": 1000,
      "minItems": 1,
      "description": "The shift ids to unpublish."
    }
  }
}

wheniwork_update_shift

Change a shift — reassign it, move it, change position or notes. When I Work requires start_time, end_time and location_id on every update, so fetch the shift first and pass them back. This tool never sends a breaks array; When I Work documents that breaks omitted from an update's breaks list are removed, so re-check the shift's breaks afterwards. When I Work: PUT /2/shifts/{id}.

destructive

Argument	Type	Description
color	string	Hex colour without #, e.g. cc0000.
notes	string	Shift notes shown to the employee.
site_id	integer	Job site for the shift.
user_id	integer	The user to assign. 0 (or omitted on create) makes it an open shift.
end_time*	string	Shift end (required by the API even if unchanged).
shift_id*	integer	The shift id.
is_shared	boolean	For an open shift: a shared open shift.
published	boolean	Publish it immediately (default: draft).

wheniwork_update_time_off_request

Change a time-off request: set its status (0 pending, 1 canceled, 2 accepted/approved, 3 expired, 4 denied) and/or its dates or hours. Reversible — set the status back. start_time and end_time must be given together. When I Work: PUT /2/requests/{request_id}.

destructive

Argument	Type	Description
hours	number	Hours of paid time off to use.
status	integer	New status.
end_time	string	New end, full date-time (give with start_time).
request_id*	integer	The time-off request id.
start_time	string	New start, full date-time (give with end_time).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "request_id"
  ],
  "properties": {
    "hours": {
      "type": "number",
      "minimum": 0,
      "description": "Hours of paid time off to use."
    },
    "status": {
      "type": "integer",
      "maximum": 4,
      "minimum": 0,
      "description": "New status."
    },
    "end_time": {
      "type": "string",
      "description": "New end, full date-time (give with start_time)."
    },
    "request_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "The time-off request id.",
      "exclusiveMinimum": 0
    },
    "start_time": {
      "type": "string",
      "description": "New start, full date-time (give with end_time)."
    }
  }
}

When I Work MCP by usefulapi

Try it

wheniwork_create_shift Destructive

When I Work MCP by usefulapi

Try it

wheniwork_create_shift Destructive

Tools (21)