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: ' \\\n -H 'content-type: application/json' \\\n -d '{\"email\":\"\",\"password\":\"\"}'\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 '\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 ' \\\n -H 'W-UserId: '\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"