openapi: 3.0.3
info:
  version: 1.0.0
  title: When I Work API Documentation Accounts Import 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: Import
  description: "The import API is used to import a variety of When I Work resources from user-provided CSV or Excel files.\n\n### Import Types\n\nAll available import types and their columns are listed here. Where possible, the column names will align with names used elsewhere in the API, but this is not always possible.\n\n<table>\n   <thead>\n     <tr>\n       <th>type</th>\n       <th>columns</th>\n       <th>required?</th>\n       <th>notes</th>\n     </tr>\n   </thead>\n   <tbody>\n     <tr>\n       <td rowspan=\"5\" class=\"nowrap\"><code>SHIFT_TEMPLATE</code></td>\n       <td>start_time</td>\n       <td>✅</td>\n       <td></td>\n     </tr>\n     <tr>\n       <td>end_time</td>\n       <td>✅</td>\n       <td></td>\n     </tr>\n     <tr>\n       <td>schedule</td>\n       <td></td>\n       <td>\n         <p>A schedule name to associate with the shift template. If no schedule with that name exists, a new schedule will be created.</p>\n         <p>If omitted, the shift template will be assigned to all schedules (or the value \"All Schedules\" can be provided to do the same).</p>\n       </td>\n     </tr>\n     <tr>\n       <td>position</td>\n       <td></td>\n       <td>\n         <p>A position name to associate with the shift template. If no position with that name exists, a new position will be created.</p>\n       </td>\n     </tr>\n     <tr>\n       <td>unpaid_break</td>\n       <td></td>\n       <td>The length of the unpaid break in minutes.</td>\n     </tr>\n     <tr>\n       <td rowspan=\"12\" class=\"nowrap\"><code>EMPLOYEE</code></td>\n       <td>first_name</td>\n       <td>✅</td>\n       <td>First name of the employee</td>\n     </tr>\n     <tr>\n       <td>last_name</td>\n       <td>✅</td>\n       <td>Last name of the employee</td>\n     </tr>\n     <tr>\n       <td>email</td>\n       <td></td>\n       <td>The email address of the employee</td>\n     </tr>\n     <tr>\n       <td>employee_code</td>\n       <td></td>\n       <td>The employee code to associate with the employee</td>\n     </tr>\n     <tr>\n       <td>file_number</td>\n       <td></td>\n       <td>The file number corresponding to the employee in ADP</td>\n     </tr>\n     <tr>\n       <td>id</td>\n       <td></td>\n       <td>The user id corresponding to the employee in When I Work</td>\n     </tr>\n     <tr>\n       <td>location</td>\n       <td></td>\n       <td>\n         <p>A schedule (location) name to associate with the employee. If no schedule with that name exists, a new schedule will be created.</p>\n       </td>\n     </tr>\n     <tr>\n       <td>max</td>\n       <td></td>\n       <td>The maximum hours per week of the employee</td>\n     </tr>\n     <tr>\n       <td>phone</td>\n       <td></td>\n       <td>The phone number of the employee</td>\n     </tr>\n     <tr>\n       <td>position</td>\n       <td></td>\n       <td>\n         <p>A position name to associate with the employee. If no position with that name exists, a new position will be created.</p>\n       </td>\n     </tr>\n     <tr>\n       <td>tags</td>\n       <td></td>\n       <td>\n         <p>A comma separated list of tags to associate to the employee. If the tag does not exist, it will be created.</p>\n       </td>\n     </tr>\n     <tr>\n       <td>wage</td>\n       <td></td>\n       <td>\n         <p>The hourly rate of the employee expressed as a floating point number (e.g. 14.50)</p>\n       </td>\n     </tr>\n   </tbody>\n </table>\n"
