openapi: 3.0.3
info:
version: 1.0.0
title: When I Work API Documentation
description: 'The When I Work API is thorough, flexible, and restful. Its methods are logically grouped and follow standard
conventions. Make a selection from the left to jump to the method group you would like to know more about.
When designing your integration, When I Work recommends leveraging our Webhooks subscriptions if you plan to regularly
pull data to sync records in your data store. This may be preferable to using our API for tasks like staying up to date
about shifts or time entries in your account. Frequent large API requests may run into rate limitations.
Find out more about Webhooks at our [Help Center](https://help.wheniwork.com/articles/webhooks-reference/) or contact
our [Customer Care team](mailto:[email protected]) for assistance.
For more information about obtaining an API key, or general API questions, please refer to the [Help Center](https://help.wheniwork.com/articles/api-services-reference-guide/).
'
servers:
- url: https://api.wheniwork.com
description: Production
security:
- W-Token: []
tags:
- name: Shifts
description: 'Shifts provide the basis for scheduling. Many other objects, including Schedules (aka Locations), Positions,
Sites, Users, Tasks, and Tags all link through Shifts.
For more information about how to use Shifts, visit the [Help Center](https://help.wheniwork.com/article-categories/scheduling-your-team/).
'
- name: Accounts
description: 'Accounts (aka Workplaces) are objects that define a business account with When I Work. Each user is associated
with an account enabling them to access Shifts or other data.
For more information about Accounts, visit the [Help Center](https://help.wheniwork.com/article-categories/account-settings/).
'
- name: Users
description: 'A person on the When I Work platform is associated with a two tier record. The persons email/password is
associated to a person_id.
For each Workplace the person belongs to a user_id record exists. This record links back to the person_id so only a single
instance of the email/password exists. If a user updates their email or password this applies to all related instances
of the user.
For more information about Users, visit the [Help Center](https://help.wheniwork.com/articles/user-access-privileges-computer/).
'
- name: Positions
description: 'Positions (aka, job or duty) are used to define labor allocation. Users can be tagged (associated) with one
or more Positions. When I Work uses this association for shift eligibility, Alert notifications filtering and labor reporting.
For more information about using Positions, visit the [Help Center](https://help.wheniwork.com/articles/creating-and-managing-positions-computer/).
'
- name: Punch
description: 'A punch is an event where a user clocks in or clocks out. Punches can be managed to restrict where an employee
can clock in/out and from what devices.
If a user forgets to clock out, they will be allowed to clock in after 9 hours from the end of their scheduled shift.
If there is no scheduled shift, the user can clock in again after 18 hours from when they originally clocked in.
'
- name: Schedules (Locations)
description: 'Schedules are logical groupings of users that are working together. Schedules can be physical offices with
addresses or logical groups like departments. Users can be tagged (associated) to one or more schedules. Schedules can
be departments, facilities, business divisions or any grouping of staff.
For more information about using Scheduled, visit the [Help Center](https://help.wheniwork.com/articles/creating-and-managing-schedules-computer/).
'
- name: Sites
description: "Sites communicate additional information about a given shift to the recipient. Typical usage is when you schedule\
\ employees for shifts that are at different physical sites (addresses) compared to the Schedule where the shift is assigned.\
\ A Job site can include additional detail (address or coordinates) that informs the user where this particular shift\
\ is to take place. An additional use case would be if you want to use an additional labor reporting tier and having the\
\ Job Site be a project or cost center value.\n\n For more information about using Sites, visit the [Help Center](https://help.wheniwork.com/articles/scheduling-shifts-at-job-sites-computer/).\n"
- name: Shift Templates (Blocks)
description: 'Shift templates save you time when you need to schedule shifts that have a consistent start and end time.
Instead of manually entering in custom shift details one-by-one, shift templates allow you to schedule a shift quickly
and easily.
For more information about using Shift Templates, visit the [Help Center](https://help.wheniwork.com/articles/creating-and-managing-shift-templates-computer/).
'
- name: Time Off Requests
description: 'When you need to take time off from work, use When I Work to send the request to your manager for approval.
Time off can be submitted as unpaid, paid (PTO), sick, or holiday.
For more information about using Time Off Requests, visit the [Help Center](https://help.wheniwork.com/articles/requesting-time-off-computer/).
'
- name: Request Type
description: 'Types of time off that can be selected when submitting a time off request.
For more information about using Time Off Requests, visit the [Help Center](https://help.wheniwork.com/articles/requesting-time-off-computer/).
'
- name: Shift Requests
description: 'If you’re unable to work one of your shifts, you can give it to one of your coworkers (drop the shift) or
trade shifts with one of your coworkers (swap shifts).
For more information about using Shift Requests, visit the [Help Center](https://help.wheniwork.com/articles/swapping-and-dropping-shifts-computer/).
'
- name: Availabilities
description: 'Set your availability preferences to let your employer know when you prefer to work and when you prefer not
to work.
For more information about using Availabilities, visit the [Help Center](https://help.wheniwork.com/articles/setting-your-availability-computer/).
'
- name: Schedule Templates
description: 'Schedule templates allow you to create a daily or weekly schedule that is reusable. If your schedules are
very similar from day to day or week to week, use a template to save time and avoid creating schedules from scratch.
For more information about using Schedule Templates, visit the [Help Center](https://help.wheniwork.com/articles/using-schedule-templates-computer/).
'
- name: Annotations
description: 'Annotations convey important information to all staff for the given schedules (locations) and date range.
Any or none of the following tags may apply to an Annotation:
* Time Off Not Allowed
* Business Closed
* Announcement
The "Time Off Not Allowed" tag is the only tag that affects the behavior of another API. Time Off requests will be considered
invalid if the request''s date range overlaps an Annotation of the "Time Off Not Allowed" type for the user''s location(s).
For more on using Annotations, visit the [Help Center](https://help.wheniwork.com/hc/en-us/articles/204348065-Annotations).
'
- name: OpenShift Requests
description: 'Shift Bidding, also called “OpenShift Requests”, is an option within an OpenShift that allows employees to
express interest in the shift. Management can then view who has requested to pick up the OpenShift and select and approve
an employee to work the shift.
For more info about using OpenShift Requests, visit the [Help Center](https://help.wheniwork.com/articles/shift-bidding/).
'
- name: Times
description: 'Time records are a listing of the worked hours and can be select by date range. Records are sourced from timeclock
terminal, web clock In/Out, mobile clock In/Out, timesheet edits, and API record creation/edits of time values.
For more info about user Times, visit the [Help Center](https://help.wheniwork.com/articles/reviewing-employees-time-sheets-computer/).
'
- name: Payrolls
description: 'Payrolls allows you to select a pay period date range and hours worked within that range. Default range if
not supplied is today + 3 days.
> Please note that payrolls cannot be created or deleted via the API
For more info about managing Payroll, visit the [Help Center](https://help.wheniwork.com/articles/close-and-export-payroll/).
'
- name: Subscriptions
description: 'Subscriptions are additional plans that can be attached to an account. Subscriptions may include free or paid
plans.
'
- name: Shift Breaks
description: "Two types of breaks are provided. First; Scheduled Shift Breaks are break records associated with scheduled\
\ shifts. Second; Shift Breaks are break records associated with time worked.\nFor Shift Breaks (Attendance)\n Three\
\ types of records are possible from a break action or automated action\n A record can be created from a user break\
\ punch allocation\n A record can be created from a Manager/Supervisor edit to a timesheet. (With this type of record,\
\ no break time is generated and only the length is available to be queried.)\n A Break record can be created via the\
\ system configuration setting for Auto-Deduct of Breaks. (With this type of record, no break time is generated and only\
\ the length is available to be queried.)\n\n Note: This endpoint requires the request header for w-userid.\n For\
\ more information about managing Breaks, visit the [Help Center](https://help.wheniwork.com/articles/attendance-settings/)\n"
- name: Shift Break - Paid Rest
description: "When the Attendance setting is enabled to Ask Employees About Paid Rest Breaks the feedback on whether or\
\ not breaks were taken is provided here.\n\n Note: This endpoint requires the request header for w-userid.\n For more\
\ information about managing Breaks, visit the [Help Center](https://help.wheniwork.com/articles/paid-break-reporting/#reporting-paid-breaks)\n\
\n (Deprecated - Please refer to the [updated documentation](https://apidocs.wheniwork.com/external/index.html?repo=attendance#tag/Times)\
\ for managing break attestations)\n"
- name: Forecast Tools
description: 'Get more insight into your budget while scheduling using the forecast tools. Track the sales and hours budget
for your schedules to ensure you have the right coverage and are within your labor budget.
Use the Forecast Tools service API to import your forecast data. Please visit the [API documentation](https://apidocs.wheniwork.com/external/index.html?repo=forecast-tools&branch=main)
for more details.
For more info about using Forecast Tools, visit the [Help Center](https://help.wheniwork.com/articles/forecast-tools/).
'
- name: Tasks
description: "Use Task Lists to let your employees know what activities they need to complete on a given day or during their\
\ shift. Then monitor the task lists to ensure those activities are completed.\n\n Note: This endpoint requires the request\
\ header for w-userid.\nUse the Tasks service API to create and assign task lists. Please visit the [API documentation](https://apidocs.wheniwork.com/external/index.html?repo=tasks&branch=main)\
\ for more details.\n\nFor more info about using Tasks, visit the [Help Center](https://help.wheniwork.com/articles/how-tasks-work-computer/).\n"
- name: Work Tags
description: "Tags provide a way to define custom shift qualifications that cannot be easily captured by position alone.\
\ Think of tags like additional eligibility requirements that you can layer on top of positions.\n\n Note: This endpoint\
\ requires the request header for w-userid.\nUse the Work Tags service API to create and assign tags to users, shifts\
\ and shift templates. Please visit the [API documentation](https://apidocs.wheniwork.com/external/index.html?repo=worktags&branch=main)\
\ for more details.\n\nFor more info about using Work Tags, visit the [Help Center](https://help.wheniwork.com/articles/creating-and-managing-tags-computer/).\n"
- name: Webhooks
description: "Webhooks will send streaming events that details changes happening within the When I Work environment. A webserver\
\ must be configured to receive the events. Events have a few second delay before sending to allow for batching.\n\n \
\ Note: Webhooks require TLS and require the events to be streamed to a domain owned by the account. Please visit the\
\ [API documentation](https://apidocs.wheniwork.com/external/index.html?repo=webhooks&branch=main) for more details.\n\
\nFor more info about using Webhooks, visit the [Help Center](https://help.wheniwork.com/articles/webhooks-reference/).\n"
- name: Absences
description: "Absences allows users to report when they cannot work an assigned shift and provides a way to track call outs.\n\
\n Note: Use the Scheduling API to report and fetch Absences. Please visit the [API documentation](https://apidocs.wheniwork.com/external/index.html?repo=scheduling&branch=main#tag/Absences)\
\ for more details.\n\nFor more info about using Absences, visit the [Help Center](https://help.wheniwork.com/articles/how-tracking-absences-works/).\n"
- name: Scheduling Rules
description: "Scheduling rules encompass a variety of rules to help users schedule with confidence.\n\n Note: Use the Scheduling\
\ API to evaluate rules for shifts and users. Please visit [API documentation](https://apidocs.wheniwork.com/external/index.html?repo=scheduling&branch=main#tag/Rules)\
\ for more details.\n\nFor more info about using Scheduling Rules, visit the [Help Center](https://help.wheniwork.com/articles/scheduling-rules-reference/).\n"
- name: Break Attestation
description: "Break attestation (break reporting) allows users to report that they have taken all of their required breaks.\
\ If \nthey were not able to, they can leave a note explaining why the breaks were missed.\n\n Note: Use the Attendance\
\ API to report and fetch break attestations. Please visit the [API documentation](https://apidocs.wheniwork.com/external/index.html?repo=attendance#tag/Times)\n"
- name: Import
description: "The import API is used to import a variety of When I Work resources from user-provided CSV or Excel files.\n\
\n### Import Types\n\nAll available import types and their columns are listed here. Where possible, the column names will\
\ align with names used elsewhere in the API, but this is not always possible.\n\n<table>\n <thead>\n <tr>\n \
\ <th>type</th>\n <th>columns</th>\n <th>required?</th>\n <th>notes</th>\n </tr>\n </thead>\n\
\ <tbody>\n <tr>\n <td rowspan=\"5\" class=\"nowrap\"><code>SHIFT_TEMPLATE</code></td>\n <td>start_time</td>\n\
\ <td>✅</td>\n <td></td>\n </tr>\n <tr>\n <td>end_time</td>\n <td>✅</td>\n <td></td>\n\
\ </tr>\n <tr>\n <td>schedule</td>\n <td></td>\n <td>\n <p>A schedule name to associate\
\ with the shift template. If no schedule with that name exists, a new schedule will be created.</p>\n <p>If omitted,\
\ the shift template will be assigned to all schedules (or the value \"All Schedules\" can be provided to do the same).</p>\n\
\ </td>\n </tr>\n <tr>\n <td>position</td>\n <td></td>\n <td>\n <p>A position\
\ name to associate with the shift template. If no position with that name exists, a new position will be created.</p>\n\
\ </td>\n </tr>\n <tr>\n <td>unpaid_break</td>\n <td></td>\n <td>The length of the unpaid\
\ break in minutes.</td>\n </tr>\n <tr>\n <td rowspan=\"12\" class=\"nowrap\"><code>EMPLOYEE</code></td>\n\
\ <td>first_name</td>\n <td>✅</td>\n <td>First name of the employee</td>\n </tr>\n <tr>\n \
\ <td>last_name</td>\n <td>✅</td>\n <td>Last name of the employee</td>\n </tr>\n <tr>\n \
\ <td>email</td>\n <td></td>\n <td>The email address of the employee</td>\n </tr>\n <tr>\n <td>employee_code</td>\n\
\ <td></td>\n <td>The employee code to associate with the employee</td>\n </tr>\n <tr>\n <td>file_number</td>\n\
\ <td></td>\n <td>The file number corresponding to the employee in ADP</td>\n </tr>\n <tr>\n \
\ <td>id</td>\n <td></td>\n <td>The user id corresponding to the employee in When I Work</td>\n </tr>\n\
\ <tr>\n <td>location</td>\n <td></td>\n <td>\n <p>A schedule (location) name to associate\
\ with the employee. If no schedule with that name exists, a new schedule will be created.</p>\n </td>\n </tr>\n\
\ <tr>\n <td>max</td>\n <td></td>\n <td>The maximum hours per week of the employee</td>\n </tr>\n\
\ <tr>\n <td>phone</td>\n <td></td>\n <td>The phone number of the employee</td>\n </tr>\n \
\ <tr>\n <td>position</td>\n <td></td>\n <td>\n <p>A position name to associate with the employee.\
\ If no position with that name exists, a new position will be created.</p>\n </td>\n </tr>\n <tr>\n \
\ <td>tags</td>\n <td></td>\n <td>\n <p>A comma separated list of tags to associate to the employee.\
\ If the tag does not exist, it will be created.</p>\n </td>\n </tr>\n <tr>\n <td>wage</td>\n \
\ <td></td>\n <td>\n <p>The hourly rate of the employee expressed as a floating point number (e.g. 14.50)</p>\n\
\ </td>\n </tr>\n </tbody>\n </table>\n"
- name: Export
- name: Reinvite
- name: Timezones
description: Timezones for When I work workplaces including Olson ID
paths:
/2/shifts:
get:
summary: List Shifts
description: Fetch a list of shifts based on a set of filters
tags:
- Shifts
parameters:
- name: user_id
in: query
description: The user id to filter by
schema:
type: integer
example: 201
- name: start
in: query
description: The start of the filter range.
schema:
type: string
format: date-time
default: now
- name: end
in: query
description: The end of the filter range.
schema:
type: string
format: date-time
default: now + 3 days
- name: unpublished
in: query
description: Whether or not to include unpublished shifts. Requires supervisor rights.
schema:
type: boolean
- name: include_open
in: query
description: Whether or not to include open shifts from the user's assigned Schedules.
schema:
type: boolean
- name: include_onlyopen
in: query
description: Whether or not to include only open shifts from the user's assigned Schedules.
schema:
type: boolean
- name: include_allopen
in: query
description: 'Whether or to include open shifts across All Schedules. Requires "Manager or Admin access" level.
Common practice is to combine allopen with one of the other inclusion options.
'
schema:
type: boolean
- name: deleted
in: query
description: Whether to include a list of shift IDs ("deleted_ids") that were deleted during the passed time window.
schema:
type: boolean
- name: include_swaps
in: query
description: Whether or not to include swap requests.
schema:
type: boolean
- name: limit
in: query
description: Maximum number of results to return.
schema:
type: integer
- name: all_locations
in: query
description: 'Whether to include data from all locations. Shifts are marked as "readonly" if not a manager user.
If this option is included in addition to the `location_id` option, all shifts linked to other
locations, through users in other locations, will also be included.
'
schema:
type: boolean
- name: location_id
in: query
description: 'One or more location IDs by which to limit results
_Also see `all_locations` above_
'
schema:
type: string
format: csv
- name: shift_sort
in: query
description: True to sort results by user_id, false to sort by shift time. Missing for default sort
schema:
type: boolean
- name: include_repeating_shifts_to
in: query
description: End date to include repeating shifts in series, if applicable
schema:
type: string
format: date-time
default: null
- name: trim_openshifts
in: query
description: Setting to true will work w/ the Allow Partial Openshifts feature to display trimmed start/end times
for users that can take a conflicting openshift based on the account settings.
schema:
type: boolean
- name: limit_by_rules
in: query
description: Setting to true will work w/ the Scheduling Rules feature to only return OpenShifts that the requester
is eligible for according to the scheduling rules settings for the account.
schema:
type: boolean
x-code-samples:
- lang: shell
source: curl https://api.wheniwork.com/2/shifts
responses:
'200':
description: Valid
content:
application/json:
schema:
type: object
properties:
shifts:
type: array
items:
$ref: '#/components/schemas/Shift'
repeating_shifts:
description: 'This field will be present if the `include_repeating_shifts_to` parameter is provided. For
each
fetched shift, if it is on a shift chain, we will insert all the shifts on that chain from the
first up to the date specified in the parameter.
'
type: array
items:
$ref: '#/components/schemas/Shift'
shiftchains:
description: Any shift chains that the fetched shifts are a part of
type: array
items:
$ref: '#/components/schemas/ShiftChain'
post:
summary: Create Shift
description: 'Create one or many shifts for scheduling.
**NOTE:** The response is slightly different if you create many shifts instead of one.
'
tags:
- Shifts
parameters:
- name: include_repeating_shifts_to
in: query
description: End date to include repeating shifts in series, if applicable
schema:
type: string
format: date-time
default: null
requestBody:
$ref: '#/components/requestBodies/ShiftRequest'
responses:
'200':
description: Valid
content:
application/json:
schema:
oneOf:
- type: object
properties:
shift:
$ref: '#/components/schemas/Shift'
repeating_shifts:
description: 'This field will be present if the `include_repeating_shifts_to` parameter is provided.
It
will only be populated with shifts if a shift chain is created with the shift and it we will
insert the created shifts from the beginning of the chain up to the date specified in the
parameter.
**NOTE:** This does not apply when creating shifts in bulk.
'
type: array
items:
$ref: '#/components/schemas/Shift'
shiftchains:
description: A shift chain that was created with the shift
type: array
items:
$ref: '#/components/schemas/ShiftChain'
tags:
type: array
items:
type: string
example:
- e96cab22-0542-4e75-80a4-7c49262eea41
- type: object
properties:
shifts:
type: array
items:
$ref: '#/components/schemas/Shift'
repeating_shifts:
description: 'The shifts created as part of a shift chain, if the `include_repeating_shifts_to` parameter
is provided and a set of shifts match the criteria.
'
type: array
items:
$ref: '#/components/schemas/Shift'
shiftchains:
description: Any shift chains that were created for the created shifts
type: array
items:
$ref: '#/components/schemas/ShiftChain'
tagIdsMap:
description: A map of shift IDs to an array of tag IDs
type: object
additionalProperties:
type: array
items:
type: string
example:
'101': []
'102':
- e96cab22-0542-4e75-80a4-7c49262eea41
'103':
- e96cab22-0542-4e75-80a4-7c49262eea41
- 3b7c8cd3-58a4-4ca3-bb34-0db3cbc1a3de
delete:
summary: Bulk Delete Shifts
deprecated: false
description: 'If IDs are provided, those will take precedence. Otherwise it will use the provided filters to delete
shifts.
If filters are used, the `start`, `end`, and `location_id` properties are required.
'
tags:
- Shifts
parameters:
- name: ids
in: query
description: A comma-separated list of shift IDs to delete. Takes precedence over IDs provided in the body and provided
filter properties.
required: false
example:
- 101%2C102
schema:
type: array
items:
type: string
- name: message
in: query
description: Used to notify the shift's assignee that their shift has been deleted. Your message will be added to
the notification email. If you want to send the notification email without a message, simple send a single space.
required: false
example: We%27ll%20be%20closed%20that%20day
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
ids:
type: array
items:
type: integer
description: The IDs of the shifts to delete. Takes precedence over filter properties.
start:
type: string
format: date-time
description: The start of the range you want to delete shifts over.
end:
type: string
format: date-time
description: The end of the range you want to delete shifts over.
location_id:
type: array
items:
type: integer
description: The schedule(s) you want to delete shifts from. At least one is required.
position_id:
type: array
items:
type: integer
description: The positions of shifts you want to delete.
user_id:
type: array
items:
type: integer
description: The users whose shifts you want to delete.
site_id:
type: array
items:
type: integer
description: The sites of shifts you want to delete.
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the operation was successful. If absent, nothing was deleted.
deleted:
type: array
items:
type: integer
description: The IDs of the deleted shifts
count:
type: integer
description: The number of shifts deleted
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'404':
description: Shift Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'500':
description: Internal Error
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
/2/shifts/{id}:
get:
summary: Get Shift
description: Get a single shift by ID
tags:
- Shifts
parameters:
- name: id
in: path
description: The ID of the shift
schema:
type: integer
required: true
- name: include_repeating_shifts_to
in: query
description: End date to include repeating shifts in series, if applicable
schema:
type: string
format: date-time
default: null
responses:
'200':
description: Valid
content:
application/json:
schema:
type: object
properties:
shift:
$ref: '#/components/schemas/Shift'
repeating_shifts:
description: 'This field will be present if the `include_repeating_shifts_to` parameter is provided. If
the
fetched shift has a shift chain, we will insert all the shifts on that chain from the first up
to the date specified in the parameter.
'
type: array
items:
$ref: '#/components/schemas/Shift'
shiftchains:
description: Any shift chain this shift is a part of
type: array
items:
$ref: '#/components/schemas/ShiftChain'
put:
summary: Update Shift
description: Update an existing shift for scheduling
tags:
- Shifts
parameters:
- name: id
in: path
description: The ID of the shift
schema:
type: integer
required: true
- name: include_repeating_shifts_to
in: query
description: End date to include repeating shifts in series, if applicable
schema:
type: string
format: date-time
default: null
requestBody:
$ref: '#/components/requestBodies/ShiftRequest'
responses:
'200':
description: Vali
# --- truncated at 32 KB (308 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/when-i-work/refs/heads/main/openapi/when-i-work-openapi.yml