openapi: 3.0.3 info: version: 1.0.0 title: When I Work API Documentation Accounts Shifts API 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:support@wheniwork.com) 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/). ' 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: 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. We will insert the created or edited shifts from the beginning of the chain up to the date specified in the parameter. **NOTE:** This does not apply when updating shifts in bulk. ' 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' deleted: description: A list of shift IDs that were deleted as a result of the update. Applicable for updates to repeating shifts that impact future shifts on the same chain. type: array items: type: integer example: - 878787 - 656565 delete: summary: Delete Shift deprecated: false description: Delete an existing shift when no longer needed. This operation cannot be undone. tags: - Shifts parameters: - name: id in: path description: The ID of the shift required: true example: 0 schema: type: integer - 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. Must be URL encoded. required: false example: We%27ll%20be%20closed%20that%20day schema: type: string - name: chain in: query description: Only applies to repeating shifts. Any value will delete the shift and all shifts that come after it on the chain. required: false schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: success: type: boolean examples: - true description: Whether deletion was successful. If absent, it means nothing was actually deleted. default: true deleted: type: array items: type: integer description: The IDs of the shifts that were deleted examples: '1': summary: Success value: success: true deleted: - 101 - 102 - 103 '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/unassign: post: summary: Unassign/Release Shifts description: 'Move a set of shifts from users to an OpenShift. This can also be used by employees when the Shift Release setting is enabled. ' tags: - Shifts requestBody: $ref: '#/components/requestBodies/ShiftUnassignRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: shifts: type: array items: $ref: '#/components/schemas/Shift' /2/shifts/{id}/assign: post: parameters: - name: id in: path description: The ID of the shift schema: type: integer required: true summary: Assign multiple users to an OpenShift description: 'Assign mutiple users to an OpenShift with multiple instances This can also be used to approve multiple users for an OpenShift that requires approval. ' tags: - Shifts requestBody: $ref: '#/components/requestBodies/ShiftAssignRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: shifts: type: array items: $ref: '#/components/schemas/Shift' openshiftapprovalrequests: type: array items: $ref: '#/components/schemas/OpenShiftApprovalRequest' /2/shifts/eligible: get: summary: List eligible users for OpenShift description: Get a list of eligible users to offer an OpenShift based on existing shift, or shift parameters tags: - Shifts parameters: - name: id in: query description: The ID of the shift schema: type: integer - name: start in: query description: Start time of the potential shift (required if Shift ID not present) schema: type: string format: date-time - name: end in: query description: End time of the potential shift (required if Shift ID not present) schema: type: string format: date-time - name: position_id in: query description: Position ID of the potential shift (required if Shift ID not present) schema: type: string - name: location_id in: query description: Location ID of the potenential shift (required if Shift ID not present) schema: type: string - name: is_shared in: query description: Is the shift a shared OpenShift schema: type: boolean default: false - name: include_objects in: query description: Include user locations and positions in output schema: type: boolean default: false - name: tags in: query description: A set of tag IDs to compare the eligible users against schema: type: array items: type: string default: [] responses: '200': description: Valid content: application/json: schema: type: object properties: users: type: array items: $ref: '#/components/schemas/User' /2/shifts/{id}/history: get: parameters: - name: id in: path description: The ID of the shift schema: type: integer required: true - name: include_deleted in: query description: Flag to indicate if you want to search for a deleted shift's history (off by default) type: boolean required: false default: false summary: Fetch shift history description: 'Provides a detailed list of history events that are recorded every time the given shift was changed indicating how it changed (Reason Code), and by which user (updated by ID). This history is a rolling 90 day period based on the shift start date/time. Also, history is not retained for OpenShifts following deletion of the shift. ' tags: - Shifts responses: '200': description: Valid content: application/json: schema: type: object properties: shift: description: The current version of the shift $ref: '#/components/schemas/Shift' history: description: Array of history events type: array items: $ref: '#/components/schemas/ShiftHistory' /2/shifts/publish: post: summary: Publish Shifts description: "These methods allow you to publish or unpublish a group of shifts.\n (Note: multi-threading is supported for large lists of shift)\n See Notify Shifts for informing users of Publication\n" tags: - Shifts requestBody: $ref: '#/components/requestBodies/ShiftPublish' responses: '200': description: Valid content: application/json: schema: type: object properties: shifts: type: array items: $ref: '#/components/schemas/Shift' /2/shifts/unpublish: post: summary: Unpublish Shifts description: "These methods allow you to publish or unpublish a group of shifts.\n (Note: multi-threading is supported for large lists of shift)\n" tags: - Shifts requestBody: $ref: '#/components/requestBodies/ShiftPublish' responses: '200': description: Valid content: application/json: schema: type: object properties: shifts: type: array items: $ref: '#/components/schemas/Shift' /2/shifts/notify: post: summary: Notify shifts description: 'Send Notifications for a published schedule ' tags: - Shifts requestBody: $ref: '#/components/requestBodies/ShiftNotifyRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: success: type: boolean example: true email: type: integer example: 5 description: A count of the emails sent. sms: type: integer example: 10 description: A count of the SMS and/or push notifications (depending on user preferences) sent. /2/shifts/notify/{id}: post: summary: Notify single shift description: Send Notifications for a single shift tags: - Shifts parameters: - name: id in: path description: The ID of the shift to send notifications schema: type: integer required: true requestBody: $ref: '#/components/requestBodies/SingleShiftNotifyRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: success: type: boolean example: true email: type: integer example: 5 description: A count of the emails sent. sms: type: integer example: 10 description: A count of the SMS and/or push notifications (depending on user preferences) sent. /2/shifts/bulk: put: summary: Bulk Update Shifts description: Make updates to multiple shifts in a single API request by submitting an array of the shifts and data to be changed. tags: - Shifts parameters: - name: assign_openshift_instances in: query description: 'When set to true, any multiple instance openshifts that are being assigned will assign only one openshift off the stack rather than the entire stack. ' schema: type: boolean default: false requestBody: $ref: '#/components/requestBodies/BulkEditShiftRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: shifts: description: Array of shift objects to update type: array items: $ref: '#/components/schemas/Shift' '400': description: Invalid content: application/json: schema: type: object properties: shifts: description: Shifts that were successfully updated and their new data type: array items: $ref: '#/components/schemas/Shift' errors: description: Array of errors for each shift that failed to update type: array items: type: object properties: shift_id: type: integer example: 1235123 error: type: string example: The end time must happen after the start time. code: type: integer example: 2165 /2/shifts/{id}/swapusers: get: summary: List swap users description: 'Fetch a list of elgible users that can take this dropped shift. The ID of the shift can be specified in the path or query string. ' tags: - Shifts parameters: - name: id in: path description: The ID of the shift being dropped schema: type: integer optional: true - name: id in: query description: The ID of the shift being dropped schema: type: integer optional: true - name: count in: query description: Flag to indicate if only a count of eligible takers should be returned schema: type: integer default: false - name: ids_only in: query description: Flag to indicate if only the IDs of the eligible takers should be returned schema: type: integer default: false responses: '200': description: Valid content: application/json: schema: type: object properties: can_release: type: boolean description: Indicates if this shift can be released users: oneOf: - type: array items: $ref: '#/components/schemas/User' - type: array items: type: string count: type: int description: A count of all the eligible takers optional: true examples: Full Users Response: summary: Example response for the default behavior value: can_release: true users: - id: 10 first_name: John last_name: doe User IDs Response: summary: Example response when passing the `ids_only` query param value: can_release: true users: - '12342' - '235234' - '235234' User Count Reponse: summary: Example response when passing the `count` query param value: can_release: false count: 0 /v3/auto-assign: openapi: 3.0.0 get: summary: List Auto Scheduled shifts parameters: - in: query description: The start range of the auto-schedule window required: true name: start example: Sun Nov 17 2019 00:00:00 GMT-0600 schema: type: string format: date-time - in: query description: The end range of the auto-schedule window required: true name: end example: Sun Nov 17 2019 00:00:00 GMT-0600 schema: type: string format: date-time - in: query description: Comma separated list of openshift ids to include in auto schedule algorithm required: true name: ids example: 1,2 schema: type: string format: csv - in: query description: The schedule (location) to include in auto schedule algorithm required: true name: location example: '2' schema: type: string - in: query description: The maximum hours any individual can be assigned per week, defaults to 40 required: false name: autoScheduleMaxHours example: 40 schema: type: integer - in: query description: Instruct algorithm to avoid unavailable preferences, defaults to true required: false name: autoScheduleUnavailability example: true schema: type: boolean - in: query description: Instruct algorithm to respect preferences, defaults to false required: false name: autoSchedulePreferredTimes example: false schema: type: boolean - in: query description: Instruct algorithm to allow multiple shifts per day, defaults to false required: false name: autoScheduleMultiShifts example: false schema: type: boolean - in: query description: The maximum hours any individual can be assigned per day required: false name: autoScheduleMaxDailyHours example: 9 schema: type: integer - in: query description: A randomization seed to get predictable assignment results required: false name: seed example: 1 schema: type: integer - in: query description: Instruct algorithm to prioritize weekend shifts (5pm Fri to 11:59pm Sun) during assignment, defaults to false required: false name: autoScheduleWeekendShifts example: true schema: type: boolean - in: query description: Comma separated list of user ids to exclude in auto schedule algorithm required: false name: excludedUserIds example: 1,2 schema: type: string format: csv description: Autoschedule a list of OpenShifts tags: - Shifts responses: '200': description: Valid content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/schemas-Shift' '400': description: Bad Request occurs if start/end is in an invalid format content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Chain: type: object required: timezone_id properties: 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. ' type: string format: iso8601 example: '2024-07-29T05:00:00Z' 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. ' type: int example: 2 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 | ' type: int example: 31 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). ' type: - string - int example: America/Chicago ShiftChain: type: object properties: key: type: string rrule: description: The RFC5545-compliant RRule representing the shift chain. type: string format: RFC5545 example: 'DTSTART;TZID=America/Chicago:20240603T090000 RRULE:FREQ=WEEKLY;UNTIL=20240629T045959Z;WKST=SU;BYDAY=MO,TU,WE,TH,FR ' until: description: The date when the shift chain ends. type: string format: date week: description: Represents the week frequency interval. `1` means weekly, `2` means every two weeks, etc. type: int example: 1 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 | ' type: int example: 31 timezone_id: description: The timezone this chain is built in type: string example: America/Chicago count: deprecated: true description: The number of shifts created by this chain. type: int example: 30 V2Error: type: object required: - error properties: error: type: string description: A description of the specific error code: oneOf: - type: integer - type: string description: The API error code ShiftBulk: type: object required: - id - start_time - end_time - location_id properties: id: type: integer example: 10000 account_id: type: integer example: 10000 user_id: type: integer example: 101 description: The user assigned to the shift. Set to `0` for an Open Shift. location_id: type: integer example: 1045 description: Location the shift belongs to position_id: type: integer example: 19483 site_id: type: integer example: 4351 start_time: type: string format: date-time example: Mon, 08 May 2023 08:30:00 -0600 end_time: type: string format: date-time example: Mon, 08 May 2023 14:30:00 -0600 break_time: type: double example: 0.5 color: type: string example: cc000 description: Assign color to shift notes: type: string example: Shift test description: Text notation for a Shift linked_users: type: array items: type: integer default: null description: Array of user IDs that can take this openshift. Null means all users are eligible. published: type: boolean example: false description: Is the shift published is_open: type: boolean example: false requires_openshift_approval: description: Does this shift require OpenShift Approval type: boolean example: true is_shared: description: Is the shift a shared OpenShift type: boolean example: false Error: type: object required: - error properties: error: type: object required: - code - title properties: code: description: The API error code type: string title: description: The API error code description type: string errorData: description: Context for the error BaseScheduledBreak: type: object required: - length - paid properties: id: example: 1234 type: integer description: ID of the break. Provide in the request when updating an existing break. account_id: example: 1234 type: integer readOnly: true length: example: 1800 description: The length of the break (seconds). type: integer paid: description: Whether the break is a paid rest break (true) or unpaid meal break (false) type: boolean sort: type: integer 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. readOnly: true created_at: description: Date and time the break was created at. type: string readOnly: true created_by: description: The id of the user who created the break. type: integer readOnly: true updated_at: description: Date and time the break was last updated. type: string readOnly: true updated_by: description: The id of the user who last edited the break. type: integer readOnly: true Shift: type: object required: - start_time - end_time - location_id properties: id: type: integer readOnly: true example: 10000 account_id: type: integer example: 10000 user_id: type: integer example: 101 description: The user assigned to the shift. Set to `0` for an Open Shift. location_id: type: integer example: 1045 description: Location the shift belongs to position_id: type: integer example: 19483 site_id: type: integer example: 4351 start_time: type: string format: date-time example: Mon, 08 May 2023 08:30:00 -0600 end_time: type: string format: date-time example: Mon, 08 May 2023 14:30:00 -0600 break_time: type: double example: 0.5 description: Length of the unpaid breaks for the shift in hours. 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. type: array items: $ref: '#/components/schemas/ShiftScheduledBreak' color: type: string example: cc000 description: Assign color to shift notes: type: string example: Shift test description: Text notation for a Shift alerted: type: boolean example: false description: Is the shift Alert sent linked_users: type: array items: type: integer default: null description: Array of user IDs that can take this openshift. Null means all users are eligible. shiftchain_key: type: string example: 1eizfwp description: The ID to associate shifts in a repeating pattern published: type: boolean example: false description: Is the shift published published_date: type: string format: date-time example: Mon, 01 May 2023 08:30:00 -0600 notified_at: type: string format: date-time example: Mon, 01 May 2023 08:32:00 -0600 instances: type: integer example: 3 default: null created_at: type: string format: date-time example: Mon, 24 Apr 2023 07:30:00 -0600 updated_at: type: string format: date-time example: Wed, 26 Apr 2023 11:30:00 -0600 acknowledged: type: boolean example: 0 description: If enabled; When the user confirmed the shift acknowledged_at: type: string format: date-time example: Fri, 21 Apr 2023 13:30:00 -0600 description: If enabled; When the user confirmed the shift creator_id: type: integer example: 101 description: The user that created the shift is_open: type: boolean example: false requires_openshift_approval: description: Does this shift require OpenShift Approval type: boolean example: true openshift_approval_request_id: description: ID of the associated OpenShift Approval request type: integer example: 5232 readOnly: true is_approved_without_time: description: Used to indicate that a manager or supervisor has approved a missing time entry for this shift type: boolean example: false readOnly: true is_shared: description: Is the shift a shared OpenShift type: boolean example: false is_trimmed: description: Is rounding active for shift type: boolean example: false User: properties: account_id: description: ID of the primary account for this user. type: integer activated: description: Whether the manager has activated this user. type: boolean email: description: The email address of this user. format: email type: string 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. ' type: string first_name: description: The first name of this user. type: string 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. ' format: float type: number hours_max: description: 'The max hours that this user prefers to work. A manager may still schedule the user beyond this value. ' format: float type: number hours_preferred: description: The preferred number of hours for this user to work. format: float type: number id: description: Unique identifier for the user. type: integer is_deleted: description: Whether the user has been deleted. type: boolean is_hidden: description: Whether the user has been hidden from the scheduler. type: boolean is_payroll: description: 'Whether the user has access to payroll. (Only available for managers and supervisors.) ' type: boolean is_private: description: 'Whether the user has privacy enabled, which will hide their contact details from other employees. Supervisors+ can not hide their email/phone from other employees. ' type: boolean is_trusted: description: Whether the user can edit their own timesheet. type: boolean last_login: description: The date and time when this user last logged in. format: date-time type: string last_name: description: The last name of this user. type: string locations: description: An array of location IDs to be applied to this user. items: type: integer type: array login_id: description: Unique identifier for the login belonging to the user. type: integer notes: description: Notes about this user. Visible only to supervisors+. type: string phone_number: description: The phone number of this user. type: string positions: description: An array of position IDs to be assigned to this user. items: type: integer type: array role: description: The user's role. enum: - 1 = Admin - 2 = Manager - 3 = Employee (Default) - 4 = Lead (Unused) - 5 = Supervisor type: integer type: description: 'A bitwise flag representing additional wage options: 1 = hourly employee 2 = salaried employee 4 = Exempt from overtime ' type: integer type: object OpenShiftApprovalRequest: type: object properties: id: description: The ID of the OpenShift Approval Request type: integer example: 1 readOnly: true account_id: description: The ID of the account that this OpenShift Approval Request belongs to type: integer example: 1 shift_id: description: The ID of the shift that this OpenShift Approval Request is for type: integer example: 1 shift: $ref: '#/components/schemas/Shift' creator_id: description: The ID of the user that created this request type: integer example: 1 readOnly: true updater_id: description: The ID of the user that last updated this request type: integer example: 1 readOnly: true status: description: The current status of the OpenShift Approval Request. type: integer enum: - 0 = Pending - 1 = Approved - 4 = Canceled - 5 = Expired - 6 = Denied example: 0 user_status: description: Copy of the status field to mirror the data model of other request types example: 0 is_shared: description: Is this approval request shared across schedules type: boolean example: false created_at: type: string format: date-time example: Thu, 06 Mar 2016 21:12:14 -0600 updated_at: type: string format: date-time example: Thu, 06 Mar 2016 22:17:14 -0600 readOnly: true user_requests: type: array items: $ref: '#/components/schemas/OpenShiftApprovalRequestUser' readOnly: true ShiftScheduledBreak: allOf: - $ref: '#/components/schemas/BaseScheduledBreak' - type: object properties: shift_id: type: integer example: 1234 description: The ID of the shift that the break applies to. readOnly: true start_time: example: Mon, 08 May 2023 9:30:00 -0600 description: The start time of the break. Null if the break does not have a start time. type: string end_time: example: Mon, 08 May 2023 10:00:00 -0600 description: The end time of the break. Null if the break does not have an end time. Calculated from the start time of the break and the length. type: string readOnly: true ShiftHistory: type: object required: - start_time - end_time - location_id properties: type: description: The type of history event type: string enum: - current - created - confirmed - published - unpublished - reassigned - taken - deleted - location_changed - position_changed - position_removed - site_removed - site_changed - break_changed - break_removed - time_changed - accepted - released example: current attributes: type: object required: - actor - at properties: actor: type: string description: The name of the user that triggered this shift history event at: type: string format: date-time example: Fri, 07 Mar 2016 08:30:00 -0600 description: The timestamp of when this shift history event was recorded reason: type: string example: edit description: A reason code to provide additional context for why a shift history event was recorded enum: - assign - take - delete - split - swap - drop - edit - assign-approve - repeating-delete - overwrite-conflicts-delete - deleted-assigned-user - user-removed-from-schedule - created-from-repeating-series - updated-from-repeating-series - publish - unpublish - delete-bulk - delete-clear user: type: string description: Present in `current`, `created`, `reassigned`, `taken`, `accepted` and `released` events. The new user assigned to the shift. example: John Doe start: type: string format: date-time description: Present in `current`, `created`, and `time_changed` events. The new start time. end: type: string format: date-time description: Present in `current`, `created`, and `time_changed` events. The new end time. position: type: string description: Present in `current`, `created`, `position_changed` and `position_removed` events. The new position. site: type: string description: Present in `current`, `created`, `site_changed` and `site_removed` events. The new site. break: type: float description: Present in `created`, `current`, `break_changed` and `break_removed` events . The new value of shift break. example: 15 OpenShiftApprovalRequestUser: type: object properties: id: description: The ID of the OpenShift Approval Request type: integer example: 1 user_id: description: The ID of the user that raised their hand for this request type: integer example: 1 created_at: type: string format: date-time example: Thu, 06 Mar 2016 21:12:14 -0600 readOnly: true deleted_at: type: string format: date-time example: Thu, 06 Mar 2016 22:17:14 -0600 readOnly: true schemas-Shift: type: object required: - startTime - endTime - locationId properties: id: type: integer readOnly: true example: 10000 accountId: type: integer example: 10000 userId: type: integer example: 101 description: The user assigned to the shift. Set to `0` for an Open Shift. locationId: type: integer example: 1045 description: Location the shift belongs to positionId: type: integer example: 19483 siteId: type: integer example: 4351 startTime: type: string format: date-time example: '2017-10-23T05:00:00+00:00' endTime: type: string format: date-time example: '2017-10-23T13:00:00+00:00' breakTime: type: float example: 0.5 color: type: string example: cc0000 alerted: type: bool example: false shiftchainKey: type: string published: type: bool example: true notifiedAt: type: string format: date-time example: '2017-10-23T19:18:01+00:00' createdAt: type: string format: date-time example: '2017-10-23T19:17:59+00:00' updatedAt: type: string format: date-time example: '2017-10-23T19:18:00+00:00' acknowledged: type: bool example: false instances: type: integer example: 1 requestBodies: ShiftRequest: description: Shift data content: application/json: schema: oneOf: - allOf: - $ref: '#/components/schemas/Shift' - type: object properties: chain: $ref: '#/components/schemas/Chain' - type: array items: allOf: - $ref: '#/components/schemas/Shift' - type: object properties: chain: $ref: '#/components/schemas/Chain' ShiftUnassignRequest: content: application/json: schema: type: object properties: shift_ids: description: Array of shift IDs type: array items: type: string example: '555555' BulkEditShiftRequest: content: application/json: schema: description: Array of shift objects to update type: array items: $ref: '#/components/schemas/ShiftBulk' ShiftPublish: content: application/json: schema: type: object properties: ids: type: array items: type: integer example: - 878787 - 656565 description: List of shift IDs ShiftNotifyRequest: content: application/json: schema: type: object required: - start - end properties: all: type: boolean value: true description: Should notifications be sent for all matching shifts, or only new and/or changed shifts since last notification. start: type: string format: date-time example: '2020-10-03T22:00:00.000Z' description: The start of the date range of shifts for which to send notifications end: type: string format: date-time example: '2020-10-10T21:59:56.999Z' description: The end of the date range of shifts for which to send notifications location_id: type: integer example: 9 description: The location (schedule) with shifts to send notifications. If not set, all locations will be included. message: type: string example: hello world description: A custom message to send with the shift notifications position_ids: type: array items: type: integer example: 12342 description: Limit schedule notifications to only shifts tagged to the given position IDs. Defaults to all positions. example: [] site_ids: type: array items: type: integer example: 512352 description: Limit schedule notifications to only shifts tagged to the given site IDs. Defaults to all sites. example: [] user_ids: type: array items: type: integer example: 231523 description: Limit schedule notifications to only shifts tagged to the given user IDs. Defaults to all users. example: [] ShiftAssignRequest: content: application/json: schema: type: object properties: user_ids: description: Array of user IDs type: array items: type: string example: '555555' SingleShiftNotifyRequest: content: application/json: schema: type: object properties: message: type: string example: hello world description: A custom message to send with the shift notifications. securitySchemes: W-Token: type: http scheme: bearer bearerFormat: JSON Web Token description: "Authentication with When I Work is based on a token model using [JSON Web Tokens](https://jwt.io/). First, you authenticate using a private developer key and the username and password of a When I Work user. Your developer key can be used like the following in the headers.\n```\ncurl -X POST \\\n https://api.login.wheniwork.com/login \\\n -H 'W-Key: ' \\\n -H 'content-type: application/json' \\\n -d '{\"email\":\"\",\"password\":\"\"}'\n```\n\nAuthenticating returns back a person object containing a token that is used to authenticate all future requests. You can now use this token to fetch all the users tied to your person. The token may be included in the headers, as a cookie, or in the query string using the key ‘W-Token’ or ‘Authorization’. If the authenticated user belongs to more than one Workplace you will need to get the User listing to obtain the user-id value\n```\ncurl -X GET \\\n 'https://api.wheniwork.com/2/login?show_pending=true' \\\n -H 'Host: api.wheniwork.com' \\\n -H 'Authorization: Bearer '\n```\n\nThe response will also include a listing of the user objects related to the person for each associated When I Work account. You can use the user ID to set the context for which account you will be acting upon by providing a When I Work user ID through the ‘W-UserID’ header.\n```\ncurl -X GET \\\n https://api.wheniwork.com/2/users \\\n -H 'Authorization: Bearer ' \\\n -H 'W-UserId: '\n```\nWhen I Work protects our application and API with rate limiting thresholds. Rate limiting utilizes thresholds based on rolling windows of time. Typical responses will be 403 level client side errors when encountering these limits. If you suspect you are encountering one of our thresholds please connect with our Customer Care team at support@wheniwork.com.\n\nYou can find additional authentication related API documentation in our [Login Service API docs](https://apidocs.wheniwork.com/external/index.html?repo=login).\n"