When I Work Shift Requests API

openapi: 3.2.0
info:
  version: 1.0.0
  title: When I Work API Documentation Accounts Shift Requests 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: 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/).

    '
paths:
  /2/swaps:
    get:
      summary: Gets a collection of all shift requests.
      description: 'Get a collection of shift request objects. Swaps let users swap shifts with each

        other or drop shifts for other users to pick up.

        '
      parameters:
      - name: end
        description: 'End time for the shift search window. Must be included if start is defined.

          '
        example: '2017-07-21T17:32:28Z'
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: limit
        description: The number of shift requests to include per page.
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 10
      - name: open_only
        description: Whether only open swaps should be included in the results.
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: page
        description: The page of results to fetch.
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: shift_id
        description: 'The ID of the shift to get swaps for. For multiple shifts, enter a list of shift IDs separated by commas.

          '
        example: 1,5,3
        in: query
        required: false
        schema:
          type: array
          items:
            type: integer
      - name: start
        description: 'Start time for the shift search window. Must be included if end is defined.

          '
        example: '2017-07-21T17:32:28Z'
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: status
        description: 'The status or statuses of shift request that should be included in the

          results. For multiple statuses, enter a list separated by commas.


          Statuses available are:

          * `0` - Pending

          * `1` - Approved

          * `2` - Declined

          * `3` - Completed

          * `4` - Canceled

          * `5` - Expired

          '
        example: 4,5
        in: query
        required: false
        schema:
          type: array
          items:
            type: integer
      - name: type
        description: 'The type or types of shift requests that should be included in the results.

          For multiple types, enter a list separated by commas.


          Types available are:

          * `1` - Swap

          * `2` - Drop

          * `3` - Alert

          '
        example: 2,3
        in: query
        required: false
        schema:
          type: array
          items:
            type: integer
      - name: user_id
        description: 'The ID of the user to get shift requests for. For multiple users, enter a list of user IDs separated by commas.

          '
        example: 1,3,5
        in: query
        required: false
        schema:
          type: array
          items:
            type: integer
      responses:
        '200':
          description: Collection of shift request objects.
          content:
            application/json:
              schema:
                properties:
                  messages:
                    description: Array of message objects.
                    items:
                      $ref: '#/components/schemas/Message'
                    type: array
                  more:
                    description: Whether there are more pages of results.
                    type: boolean
                  page:
                    description: Current page of results.
                    type: integer
                  shifts:
                    description: Array of shift objects.
                    items:
                      $ref: '#/components/schemas/Shift'
                    type: array
                  swaps:
                    description: Array of shift request objects.
                    items:
                      $ref: '#/components/schemas/Swap'
                    type: array
                  total:
                    description: Total number of shift requests in result set.
                    type: integer
                  users:
                    description: Array of user objects.
                    items:
                      $ref: '#/components/schemas/User'
                    type: array
      tags:
      - Shift Requests
    post:
      summary: Create a new shift request.
      requestBody:
        content:
          application/json:
            schema:
              properties:
                shift_id:
                  description: ID of the shift being swapped or dropped.
                  type: integer
                shifts:
                  description: The IDs of the shifts requested to be swapped for.
                  items:
                    type: integer
                  type: array
                type:
                  description: "Type of shift request to be created. Note: If using type `3` it should be created as a \nmanager looking for find a replacement for a shift.\n* `1` - Swap\n* `2` - Drop\n* `3` - Alert\n"
                  enum:
                  - 1
                  - 2
                  - 3
                  type: integer
                users:
                  description: The IDs of users available to take shifts.
                  items:
                    type: integer
                  type: array
              type: object
        description: Shift request to create.
      responses:
        '201':
          description: The swap was created.
      tags:
      - Shift Requests
  /2/swaps/{swap_id}:
    parameters:
    - name: swap_id
      description: ID of the swap being requests.
      in: path
      required: true
      schema:
        type: integer
    delete:
      summary: Delete the given shift request.
      responses:
        '200':
          description: The swap was deleted.
      tags:
      - Shift Requests
    get:
      summary: Get the details of a specific shift request.
      description: 'Get a single shift request object. Shift requests let users swap shifts with each other or

        drop shifts for other users to pick up.

        '
      responses:
        '200':
          description: Collection of shift request objects.
          content:
            application/json:
              schema:
                properties:
                  messages:
                    description: Array of message objects.
                    items:
                      $ref: '#/components/schemas/Message'
                    type: array
                  shifts:
                    description: Array of shift objects.
                    items:
                      $ref: '#/components/schemas/Shift'
                    type: array
                  swap:
                    $ref: '#/components/schemas/Swap'
                  users:
                    description: Array of user objects.
                    items:
                      $ref: '#/components/schemas/User'
                    type: array
      tags:
      - Shift Requests
    put:
      summary: Update a shift request.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Swap'
        description: Updated shift request.
      responses:
        '200':
          description: Update was successful.
      tags:
      - Shift Requests
