When I Work Shifts API

openapi: 3.2.0
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 Schedul

# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/when-i-work/refs/heads/main/openapi/when-i-work-shifts-api-openapi.yml