When I Work Users API

openapi: 3.0.3
info:
  version: 1.0.0
  title: When I Work API Documentation Accounts Users 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: Users
  description: 'A person on the When I Work platform is associated with a two tier record.   The persons email/password is associated to a person_id.

    For each Workplace the person belongs to a user_id record exists. This record links back to the person_id so only a single instance of the email/password exists. If a user updates their email or password this applies to all related instances of the user.


    For more information about Users, visit the [Help Center](https://help.wheniwork.com/articles/user-access-privileges-computer/).

    '
paths:
  /2/users:
    get:
      summary: List Users
      description: List all the users in your account
      tags:
      - Users
      parameters:
      - in: query
        name: location_id
        schema:
          type: array
          items:
            type: integer
          minItems: 1
        style: form
        explode: false
        example: 4
      - name: show_pending
        in: query
        description: Include pending users in results. Defaults to true.
        schema:
          type: boolean
          example: true
      - name: only_pending
        in: query
        description: Include ONLY pending users in results. Defaults to false.
        schema:
          type: boolean
          example: false
      - name: show_deleted
        in: query
        description: 'Include deleted users in results. Defaults to false. Requires administrator, manager, or supervisor access (enforced via can_supervise()); otherwise the request returns 403.

          '
        schema:
          type: boolean
          example: false
      - name: only_deleted
        in: query
        description: 'Only include deleted/archived users in results. Defaults to false. Requires administrator, manager, or supervisor access (enforced via can_supervise()); otherwise the request returns 403.

          '
        schema:
          type: boolean
          example: false
      - name: search
        in: query
        description: Optional string to search by in users first name, last name, or email.
        schema:
          type: string
          example: ''
      x-code-samples:
      - lang: shell
        source: 'curl https://api.wheniwork.com/2/users \

          -H "W-Token: ilovemyboss"

          '
      responses:
        '200':
          description: Valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/components-schemas-User'
    post:
      summary: Create User
      description: Used to create a user
      tags:
      - Users
      requestBody:
        $ref: '#/components/requestBodies/UserRequest'
      responses:
        '200':
          description: Valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/components-schemas-User'
  /2/users/{id}:
    get:
      summary: Get User
      description: Get a single user by ID
      tags:
      - Users
      parameters:
      - name: id
        in: path
        description: The ID of the user
        schema:
          type: integer
        required: true
      x-code-samples:
      - lang: shell
        source: "curl https://api.wheniwork.com/2/users/4364 \\\n -H \"W-Token: ilovemyboss\"\n"
      responses:
        '200':
          description: Valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/components-schemas-User'
    put:
      summary: Update User
      description: Updates a single user
      tags:
      - Users
      parameters:
      - name: id
        in: path
        description: The ID of the user
        schema:
          type: integer
        required: true
      requestBody:
        $ref: '#/components/requestBodies/UpdateUserRequest'
      responses:
        '200':
          description: Valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/components-schemas-User'
    delete:
      summary: Delete User
      description: Delete an existing user. This action can be reversed.
      tags:
      - Users
      parameters:
      - name: id
        in: path
        description: The ID of the user
        schema:
          type: integer
        required: true
      - name: deleted_shifts
        in: query
        description: Indicates whether or not to delete this user's future shifts. If not deleted, those shifts will be moved to Open Shifts.
        schema:
          type: boolean
          example: false
      responses:
        '200':
          description: Valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
  /2/users/avatar/{id}:
    post:
      summary: Create/Update user avatar
      description: Used to create and update a user's avatar
      tags:
      - Users
      parameters:
      - name: id
        in: path
        description: The ID of the user whose avatar is being uploaded
        schema:
          type: integer
        required: true
      - name: content-type
        in: header
        description: The type of content being uploaded
        type: string
        example: image/jpeg
      requestBody:
        $ref: '#/components/requestBodies/AvatarRequest'
      responses:
        '200':
          description: Valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      hash:
                        type: string
                        example: df8ace3aeae0f582d05628708a0e555c81bf57af
                      type:
                        type: string
                        example: jpg
                      sizes:
                        type: array
                        items:
                          type: string
                        example:
                        - small
                        - medium
                        - large
                      createdAt:
                        type: string
                        format: date-time
                        example: '2019-12-17T15:58:45.562887004Z'
                      updatedAt:
                        type: string
                        format: date-time
                        example: '2019-12-17T15:58:45.562887004Z'
  /2/users/bulkupdate:
    post:
      summary: Create A Batch of Users
      description: Used to create a user, limit of 50 users at a time to prevent long requests
      tags:
      - Users
      requestBody:
        $ref: '#/components/requestBodies/BulkUserRequest'
      responses:
        '200':
          description: Valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/BulkUserResponse'
  /2/users/profile:
    get:
      summary: Get User Profile
      description: Get the logged in user's profile
      tags:
      - Users
      x-code-samples:
      - lang: shell
        source: "curl https://api.wheniwork.com/2/users/profile \\\n -H \"W-Token: ilovemyboss\"\n"
      responses:
        '200':
          description: Valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/components-schemas-User'
    post:
      summary: Update User Profile
      description: 'Update the logged in user''s profile.

        > Although managers and supervisors are able to change most profile information through the Update Existing User endpoint, this is the only way for an employee to change their own information using the API.

        '
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  example: John
                  description: The first name of the user.
                last_name:
                  type: string
                  example: Doe
                  description: The last name of the user.
                phone_number:
                  type: string
                  example: 16511234567
                  description: The phone number of the user
                email:
                  type: string
                  example: jdoe@wheniwork.com
                  description: The email address of the user.
                is_private:
                  type: boolean
                  example: false
                  description: Whether the user has privacy enabled, which will hide their contact details from other employees (excluding supervisors and managers).
      responses:
        '200':
          description: Valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/components-schemas-User'
  /2/users/alerts:
    post:
      summary: Update User Alert Settings
      description: Update the logged in user's alert settings
      tags:
      - Users
      requestBody:
        $ref: '#/components/requestBodies/UserAlertsRequest'
      responses:
        '200':
          description: Valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
  /2/users/invite:
    post:
      summary: Invite users
      description: Users can be invited by managers, or by supervisors. This will send them an email or text message inviting them to register.
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: integer
                  example:
                  - 1
                  - 2
                  - 3
                  description: List of existing user IDs to invite.
                send_all:
                  type: boolean
                  description: Whether to invite all users who do not currently have a login/person. If this is `true`, the `ids` parameter will be ignored. Defaults to false.
                  example: false
                message:
                  type: string
                  description: An optional message to include in the email invite.
                  example: Welcome to the company!
      responses:
        '200':
          $ref: '#/components/responses/InviteUserResponse'
  /2/users/invite/{id}:
    post:
      summary: Invite single user
      description: A user can be invited by managers, or by supervisors. This will send them an email or text message inviting them to register.
      tags:
      - Users
      parameters:
      - name: id
        in: path
        description: The ID of the user to invite
        schema:
          type: integer
        required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: An optional message to include in the email invite.
                  example: Welcome to the company!
      responses:
        '200':
          $ref: '#/components/responses/InviteUserResponse'
components:
  schemas:
    BulkUserResponse:
      description: Response for both Valid/Invalid requests
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
                description: The total number of invites sent.
                example: 3
              validRows:
                row:
                  type: integer
                  description: The total number of invites sent.
                  example: 3
                user:
                  $ref: '#/components/schemas/User'
              invalidRows:
                row:
                  type: integer
                  description: The total number of invites sent.
                  example: 3
                user:
                  $ref: '#/components/schemas/User'
              locations:
                type: array
                items:
                  type: integer
                example:
                - 1
                - 2
                - 3
                description: An array of locations (schedules) assigned to this user.
              success:
                type: boolean
                description: True if at least one invite was sent.
                example: true
    AlertSetting:
      type: object
      properties:
        sms:
          type: boolean
          example: true
          description: Whether or not SMS messages should be sent for events of this alert type.
        email:
          type: boolean
          example: true
          description: Whether or not email messages should be sent for events of this alert type.
        alerts:
          type: boolean
          example: true
          description: Whether or not push notifications should be sent for events of this alert type.
        in_app:
          type: boolean
          example: true
          description: Whether or not in-app notifications should be sent for events of this alert type.
        badge_icon:
          type: boolean
          example: true
          description: Whether or not banner notifications (iOS only) should be sent for events of this alert type.
    components-schemas-User:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          example: 10000
          description: Unique identifier for the user
        login_id:
          type: integer
          example: 10000
          readOnly: true
          description: Unique identifier for the person/login belonging to the user.
        account_id:
          type: integer
          example: 10000
          readOnly: true
          description: ID of the account for this user.
        role:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 5
          description: "The user's role:\n * `1` - Admin\n * `2` - Manager\n * `3` - Employee (Default)\n * `5` - Supervisor\n"
        email:
          type: string
          example: jdoe@wheniwork.com
          description: The email address of the user.
        first_name:
          type: string
          example: John
          description: The first name of the user.
        middle_name:
          type: string
          example: Alan
          description: The middle name of the user.
        last_name:
          type: string
          example: Doe
          description: The last name of the user.
        phone_number:
          type: string
          example: 16511234567
          description: The phone number of the user
        employee_code:
          type: string
          example: 1234
          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.

            '
        activated:
          type: boolean
          example: true
          readOnly: true
          description: Indicates of a manager has activated (accepted a pending user) this user.
        notes:
          type: string
          example: Excellent employee
          description: Notes about this user. (Only viewable by supervisors and managers).
        hours_max:
          type: number
          format: float
          example: 40
          description: The max hours that this user can work.
        hourly_rate:
          type: number
          format: float
          example: 15
          description: The hourly rate for this user. (Only viewable by managers and supervisors that can do payroll).
        position_rates:
          type: object
          example:
            '1001': 2
            '1002': 3.5
          description: "A mapping of position IDs to the user's hourly rate for that position. The rates here are applied on\ntop of the user's base hourly rate (see hourly_rate). A user with an hourly rate of 15 and a position rate \nof 1 for position 1001 would result in an hourly rate of 16 for position 1001. (Only viewable by managers \nand supervisors that can do payroll).\n"
        type:
          type: integer
          example: 5
          description: "Use the `employment_type` property instead.\nA bitwise flag representing additional wage options:\n * `1` - Hourly employee\n * `2` - Salaried employee\n * `5` - Exempt from overtime.\n"
          deprecated: true
        employment_type:
          type: string
          enum:
          - hourly
          - hourly_exempt
          - salaried *
          - salaried_exempt *
          - shareholder *
          description: Employment type of the user. *These options are only available to payroll customers
        last_login:
          type: string
          format: date-time
          example: '2019-05-23T23:59:59+05:00'
          readOnly: true
          description: The date and time when this user last logged in.
        positions:
          type: array
          items:
            type: integer
          example:
          - 1
          - 2
          - 3
          description: An array of positions assigned to this user.
        locations:
          type: array
          items:
            type: integer
          example:
          - 1
          - 2
          - 3
          description: An array of locations (schedules) assigned to this user.
        is_deleted:
          type: boolean
          example: false
          readOnly: true
          description: Whether the user has been deleted.
        is_hidden:
          type: boolean
          example: false
          description: Whether the user has been hidden from the scheduler.
        is_payroll:
          type: boolean
          example: false
          description: Whether the user has access to payroll. (Only available for managers and supervisors).
        is_private:
          type: boolean
          example: false
          description: Whether the user has privacy enabled, which will hide their contact details from other employees (excluding supervisors and managers).
        is_trusted:
          type: boolean
          example: false
          description: Whether the user can edit their own timesheet.
        created_at:
          readOnly: true
          type: string
          format: date-time
          example: '2019-05-16T06:57:28+05:00'
        updated_at:
          readOnly: true
          type: string
          format: date-time
          example: '2019-05-16T06:57:28+05:00'
        start_date:
          type: string
          format: date
          example: '2019-05-16'
          description: yyyy-mm-dd formatted date for when the user started their employment
    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
  requestBodies:
    BulkUserRequest:
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/components-schemas-User'
            - type: object
              properties:
                invite:
                  type: boolean
                  example: false
                  description: Whether an invite should be sent upon user creation. When missing or not false, an invite is sent by default
      description: The user data
    AvatarRequest:
      content:
        image/*:
          schema:
            type: string
            format: binary
    UpdateUserRequest:
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/components-schemas-User'
            - type: object
              properties:
                reactivate:
                  type: boolean
                  example: true
                  description: Whether to reactivate a previously deleted user.
      description: The user data to update
    UserAlertsRequest:
      content:
        application/json:
          schema:
            type: object
            properties:
              timeoff:
                $ref: '#/components/schemas/AlertSetting'
                description: Whether the user wishes to receive alerts when the status of a time off request changes.
              swaps:
                $ref: '#/components/schemas/AlertSetting'
                description: Whether the user wishes to receive alerts when the status of a swap or drop request changes.
              schedule:
                $ref: '#/components/schemas/AlertSetting'
                description: Whether the user wishes to receive alerts when the schedule changes.
              reminders:
                $ref: '#/components/schemas/AlertSetting'
                description: Whether the user wishes to receive alerts for reminders prior to shifts.
              availability:
                $ref: '#/components/schemas/AlertSetting'
                description: Whether the user wishes to receive alerts for changes in availability.
              new_employee:
                $ref: '#/components/schemas/AlertSetting'
                description: Whether the user wishes to receive alerts when a new employee is added.
              attendance:
                $ref: '#/components/schemas/AlertSetting'
                description: Whether the user wishes to receive alerts for attendance-related events.
              workchat:
                $ref: '#/components/schemas/AlertSetting'
                description: Whether the user wishes to receive alerts when new workchat messages are received and how they are notified.
              reminder_time:
                type: number
                format: float
                description: Time before an event when a user should be sent notifications, in hours.
                example: 2
    UserRequest:
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/components-schemas-User'
            - type: object
              properties:
                invite:
                  type: boolean
                  example: false
                  description: Whether an invite should be sent upon user creation. When missing or not false, an invite is sent by default
      description: The user data
  responses:
    InviteUserResponse:
      description: Valid
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
                description: The total number of invites sent.
                example: 3
              email:
                type: integer
                description: The total number of invites sent via email.
                example: 3
              sms:
                type: integer
                description: The total number of invites sent via text message.
                example: 1
              success:
                type: boolean
                description: True if at least one invite was sent.
                example: 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"