components:
  schemas:
    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
    Message:
      properties:
        account_id:
          description: The account ID that the message is associated with.
          type: integer
        actor:
          description: "Who or what generated the message.\n* `0` - user generated (message was generated directly by a user's\n  actions; their userid is recorded on the message object)\n* `1` - automatically (system took action automatically; usually\n  auto-approved or expired a request)\n* `2` - shift modification (a shift change triggered the message)\n* `3` - all recipients (all recipients declined the request)\n"
          enum:
          - 0
          - 1
          - 2
          - 3
          type: integer
        content:
          description: The content of the message.
          type: string
        conversation_id:
          description: 'Deprecated. The ID of the conversation the message is a part of,

            replaced by either request_id or swap_id.

            '
          type: integer
        created_at:
          description: Date at which the message was created.
          format: date-time
          type: string
        id:
          description: The unique ID of the message.
          type: integer
        request_id:
          description: 'The ID of the request the message is for. Either request_id OR swap_id

            are required.

            '
          type: integer
        swap_id:
          description: 'The ID of the swap the message is for. Either request_id OR swap_id are

            required.

            '
          type: integer
        title:
          description: The title of the message.
          type: string
        updated_at:
          description: Date the message was most recently updated.
          format: date-time
          type: string
        user_id:
          description: The ID of the user.
          type: integer
      type: object
    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
    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
    Swap:
      description: 'Shift requests let users swap shifts with each other or drop shifts for other users

        to pick up.

        '
      properties:
        accepted_id:
          description: For a drop request, will be the ID of the user who took the shift. For a swap request will be the ID of the shift being swapped for the shift already on the swap record.
          type: integer
        account_id:
          description: The ID of the account associated with the shift request.
          type: integer
        actionable:
          type: boolean
        allowed_statuses:
          description: 'Array of status values that the shift request can be transitioned to based on the

            role of the current user and their relationship to the request.

            '
          items:
            type: integer
          type: array
        canceled_id:
          type: integer
        completed_at:
          type: string
        created_at:
          description: Date and time the shift request was created at.
          type: string
        creator_id:
          description: ID of who created the shift request.
          type: integer
        id:
          description: The unique ID of the shift request.
          type: integer
        location_id:
          description: ID of the location.
          type: integer
        shift_id:
          description: ID of the shift.
          type: integer
        status:
          description: 'Status of the shift request.

            * `0` - Pending

            * `1` - Approved

            * `2` - Declined

            * `3` - Completed

            * `4` - Canceled

            * `5` - Expired

            '
          enum:
          - 0
          - 1
          - 2
          - 3
          - 4
          - 5
          type: integer
        statuses:
          description: An array of user shift acceptance statuses.
          items:
            properties:
              shift_id:
                type: integer
              status:
                type: integer
              user_id:
                type: integer
              user_status:
                type: integer
            type: object
          type: array
        type:
          description: 'Shift request types.

            * `1` - Swap

            * `2` - Drop

            * `3` - Alert

            '
          enum:
          - 1
          - 2
          - 3
          type: integer
        updated_at:
          type: string
        updater_id:
          type: integer
        user_id:
          description: The ID of the user who initiated the shift request.
          type: integer
        user_status:
          description: 'The user-facing status of the shift request.

            * `0` - Pending Approval

            * `1` - Pending Acceptance

            * `2` - Declined

            * `3` - Accepted

            * `4` - Canceled

            * `5` - Expired

            * `6` - Denied

            '
          type: integer
      type: object
    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
  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: <INSERT_DEVELOPER_KEY_HERE>' \\\n  -H 'content-type: application/json' \\\n  -d '{\"email\":\"<INSERT_USERNAME_HERE>\",\"password\":\"<INSERT_PASSWORD_HERE>\"}'\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 <INSERT_TOKEN_HERE>'\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 <INSERT TOKEN HERE>' \\\n  -H 'W-UserId: <INSERT_USER_ID_HERE>'\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"