When I Work API Vocabulary
Terms and concepts used in the When I Work API for employee scheduling and workforce management
When I Work Vocabulary is a controlled vocabulary published by When I Work on the APIs.io network, defining 18 terms.
Defined terms include BaseScheduledBreak, Shift, ShiftChain, Chain, and V2Error.
A controlled vocabulary pins the words an API’s schemas, parameters and documentation use to one agreed definition each — the shared language a human or an agent needs to read the API the same way its authors do.
Terms
Controlled Vocabulary
vocabulary:
name: When I Work API Vocabulary
description: Terms and concepts used in the When I Work API for employee scheduling and workforce management
version: 1.0.0
source: https://apidocs.wheniwork.com/external/index.html
tags:
- Shifts
- Accounts
- Users
- Positions
- Punch
- Schedules (Locations)
- Sites
- Shift Templates (Blocks)
- Time Off Requests
- Request Type
- Shift Requests
- Availabilities
- Schedule Templates
- Annotations
- OpenShift Requests
- Times
- Payrolls
- Subscriptions
- Shift Breaks
- Shift Break - Paid Rest
- Forecast Tools
- Tasks
- Work Tags
- Webhooks
- Absences
- Scheduling Rules
- Break Attestation
- Import
- Export
- Reinvite
- Timezones
operations:
- summary: List Shifts
method: GET
path: /2/shifts
tags:
- Shifts
- summary: Create Shift
method: POST
path: /2/shifts
tags:
- Shifts
- summary: Bulk Delete Shifts
method: DELETE
path: /2/shifts
tags:
- Shifts
- summary: Get Shift
method: GET
path: /2/shifts/{id}
tags:
- Shifts
- summary: Update Shift
method: PUT
path: /2/shifts/{id}
tags:
- Shifts
- summary: Delete Shift
method: DELETE
path: /2/shifts/{id}
tags:
- Shifts
- summary: List Times
method: GET
path: /2/times
tags:
- Times
- summary: Create Time
method: POST
path: /2/times
tags:
- Times
- summary: Get Time
method: GET
path: /2/times/{id}
tags:
- Times
- summary: Update Time
method: PUT
path: /2/times/{id}
tags:
- Times
- summary: Delete Time
method: DELETE
path: /2/times/{id}
tags:
- Times
- summary: Clock In
method: POST
path: /2/times/clockin
tags:
- Punch
- summary: Clock Out
method: POST
path: /2/times/clockout
tags:
- Punch
- summary: Unassign/Release Shifts
method: POST
path: /2/shifts/unassign
tags:
- Shifts
- summary: Assign multiple users to an OpenShift
method: POST
path: /2/shifts/{id}/assign
tags:
- Shifts
- summary: List eligible users for OpenShift
method: GET
path: /2/shifts/eligible
tags:
- Shifts
- summary: Fetch shift history
method: GET
path: /2/shifts/{id}/history
tags:
- Shifts
- summary: Publish Shifts
method: POST
path: /2/shifts/publish
tags:
- Shifts
- summary: Unpublish Shifts
method: POST
path: /2/shifts/unpublish
tags:
- Shifts
- summary: Notify shifts
method: POST
path: /2/shifts/notify
tags:
- Shifts
- summary: Notify single shift
method: POST
path: /2/shifts/notify/{id}
tags:
- Shifts
- summary: Bulk Update Shifts
method: PUT
path: /2/shifts/bulk
tags:
- Shifts
- summary: List swap users
method: GET
path: /2/shifts/{id}/swapusers
tags:
- Shifts
- Swaps
- summary: List Positions
method: GET
path: /2/positions
tags:
- Positions
- summary: Create Position
method: POST
path: /2/positions
tags:
- Positions
- summary: Get Position
method: GET
path: /2/positions/{id}
tags:
- Positions
- summary: Update Position
method: PUT
path: /2/positions/{id}
tags:
- Positions
- summary: Delete Position
method: DELETE
path: /2/positions/{id}
tags:
- Positions
- summary: Update Multiple Positions
method: PUT
path: /2/positions/bulk
tags:
- Positions
- summary: List Schedules (Locations)
method: GET
path: /2/locations
tags:
- Schedules (Locations)
- summary: Create Schedule (Location)
method: POST
path: /2/locations
tags:
- Schedules (Locations)
- summary: Get Schedule (Location)
method: GET
path: /2/locations/{id}
tags:
- Schedules (Locations)
- summary: Update Schedule (Location)
method: PUT
path: /2/locations/{id}
tags:
- Schedules (Locations)
- summary: Delete Schedule (Location)
method: DELETE
path: /2/locations/{id}
tags:
- Schedules (Locations)
- summary: List Sites
method: GET
path: /2/sites
tags:
- Sites
- summary: Create Site
method: POST
path: /2/sites
tags:
- Sites
- summary: Get Site
method: GET
path: /2/sites/{id}
tags:
- Sites
- summary: Update Site
method: PUT
path: /2/sites/{id}
tags:
- Sites
- summary: Delete Site
method: DELETE
path: /2/sites/{id}
tags:
- Sites
- summary: List Shift Templates (Blocks)
method: GET
path: /2/blocks
tags:
- Shift Templates (Blocks)
- summary: Create Shift Template (Block)
method: POST
path: /2/blocks
tags:
- Shift Templates (Blocks)
- summary: Get Shift Template (Block)
method: GET
path: /2/blocks/{id}
tags:
- Shift Templates (Blocks)
- summary: Update Shift Template (block)
method: PUT
path: /2/blocks/{id}
tags:
- Shift Templates (Blocks)
- summary: Delete Shift Template (Block)
method: DELETE
path: /2/blocks/{id}
tags:
- Shift Templates (Blocks)
- summary: List Schedule Templates
method: GET
path: /2/templates
tags:
- Schedule Templates
- summary: Create Schedule Template
method: POST
path: /2/templates
tags:
- Schedule Templates
- summary: Get Schedule Template
method: GET
path: /2/templates/{id}
tags:
- Schedule Templates
- summary: Update Schedule Template
method: PUT
path: /2/templates/{id}
tags:
- Schedule Templates
- summary: Delete Schedule Template
method: DELETE
path: /2/templates/{id}
tags:
- Schedule Templates
- summary: List Annotations
method: GET
path: /2/annotations
tags:
- Annotations
- summary: Create Annotation
method: POST
path: /2/annotations
tags:
- Annotations
- summary: Get Annotation
method: GET
path: /2/annotations/{id}
tags:
- Annotations
- summary: Update Annotation
method: PUT
path: /2/annotations/{id}
tags:
- Annotations
- summary: Delete Annotation
method: DELETE
path: /2/annotations/{id}
tags:
- Annotations
- summary: List Availability Events
method: GET
path: /2/availabilityevents
tags:
- Availabilities
- summary: Create Availability Event
method: POST
path: /2/availabilityevents
tags:
- Availabilities
- summary: Get Availability Event
method: GET
path: /2/availabilityevents/{id}
tags:
- Availabilities
- summary: Update Availability Event
method: PUT
path: /2/availabilityevents/{id}
tags:
- Availabilities
- summary: Delete Availability Event
method: DELETE
path: /2/availabilityevents/{id}
tags:
- Availabilities
- summary: Create Availability Event Exception
method: POST
path: /2/availabilityevents/{id}/exceptions
tags:
- Availabilities
schemas:
- name: BaseScheduledBreak
description: ''
properties:
- name: id
description: ID of the break. Provide in the request when updating an existing break.
- name: account_id
description: ''
- name: length
description: The length of the break (seconds).
- name: paid
description: Whether the break is a paid rest break (true) or unpaid meal break (false)
- name: sort
description: Breaks are sorted by start time if it is available. If no start time is provided, breaks are sorted by
their position in the request. In a mixed list, breaks without a start time keep their original position, while breaks
with a start time are sorted amongst themselves.
- name: created_at
description: Date and time the break was created at.
- name: created_by
description: The id of the user who created the break.
- name: updated_at
description: Date and time the break was last updated.
- name: updated_by
description: The id of the user who last edited the break.
- name: Shift
description: ''
properties:
- name: id
description: ''
- name: account_id
description: ''
- name: user_id
description: The user assigned to the shift. Set to `0` for an Open Shift.
- name: location_id
description: Location the shift belongs to
- name: position_id
description: ''
- name: site_id
description: ''
- name: start_time
description: ''
- name: end_time
description: ''
- name: break_time
description: Length of the unpaid breaks for the shift in hours.
- name: breaks
description: An array of breaks for the shift. When updating a shift, any existing breaks for the shift that are not
included in the request will be deleted.
- name: ShiftChain
description: ''
properties:
- name: key
description: ''
- name: rrule
description: The RFC5545-compliant RRule representing the shift chain.
- name: until
description: The date when the shift chain ends.
- name: week
description: Represents the week frequency interval. `1` means weekly, `2` means every two weeks, etc.
- name: weekdays
description: 'A bitmask of the weekdays which shifts in this chain occur on. In a seven-bit binary number, the most
significant bit represents Sunday and the least significant bit represents Monday (0b1000001).
Examples:
| Days | Binary | Decimal |
|---------------------------|-------------|---------|
| Monday through Friday | `0b0011111` | 31 |
| Monday, Wednesday, Friday | `0b0010101` | 21 |
| Saturday and Sunday | `0b1100000` | 96 |
'
- name: timezone_id
description: The timezone this chain is built in
- name: count
description: The number of shifts created by this chain.
- name: Chain
description: ''
properties:
- name: until
description: 'The date you want the recurrence to end on. It must be in UTC, such that when shifted to the provided
timezone (see `timezone_id` below) the time will be midnight in a local time.
Example: You''re creating a shift chain in the `America/Chicago` timezone that you want to end on 7/29/24
locally. You would send `2024-07-29T05:00:00Z`, which when converted to the provided timezone would be
`2024-07-29T00:00:00-05:00`.
**NOTE**: This is required when _creating_ a repeating shift. It may be omitted when editing one.
'
- name: week
description: 'Represents the week frequency interval. `1` means weekly, `2` means every two weeks, etc.
**NOTE**: This is required when _creating_ a repeating shift. It may be omitted when editing one.
'
- name: weekdays
description: 'A bitmask of the weekdays which shifts in this chain occur on. In a seven-bit binary number, the most
significant bit represents Sunday and the least significant bit represents Monday (0b1000001).
Examples:
| Days | Binary | Decimal |
|---------------------------|-------------|---------|
| Monday through Friday | `0b0011111` | 31 |
| Monday, Wednesday, Friday | `0b0010101` | 21 |
| Saturday and Sunday | `0b1100000` | 96 |
'
- name: timezone_id
description: 'The timezone this chain is built in.
This must be either the `timezone_id` or `olson_id` from one of the timezones available through
[this endpoint](#tag/Timezones).
'
- name: V2Error
description: ''
properties:
- name: error
description: A description of the specific error
- name: code
description: The API error code
- name: Time
description: ''
properties:
- name: id
description: The time id
- name: account_id
description: The account id
- name: user_id
description: The user assigned to the time.
- name: creator_id
description: The user that created the time.
- name: position_id
description: Position the time belongs to. 0 if unassigned.
- name: location_id
description: Location the time belongs to. 0 if unassigned.
- name: site_id
description: Site the time belongs to. 0 if unassigned.
- name: shift_id
description: A shift tied to this time. 0 if unassigned.
- name: start_time
description: The start time
- name: end_time
description: The end time
- name: User
description: ''
properties:
- name: account_id
description: ID of the primary account for this user.
- name: activated
description: Whether the manager has activated this user.
- name: email
description: The email address of this user.
- name: employee_code
description: 'The user''s employee code. This code can be used to clock in instead of
the user''s email address, or it can be used to help map users in When
I Work to other services.
'
- name: first_name
description: The first name of this user.
- name: hourly_rate
description: 'The base hourly rate for this user. The user can have additional wages
based on the position they are working at the time. There is no currency
attached, so customers are expected to input correct values for their
currency or do their own conversion from USD.
'
- name: hours_max
description: 'The max hours that this user prefers to work. A manager may still
schedule the user beyond this value.
'
- name: hours_preferred
description: The preferred number of hours for this user to work.
- name: id
description: Unique identifier for the user.
- name: is_deleted
description: Whether the user has been deleted.
- name: PunchResponse
description: ''
properties:
- name: time
description: The Time object that the punch is associated with
- name: overtime_alert
description: Was an over-time alert triggered
- name: user
description: The User that has punched in
- name: punches
description: 'Array of punches associated with the current Time
* Punch in/out
* Punch break start/stop
'
- name: OpenShiftApprovalRequestUser
description: ''
properties:
- name: id
description: The ID of the OpenShift Approval Request
- name: user_id
description: The ID of the user that raised their hand for this request
- name: created_at
description: ''
- name: deleted_at
description: ''
- name: OpenShiftApprovalRequest
description: ''
properties:
- name: id
description: The ID of the OpenShift Approval Request
- name: account_id
description: The ID of the account that this OpenShift Approval Request belongs to
- name: shift_id
description: The ID of the shift that this OpenShift Approval Request is for
- name: shift
description: ''
- name: creator_id
description: The ID of the user that created this request
- name: updater_id
description: The ID of the user that last updated this request
- name: status
description: The current status of the OpenShift Approval Request.
- name: user_status
description: Copy of the status field to mirror the data model of other request types
- name: is_shared
description: Is this approval request shared across schedules
- name: created_at
description: ''
- name: ShiftHistory
description: ''
properties:
- name: type
description: The type of history event
- name: attributes
description: ''
- name: ShiftBulk
description: ''
properties:
- name: id
description: ''
- name: account_id
description: ''
- name: user_id
description: The user assigned to the shift. Set to `0` for an Open Shift.
- name: location_id
description: Location the shift belongs to
- name: position_id
description: ''
- name: site_id
description: ''
- name: start_time
description: ''
- name: end_time
description: ''
- name: break_time
description: ''
- name: color
description: Assign color to shift
- name: schemas-Shift
description: ''
properties:
- name: id
description: ''
- name: accountId
description: ''
- name: userId
description: The user assigned to the shift. Set to `0` for an Open Shift.
- name: locationId
description: Location the shift belongs to
- name: positionId
description: ''
- name: siteId
description: ''
- name: startTime
description: ''
- name: endTime
description: ''
- name: breakTime
description: ''
- name: color
description: ''
- name: Error
description: ''
properties:
- name: error
description: ''
- name: Position
description: ''
properties:
- name: id
description: ''
- name: account_id
description: ''
- name: name
description: ''
- name: color
description: ''
- name: sort
description: Custom sort order applied to this position
- name: tips_tracking
description: 'Whether this position tracks tips.
Note: the tips feature is needed to use this field.
'
- name: created_at
description: ''
- name: updated_at
description: ''
- name: Place
description: ''
properties:
- name: address
description: ''
- name: business_name
description: ''
- name: country
description: ''
- name: id
description: ''
- name: latitude
description: ''
- name: locality
description: ''
- name: longitude
description: ''
- name: place_id
description: ''
- name: place_type
description: ''
- name: postal_code
description: ''
- name: Schedule
description: ''
properties:
- name: id
description: ''
- name: account_id
description: ''
- name: name
description: ''
- name: address
description: ''
- name: coordinates
description: ''
- name: deleted_at
description: ''
- name: ip_address
description: ''
- name: is_default
description: ''
- name: is_deleted
description: ''
- name: latitude
description: ''
- name: Site
description: ''
properties:
- name: id
description: ''
- name: account_id
description: ''
- name: location_id
description: ''
- name: name
description: ''
- name: color
description: ''
- name: description
description: ''
- name: address
description: ''
- name: coordinates
description: ''
- name: latitude
description: ''
- name: longitude
description: ''
Work with this as data
Every vocabulary here is available over the APIs.io API and to AI agents over MCP. Vocabularies is not yet its own endpoint on the v1 API. Reach it through catalog search and the tag graph, or the MCP server.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for vocabularies
3 MCP tools reach this
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
curl "https://apis.io/api/v1/search?q=when-i-work-vocabulary&limit=10"
curl "https://apis.io/api/v1/tags/when-i-work-vocabulary"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.