When I Work Swaps API

openapi: 3.0.3
info:
  version: 1.0.0
  title: When I Work API Documentation Accounts Swaps 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: Swaps
paths:
  /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:
      - Swaps
      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
components:
  schemas:
    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
  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"