paths:
  /2/import:
    post:
      summary: Create Import
      description: 'Uploads a user file, parses it, and returns information to help guide the import process.


        Note that unlike most API endpoints, this endpoint does not use JSON for the request body.

        '
      tags:
      - Import
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                type:
                  $ref: '#/components/schemas/ImportType'
                file:
                  type: string
                  format: binary
                  description: 'The user-provided file, in one of the following formats: XLS, XLSX, or CSV.

                    '
              required:
              - type
              - file
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Import'
  /2/import/{id}:
    get:
      summary: Get Import
      description: 'Gets an import in progress. Returns exactly the same content as the result of Create Import.

        '
      tags:
      - Import
      parameters:
      - name: id
        in: path
        description: The ID of the import to get
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Import'
  /2/import/{id}/preview:
    post:
      summary: Preview Import
      description: 'Given a set of column mappings, previews the result of the import.

        '
      tags:
      - Import
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                columns:
                  $ref: '#/components/schemas/ColumnMappingsRequest'
              required:
              - columns
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  validRows:
                    type: array
                    description: 'The rows of the spreadsheet for which there were no errors.

                      '
                    items:
                      type: object
                      properties:
                        row:
                          type: integer
                          description: The spreadsheet row from which this item was generated.
                        message:
                          type: string
                          description: An arbitrary description of the result of finalizing this row.
                    example:
                    - row: 2
                      message: 9a-5p at Downtown as Sales
                    - row: 8
                      message: 10a-6p at All Schedules as Cashier
                    - row: 3
                      message: End Time missing.
                  invalidRows:
                    type: array
                    description: 'The rows of the spreadsheet for which there were errors. No items will be

                      generated for any of these rows.

                      '
                    properties:
                      row:
                        type: integer
                        description: The spreadsheet row from which this item was generated.
                      message:
                        type: string
                        description: An arbitrary description of why the row was invalid.
                    example:
                    - row: 7
                      message: Unpaid Break must be less than or equal to shift length.
                  newObjects:
                    type: array
                    description: 'Descriptions of any new workplace objects that will be created as a result of this import.

                      '
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          description: An arbitrary description of a resource that will be created when the import is finalized.
                    example:
                    - message: 'Schedule: Downtown'
                    - message: 'Position: Cashier'
  /2/import/{id}/finalize:
    post:
      summary: Finalize Import
      description: 'Given a set of column mappings, finalizes the import.

        '
      tags:
      - Import
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                columns:
                  $ref: '#/components/schemas/ColumnMappingsRequest'
                extra:
                  description: 'Any extra data to use when finalizing the import; e.g. whether or not to send invites to

                    newly-created users when importing employees. The type of this field varies per resource; expand

                    the details of this field to learn more.

                    '
                  oneOf:
                  - $ref: '#/components/schemas/EmployeeExtra'
              required:
              - columns
              example:
                columns:
                  start_time: Start
                  end_time: End
                  position: null
      responses:
        '200':
          description: Import Finalized
          content:
            application/json:
              schema:
                type: object
                properties:
                  created:
                    type: object
                    properties:
                      positions:
                        type: array
                        description: 'The ids of positions that were created as a result of the import

                          '
                        items:
                          type: integer
                        example:
                        - 1
                        - 2
                        - 3
                      schedules:
                        type: array
                        description: 'The ids of positions that were created as a result of the import

                          '
                        items:
                          type: integer
                        example:
                        - 1
                        - 2
                        - 3
components:
  schemas:
    EmployeeExtra:
      type: object
      properties:
        invite:
          type: boolean
          description: 'Whether to send invitations to new employees.

            '
    ColumnMappingsRequest:
      type: object
      description: A mapping from When I Work column names to user column names. The keys should be When I Work column names that are valid for the current import's `type`; see the Import section documentation for details. The values should be the names of user-provided columns. If you do not wish to provide a value for a field, you may omit the field from the mapping or provide a value of `null`.
      additionalProperties:
        type:
        - string
        - null
      example:
        start_time: Start
        end_time: End
        position: null
    ImportType:
      type: string
      enum:
      - EMPLOYEE
      - SHIFT_TEMPLATE
      description: 'The type of resource to be imported. Determines the column names that appear throughout the process.


        A full list of accepted column names for each type can be found in the Import section documentation.

        '
      example: SHIFT_TEMPLATE
    Import:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          description: The import's ID
          example: abc123
        type:
          $ref: '#/components/schemas/ImportType'
          readOnly: true
        user_columns:
          type: array
          items:
            type: string
          readOnly: true
          description: The column names from the user's file.
          example:
          - Start
          - End
          - Schedule
          - Break
        suggested_matches:
          type: object
          additionalProperties:
            type:
            - string
            - null
            description: 'The suggested mapping from WIW property names to user column names. The keys of this object are the WIW property names, determined by the import''s `type`. The values are the user column names.


              A null value means no match was suggested, and you should prompt the user to provide the mapping if necessary.

              '
          example:
            start_time: Start
            end_time: End
            schedule: Schedule
            position: null
            unpaid_break: Break
  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"