openapi: 3.0.3 info: version: 1.0.0 title: When I Work API Documentation 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: Shifts description: 'Shifts provide the basis for scheduling. Many other objects, including Schedules (aka Locations), Positions, Sites, Users, Tasks, and Tags all link through Shifts. For more information about how to use Shifts, visit the [Help Center](https://help.wheniwork.com/article-categories/scheduling-your-team/). ' - name: Accounts description: 'Accounts (aka Workplaces) are objects that define a business account with When I Work. Each user is associated with an account enabling them to access Shifts or other data. For more information about Accounts, visit the [Help Center](https://help.wheniwork.com/article-categories/account-settings/). ' - 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/). ' - name: Positions description: 'Positions (aka, job or duty) are used to define labor allocation. Users can be tagged (associated) with one or more Positions. When I Work uses this association for shift eligibility, Alert notifications filtering and labor reporting. For more information about using Positions, visit the [Help Center](https://help.wheniwork.com/articles/creating-and-managing-positions-computer/). ' - name: Punch description: 'A punch is an event where a user clocks in or clocks out. Punches can be managed to restrict where an employee can clock in/out and from what devices. If a user forgets to clock out, they will be allowed to clock in after 9 hours from the end of their scheduled shift. If there is no scheduled shift, the user can clock in again after 18 hours from when they originally clocked in. ' - name: Schedules (Locations) description: 'Schedules are logical groupings of users that are working together. Schedules can be physical offices with addresses or logical groups like departments. Users can be tagged (associated) to one or more schedules. Schedules can be departments, facilities, business divisions or any grouping of staff. For more information about using Scheduled, visit the [Help Center](https://help.wheniwork.com/articles/creating-and-managing-schedules-computer/). ' - name: Sites description: "Sites communicate additional information about a given shift to the recipient. Typical usage is when you schedule\ \ employees for shifts that are at different physical sites (addresses) compared to the Schedule where the shift is assigned.\ \ A Job site can include additional detail (address or coordinates) that informs the user where this particular shift\ \ is to take place. An additional use case would be if you want to use an additional labor reporting tier and having the\ \ Job Site be a project or cost center value.\n\n For more information about using Sites, visit the [Help Center](https://help.wheniwork.com/articles/scheduling-shifts-at-job-sites-computer/).\n" - name: Shift Templates (Blocks) description: 'Shift templates save you time when you need to schedule shifts that have a consistent start and end time. Instead of manually entering in custom shift details one-by-one, shift templates allow you to schedule a shift quickly and easily. For more information about using Shift Templates, visit the [Help Center](https://help.wheniwork.com/articles/creating-and-managing-shift-templates-computer/). ' - name: Time Off Requests description: 'When you need to take time off from work, use When I Work to send the request to your manager for approval. Time off can be submitted as unpaid, paid (PTO), sick, or holiday. For more information about using Time Off Requests, visit the [Help Center](https://help.wheniwork.com/articles/requesting-time-off-computer/). ' - name: Request Type description: 'Types of time off that can be selected when submitting a time off request. For more information about using Time Off Requests, visit the [Help Center](https://help.wheniwork.com/articles/requesting-time-off-computer/). ' - 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/). ' - name: Availabilities description: 'Set your availability preferences to let your employer know when you prefer to work and when you prefer not to work. For more information about using Availabilities, visit the [Help Center](https://help.wheniwork.com/articles/setting-your-availability-computer/). ' - name: Schedule Templates description: 'Schedule templates allow you to create a daily or weekly schedule that is reusable. If your schedules are very similar from day to day or week to week, use a template to save time and avoid creating schedules from scratch. For more information about using Schedule Templates, visit the [Help Center](https://help.wheniwork.com/articles/using-schedule-templates-computer/). ' - name: Annotations description: 'Annotations convey important information to all staff for the given schedules (locations) and date range. Any or none of the following tags may apply to an Annotation: * Time Off Not Allowed * Business Closed * Announcement The "Time Off Not Allowed" tag is the only tag that affects the behavior of another API. Time Off requests will be considered invalid if the request''s date range overlaps an Annotation of the "Time Off Not Allowed" type for the user''s location(s). For more on using Annotations, visit the [Help Center](https://help.wheniwork.com/hc/en-us/articles/204348065-Annotations). ' - name: OpenShift Requests description: 'Shift Bidding, also called “OpenShift Requests”, is an option within an OpenShift that allows employees to express interest in the shift. Management can then view who has requested to pick up the OpenShift and select and approve an employee to work the shift. For more info about using OpenShift Requests, visit the [Help Center](https://help.wheniwork.com/articles/shift-bidding/). ' - name: Times description: 'Time records are a listing of the worked hours and can be select by date range. Records are sourced from timeclock terminal, web clock In/Out, mobile clock In/Out, timesheet edits, and API record creation/edits of time values. For more info about user Times, visit the [Help Center](https://help.wheniwork.com/articles/reviewing-employees-time-sheets-computer/). ' - name: Payrolls description: 'Payrolls allows you to select a pay period date range and hours worked within that range. Default range if not supplied is today + 3 days. > Please note that payrolls cannot be created or deleted via the API For more info about managing Payroll, visit the [Help Center](https://help.wheniwork.com/articles/close-and-export-payroll/). ' - name: Subscriptions description: 'Subscriptions are additional plans that can be attached to an account. Subscriptions may include free or paid plans. ' - name: Shift Breaks description: "Two types of breaks are provided. First; Scheduled Shift Breaks are break records associated with scheduled\ \ shifts. Second; Shift Breaks are break records associated with time worked.\nFor Shift Breaks (Attendance)\n Three\ \ types of records are possible from a break action or automated action\n A record can be created from a user break\ \ punch allocation\n A record can be created from a Manager/Supervisor edit to a timesheet. (With this type of record,\ \ no break time is generated and only the length is available to be queried.)\n A Break record can be created via the\ \ system configuration setting for Auto-Deduct of Breaks. (With this type of record, no break time is generated and only\ \ the length is available to be queried.)\n\n Note: This endpoint requires the request header for w-userid.\n For\ \ more information about managing Breaks, visit the [Help Center](https://help.wheniwork.com/articles/attendance-settings/)\n" - name: Shift Break - Paid Rest description: "When the Attendance setting is enabled to Ask Employees About Paid Rest Breaks the feedback on whether or\ \ not breaks were taken is provided here.\n\n Note: This endpoint requires the request header for w-userid.\n For more\ \ information about managing Breaks, visit the [Help Center](https://help.wheniwork.com/articles/paid-break-reporting/#reporting-paid-breaks)\n\ \n (Deprecated - Please refer to the [updated documentation](https://apidocs.wheniwork.com/external/index.html?repo=attendance#tag/Times)\ \ for managing break attestations)\n" - name: Forecast Tools description: 'Get more insight into your budget while scheduling using the forecast tools. Track the sales and hours budget for your schedules to ensure you have the right coverage and are within your labor budget. Use the Forecast Tools service API to import your forecast data. Please visit the [API documentation](https://apidocs.wheniwork.com/external/index.html?repo=forecast-tools&branch=main) for more details. For more info about using Forecast Tools, visit the [Help Center](https://help.wheniwork.com/articles/forecast-tools/). ' - name: Tasks description: "Use Task Lists to let your employees know what activities they need to complete on a given day or during their\ \ shift. Then monitor the task lists to ensure those activities are completed.\n\n Note: This endpoint requires the request\ \ header for w-userid.\nUse the Tasks service API to create and assign task lists. Please visit the [API documentation](https://apidocs.wheniwork.com/external/index.html?repo=tasks&branch=main)\ \ for more details.\n\nFor more info about using Tasks, visit the [Help Center](https://help.wheniwork.com/articles/how-tasks-work-computer/).\n" - name: Work Tags description: "Tags provide a way to define custom shift qualifications that cannot be easily captured by position alone.\ \ Think of tags like additional eligibility requirements that you can layer on top of positions.\n\n Note: This endpoint\ \ requires the request header for w-userid.\nUse the Work Tags service API to create and assign tags to users, shifts\ \ and shift templates. Please visit the [API documentation](https://apidocs.wheniwork.com/external/index.html?repo=worktags&branch=main)\ \ for more details.\n\nFor more info about using Work Tags, visit the [Help Center](https://help.wheniwork.com/articles/creating-and-managing-tags-computer/).\n" - name: Webhooks description: "Webhooks will send streaming events that details changes happening within the When I Work environment. A webserver\ \ must be configured to receive the events. Events have a few second delay before sending to allow for batching.\n\n \ \ Note: Webhooks require TLS and require the events to be streamed to a domain owned by the account. Please visit the\ \ [API documentation](https://apidocs.wheniwork.com/external/index.html?repo=webhooks&branch=main) for more details.\n\ \nFor more info about using Webhooks, visit the [Help Center](https://help.wheniwork.com/articles/webhooks-reference/).\n" - name: Absences description: "Absences allows users to report when they cannot work an assigned shift and provides a way to track call outs.\n\ \n Note: Use the Scheduling API to report and fetch Absences. Please visit the [API documentation](https://apidocs.wheniwork.com/external/index.html?repo=scheduling&branch=main#tag/Absences)\ \ for more details.\n\nFor more info about using Absences, visit the [Help Center](https://help.wheniwork.com/articles/how-tracking-absences-works/).\n" - name: Scheduling Rules description: "Scheduling rules encompass a variety of rules to help users schedule with confidence.\n\n Note: Use the Scheduling\ \ API to evaluate rules for shifts and users. Please visit [API documentation](https://apidocs.wheniwork.com/external/index.html?repo=scheduling&branch=main#tag/Rules)\ \ for more details.\n\nFor more info about using Scheduling Rules, visit the [Help Center](https://help.wheniwork.com/articles/scheduling-rules-reference/).\n" - name: Break Attestation description: "Break attestation (break reporting) allows users to report that they have taken all of their required breaks.\ \ If \nthey were not able to, they can leave a note explaining why the breaks were missed.\n\n Note: Use the Attendance\ \ API to report and fetch break attestations. Please visit the [API documentation](https://apidocs.wheniwork.com/external/index.html?repo=attendance#tag/Times)\n" - 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\n \n \n \ \ \n \n \n \n \n \n\ \ \n \n \n \n\ \ \n \n \n \n \n \n \n\ \ \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\ \ \n \n \n \n \n \ \ \n \n \n \n \n \ \ \n \n \n \n \n \n\ \ \n \n \n \n \n\ \ \n \n \n \n \ \ \n \n \n \n\ \ \n \n \n \n \n\ \ \n \n \n \n \n\ \ \n \n \n \n \n \ \ \n \n \n \n \n \n \ \ \n \n \n \n \n \n \ \ \n \n \n \n
typecolumnsrequired?notes
SHIFT_TEMPLATEstart_time✅
end_time✅
schedule\n

A schedule name to associate\ \ with the shift template. If no schedule with that name exists, a new schedule will be created.

\n

If omitted,\ \ the shift template will be assigned to all schedules (or the value \"All Schedules\" can be provided to do the same).

\n\ \
position\n

A position\ \ name to associate with the shift template. If no position with that name exists, a new position will be created.

\n\ \
unpaid_breakThe length of the unpaid\ \ break in minutes.
EMPLOYEEfirst_name✅First name of the employee
last_name✅Last name of the employee
emailThe email address of the employee
employee_codeThe employee code to associate with the employee
file_numberThe file number corresponding to the employee in ADP
idThe user id corresponding to the employee in When I Work
location\n

A schedule (location) name to associate\ \ with the employee. If no schedule with that name exists, a new schedule will be created.

\n
maxThe maximum hours per week of the employee
phoneThe phone number of the employee
position\n

A position name to associate with the employee.\ \ If no position with that name exists, a new position will be created.

\n
tags\n

A comma separated list of tags to associate to the employee.\ \ If the tag does not exist, it will be created.

\n
wage\n

The hourly rate of the employee expressed as a floating point number (e.g. 14.50)

\n\ \
\n" - name: Export - name: Reinvite - name: Timezones description: Timezones for When I work workplaces including Olson ID paths: /2/shifts: get: summary: List Shifts description: Fetch a list of shifts based on a set of filters tags: - Shifts parameters: - name: user_id in: query description: The user id to filter by schema: type: integer example: 201 - name: start in: query description: The start of the filter range. schema: type: string format: date-time default: now - name: end in: query description: The end of the filter range. schema: type: string format: date-time default: now + 3 days - name: unpublished in: query description: Whether or not to include unpublished shifts. Requires supervisor rights. schema: type: boolean - name: include_open in: query description: Whether or not to include open shifts from the user's assigned Schedules. schema: type: boolean - name: include_onlyopen in: query description: Whether or not to include only open shifts from the user's assigned Schedules. schema: type: boolean - name: include_allopen in: query description: 'Whether or to include open shifts across All Schedules. Requires "Manager or Admin access" level. Common practice is to combine allopen with one of the other inclusion options. ' schema: type: boolean - name: deleted in: query description: Whether to include a list of shift IDs ("deleted_ids") that were deleted during the passed time window. schema: type: boolean - name: include_swaps in: query description: Whether or not to include swap requests. schema: type: boolean - name: limit in: query description: Maximum number of results to return. schema: type: integer - name: all_locations in: query description: 'Whether to include data from all locations. Shifts are marked as "readonly" if not a manager user. If this option is included in addition to the `location_id` option, all shifts linked to other locations, through users in other locations, will also be included. ' schema: type: boolean - name: location_id in: query description: 'One or more location IDs by which to limit results _Also see `all_locations` above_ ' schema: type: string format: csv - name: shift_sort in: query description: True to sort results by user_id, false to sort by shift time. Missing for default sort schema: type: boolean - name: include_repeating_shifts_to in: query description: End date to include repeating shifts in series, if applicable schema: type: string format: date-time default: null - name: trim_openshifts in: query description: Setting to true will work w/ the Allow Partial Openshifts feature to display trimmed start/end times for users that can take a conflicting openshift based on the account settings. schema: type: boolean - name: limit_by_rules in: query description: Setting to true will work w/ the Scheduling Rules feature to only return OpenShifts that the requester is eligible for according to the scheduling rules settings for the account. schema: type: boolean x-code-samples: - lang: shell source: curl https://api.wheniwork.com/2/shifts responses: '200': description: Valid content: application/json: schema: type: object properties: shifts: type: array items: $ref: '#/components/schemas/Shift' repeating_shifts: description: 'This field will be present if the `include_repeating_shifts_to` parameter is provided. For each fetched shift, if it is on a shift chain, we will insert all the shifts on that chain from the first up to the date specified in the parameter. ' type: array items: $ref: '#/components/schemas/Shift' shiftchains: description: Any shift chains that the fetched shifts are a part of type: array items: $ref: '#/components/schemas/ShiftChain' post: summary: Create Shift description: 'Create one or many shifts for scheduling. **NOTE:** The response is slightly different if you create many shifts instead of one. ' tags: - Shifts parameters: - name: include_repeating_shifts_to in: query description: End date to include repeating shifts in series, if applicable schema: type: string format: date-time default: null requestBody: $ref: '#/components/requestBodies/ShiftRequest' responses: '200': description: Valid content: application/json: schema: oneOf: - type: object properties: shift: $ref: '#/components/schemas/Shift' repeating_shifts: description: 'This field will be present if the `include_repeating_shifts_to` parameter is provided. It will only be populated with shifts if a shift chain is created with the shift and it we will insert the created shifts from the beginning of the chain up to the date specified in the parameter. **NOTE:** This does not apply when creating shifts in bulk. ' type: array items: $ref: '#/components/schemas/Shift' shiftchains: description: A shift chain that was created with the shift type: array items: $ref: '#/components/schemas/ShiftChain' tags: type: array items: type: string example: - e96cab22-0542-4e75-80a4-7c49262eea41 - type: object properties: shifts: type: array items: $ref: '#/components/schemas/Shift' repeating_shifts: description: 'The shifts created as part of a shift chain, if the `include_repeating_shifts_to` parameter is provided and a set of shifts match the criteria. ' type: array items: $ref: '#/components/schemas/Shift' shiftchains: description: Any shift chains that were created for the created shifts type: array items: $ref: '#/components/schemas/ShiftChain' tagIdsMap: description: A map of shift IDs to an array of tag IDs type: object additionalProperties: type: array items: type: string example: '101': [] '102': - e96cab22-0542-4e75-80a4-7c49262eea41 '103': - e96cab22-0542-4e75-80a4-7c49262eea41 - 3b7c8cd3-58a4-4ca3-bb34-0db3cbc1a3de delete: summary: Bulk Delete Shifts deprecated: false description: 'If IDs are provided, those will take precedence. Otherwise it will use the provided filters to delete shifts. If filters are used, the `start`, `end`, and `location_id` properties are required. ' tags: - Shifts parameters: - name: ids in: query description: A comma-separated list of shift IDs to delete. Takes precedence over IDs provided in the body and provided filter properties. required: false example: - 101%2C102 schema: type: array items: type: string - name: message in: query description: Used to notify the shift's assignee that their shift has been deleted. Your message will be added to the notification email. If you want to send the notification email without a message, simple send a single space. required: false example: We%27ll%20be%20closed%20that%20day schema: type: string requestBody: content: application/json: schema: type: object properties: ids: type: array items: type: integer description: The IDs of the shifts to delete. Takes precedence over filter properties. start: type: string format: date-time description: The start of the range you want to delete shifts over. end: type: string format: date-time description: The end of the range you want to delete shifts over. location_id: type: array items: type: integer description: The schedule(s) you want to delete shifts from. At least one is required. position_id: type: array items: type: integer description: The positions of shifts you want to delete. user_id: type: array items: type: integer description: The users whose shifts you want to delete. site_id: type: array items: type: integer description: The sites of shifts you want to delete. responses: '200': description: Success content: application/json: schema: type: object properties: success: type: boolean description: Whether the operation was successful. If absent, nothing was deleted. deleted: type: array items: type: integer description: The IDs of the deleted shifts count: type: integer description: The number of shifts deleted '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/V2Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/V2Error' '404': description: Shift Not Found content: application/json: schema: $ref: '#/components/schemas/V2Error' '500': description: Internal Error content: application/json: schema: $ref: '#/components/schemas/V2Error' /2/shifts/{id}: get: summary: Get Shift description: Get a single shift by ID tags: - Shifts parameters: - name: id in: path description: The ID of the shift schema: type: integer required: true - name: include_repeating_shifts_to in: query description: End date to include repeating shifts in series, if applicable schema: type: string format: date-time default: null responses: '200': description: Valid content: application/json: schema: type: object properties: shift: $ref: '#/components/schemas/Shift' repeating_shifts: description: 'This field will be present if the `include_repeating_shifts_to` parameter is provided. If the fetched shift has a shift chain, we will insert all the shifts on that chain from the first up to the date specified in the parameter. ' type: array items: $ref: '#/components/schemas/Shift' shiftchains: description: Any shift chain this shift is a part of type: array items: $ref: '#/components/schemas/ShiftChain' put: summary: Update Shift description: Update an existing shift for scheduling tags: - Shifts parameters: - name: id in: path description: The ID of the shift schema: type: integer required: true - name: include_repeating_shifts_to in: query description: End date to include repeating shifts in series, if applicable schema: type: string format: date-time default: null requestBody: $ref: '#/components/requestBodies/ShiftRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: shift: $ref: '#/components/schemas/Shift' repeating_shifts: description: 'This field will be present if the `include_repeating_shifts_to` parameter is provided. We will insert the created or edited shifts from the beginning of the chain up to the date specified in the parameter. **NOTE:** This does not apply when updating shifts in bulk. ' type: array items: $ref: '#/components/schemas/Shift' shiftchains: description: Any shift chain this shift is a part of type: array items: $ref: '#/components/schemas/ShiftChain' deleted: description: A list of shift IDs that were deleted as a result of the update. Applicable for updates to repeating shifts that impact future shifts on the same chain. type: array items: type: integer example: - 878787 - 656565 delete: summary: Delete Shift deprecated: false description: Delete an existing shift when no longer needed. This operation cannot be undone. tags: - Shifts parameters: - name: id in: path description: The ID of the shift required: true example: 0 schema: type: integer - name: message in: query description: Used to notify the shift's assignee that their shift has been deleted. Your message will be added to the notification email. If you want to send the notification email without a message, simple send a single space. Must be URL encoded. required: false example: We%27ll%20be%20closed%20that%20day schema: type: string - name: chain in: query description: Only applies to repeating shifts. Any value will delete the shift and all shifts that come after it on the chain. required: false schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: success: type: boolean examples: - true description: Whether deletion was successful. If absent, it means nothing was actually deleted. default: true deleted: type: array items: type: integer description: The IDs of the shifts that were deleted examples: '1': summary: Success value: success: true deleted: - 101 - 102 - 103 '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/V2Error' '404': description: Shift Not Found content: application/json: schema: $ref: '#/components/schemas/V2Error' '500': description: Internal Error content: application/json: schema: $ref: '#/components/schemas/V2Error' /2/times: get: summary: List Times description: Fetch a list of shifts based on a set of filters tags: - Times parameters: - name: start in: query description: The start of the filter range. schema: type: string format: date-time default: now - 3 days - name: end in: query description: The end of the filter range. schema: type: string format: date-time default: now - name: user_id in: query description: List of user ids to filter on schema: type: string format: csv - name: only_open in: query description: Return only times without an end time schema: type: boolean format: true/false default: false - name: updated_at in: query description: Only return times that have been updated since the provided timestamp. schema: type: string format: date-time default: null - in: query description: Flag to overwrite the start/end/length values with their rounded counterparts (if account setting is enabled) name: overwrite_with_rounded required: false default: false schema: type: integer - in: query description: Returns the note for a Shift Break Paid Record. Deprecated - please refer to the break attestation docs [here](#tag/Break-Attestation) name: include_paid_break_note deprecated: true default: false schema: type: boolean responses: '200': description: Valid content: application/json: schema: type: object properties: times: type: array items: $ref: '#/components/schemas/Time' post: summary: Create Time description: Create a time. For accounts with Check payroll onboarded, start time must not be past the end of the current pay period tags: - Times requestBody: $ref: '#/components/requestBodies/TimeRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: time: $ref: '#/components/schemas/Time' /2/times/{id}: get: summary: Get Time description: Get a single time by ID tags: - Times parameters: - name: id in: path description: The ID of the time schema: type: integer required: true responses: '200': description: Valid content: application/json: schema: type: object properties: time: $ref: '#/components/schemas/Time' put: summary: Update Time description: Update an existing time tags: - Times parameters: - name: id in: path description: The ID of the shift schema: type: integer required: true requestBody: $ref: '#/components/requestBodies/TimeRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: shift: $ref: '#/components/schemas/Time' delete: summary: Delete Time description: Delete an existing time when no longer needed. This operation cannot be undone. tags: - Times parameters: - name: id in: path description: The ID of the time schema: type: integer required: true responses: '200': description: Valid content: application/json: schema: type: object properties: success: type: boolean example: true /2/times/clockin: post: summary: Clock In description: Punch the current user or another user in. The punch creator's ID will also be recorded. tags: - Punch requestBody: $ref: '#/components/requestBodies/ClockInRequest' responses: '200': description: Valid content: application/json: schema: $ref: '#/components/schemas/PunchResponse' '400': description: Bad request contains missing or invalid parameters content: application/json: schema: $ref: '#/components/schemas/V2Error' '403': description: Forbidden access, account setting or permissions do not allow this action content: application/json: schema: $ref: '#/components/schemas/V2Error' /2/times/clockout: post: summary: Clock Out description: Punch the current user or another user out. The punch creator's ID will also be recorded. tags: - Punch requestBody: $ref: '#/components/requestBodies/ClockOutRequest' responses: '200': description: Valid content: application/json: schema: $ref: '#/components/schemas/PunchResponse' '400': description: Bad request contains missing or invalid parameters content: application/json: schema: $ref: '#/components/schemas/V2Error' '403': description: Forbidden access, account setting or permissions do not allow this action content: application/json: schema: $ref: '#/components/schemas/V2Error' /2/shifts/unassign: post: summary: Unassign/Release Shifts description: 'Move a set of shifts from users to an OpenShift. This can also be used by employees when the Shift Release setting is enabled. ' tags: - Shifts requestBody: $ref: '#/components/requestBodies/ShiftUnassignRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: shifts: type: array items: $ref: '#/components/schemas/Shift' /2/shifts/{id}/assign: post: parameters: - name: id in: path description: The ID of the shift schema: type: integer required: true summary: Assign multiple users to an OpenShift description: 'Assign mutiple users to an OpenShift with multiple instances This can also be used to approve multiple users for an OpenShift that requires approval. ' tags: - Shifts requestBody: $ref: '#/components/requestBodies/ShiftAssignRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: shifts: type: array items: $ref: '#/components/schemas/Shift' openshiftapprovalrequests: type: array items: $ref: '#/components/schemas/OpenShiftApprovalRequest' /2/shifts/eligible: get: summary: List eligible users for OpenShift description: Get a list of eligible users to offer an OpenShift based on existing shift, or shift parameters tags: - Shifts parameters: - name: id in: query description: The ID of the shift schema: type: integer - name: start in: query description: Start time of the potential shift (required if Shift ID not present) schema: type: string format: date-time - name: end in: query description: End time of the potential shift (required if Shift ID not present) schema: type: string format: date-time - name: position_id in: query description: Position ID of the potential shift (required if Shift ID not present) schema: type: string - name: location_id in: query description: Location ID of the potenential shift (required if Shift ID not present) schema: type: string - name: is_shared in: query description: Is the shift a shared OpenShift schema: type: boolean default: false - name: include_objects in: query description: Include user locations and positions in output schema: type: boolean default: false - name: tags in: query description: A set of tag IDs to compare the eligible users against schema: type: array items: type: string default: [] responses: '200': description: Valid content: application/json: schema: type: object properties: users: type: array items: $ref: '#/components/schemas/User' /2/shifts/{id}/history: get: parameters: - name: id in: path description: The ID of the shift schema: type: integer required: true - name: include_deleted in: query description: Flag to indicate if you want to search for a deleted shift's history (off by default) type: boolean required: false default: false summary: Fetch shift history description: 'Provides a detailed list of history events that are recorded every time the given shift was changed indicating how it changed (Reason Code), and by which user (updated by ID). This history is a rolling 90 day period based on the shift start date/time. Also, history is not retained for OpenShifts following deletion of the shift. ' tags: - Shifts responses: '200': description: Valid content: application/json: schema: type: object properties: shift: description: The current version of the shift $ref: '#/components/schemas/Shift' history: description: Array of history events type: array items: $ref: '#/components/schemas/ShiftHistory' /2/shifts/publish: post: summary: Publish Shifts description: "These methods allow you to publish or unpublish a group of shifts.\n (Note: multi-threading is supported\ \ for large lists of shift)\n See Notify Shifts for informing users of Publication\n" tags: - Shifts requestBody: $ref: '#/components/requestBodies/ShiftPublish' responses: '200': description: Valid content: application/json: schema: type: object properties: shifts: type: array items: $ref: '#/components/schemas/Shift' /2/shifts/unpublish: post: summary: Unpublish Shifts description: "These methods allow you to publish or unpublish a group of shifts.\n (Note: multi-threading is supported\ \ for large lists of shift)\n" tags: - Shifts requestBody: $ref: '#/components/requestBodies/ShiftPublish' responses: '200': description: Valid content: application/json: schema: type: object properties: shifts: type: array items: $ref: '#/components/schemas/Shift' /2/shifts/notify: post: summary: Notify shifts description: 'Send Notifications for a published schedule ' tags: - Shifts requestBody: $ref: '#/components/requestBodies/ShiftNotifyRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: success: type: boolean example: true email: type: integer example: 5 description: A count of the emails sent. sms: type: integer example: 10 description: A count of the SMS and/or push notifications (depending on user preferences) sent. /2/shifts/notify/{id}: post: summary: Notify single shift description: Send Notifications for a single shift tags: - Shifts parameters: - name: id in: path description: The ID of the shift to send notifications schema: type: integer required: true requestBody: $ref: '#/components/requestBodies/SingleShiftNotifyRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: success: type: boolean example: true email: type: integer example: 5 description: A count of the emails sent. sms: type: integer example: 10 description: A count of the SMS and/or push notifications (depending on user preferences) sent. /2/shifts/bulk: put: summary: Bulk Update Shifts description: Make updates to multiple shifts in a single API request by submitting an array of the shifts and data to be changed. tags: - Shifts parameters: - name: assign_openshift_instances in: query description: 'When set to true, any multiple instance openshifts that are being assigned will assign only one openshift off the stack rather than the entire stack. ' schema: type: boolean default: false requestBody: $ref: '#/components/requestBodies/BulkEditShiftRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: shifts: description: Array of shift objects to update type: array items: $ref: '#/components/schemas/Shift' '400': description: Invalid content: application/json: schema: type: object properties: shifts: description: Shifts that were successfully updated and their new data type: array items: $ref: '#/components/schemas/Shift' errors: description: Array of errors for each shift that failed to update type: array items: type: object properties: shift_id: type: integer example: 1235123 error: type: string example: The end time must happen after the start time. code: type: integer example: 2165 /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: - Shifts - 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 /2/positions: get: summary: List Positions description: List all the positions in an account. tags: - Positions parameters: - name: show_deleted in: query description: Whether to show positions that have been deleted schema: type: boolean responses: '200': description: Valid content: application/json: schema: type: object properties: positions: type: array items: $ref: '#/components/schemas/Position' post: summary: Create Position description: 'The easiest way to create a position. ' tags: - Positions requestBody: $ref: '#/components/requestBodies/PositionRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: position: $ref: '#/components/schemas/Position' /2/positions/{id}: get: summary: Get Position description: Get a single position by ID tags: - Positions parameters: - name: id in: path description: The ID of the position schema: type: integer required: true responses: '200': description: Valid content: application/json: schema: type: object properties: position: $ref: '#/components/schemas/Position' put: summary: Update Position description: Allows updating a position, with the same format as creating one. tags: - Positions parameters: - name: id in: path description: The ID of the position schema: type: integer required: true requestBody: $ref: '#/components/requestBodies/PositionRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: position: $ref: '#/components/schemas/Position' delete: summary: Delete Position description: 'Delete an existing position when no longer needed. This operation cannot be undone. Data will remain for historical purposes. ' tags: - Positions parameters: - name: id in: path description: The ID of the position schema: type: integer required: false - name: ids in: query description: The IDs of the multiple shift templates schema: type: string required: false example: 1,2,3,4 responses: '200': description: Valid content: application/json: schema: type: object properties: success: type: boolean example: true /2/positions/bulk: put: summary: Update Multiple Positions tags: - Positions requestBody: description: The list of positions to update content: application/json: schema: type: array items: $ref: '#/components/schemas/Position' responses: '200': description: Valid content: application/json: schema: type: object properties: positions: type: array items: $ref: '#/components/schemas/Position' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/V2Error' example: error: Body must be an array of positions code: INVALID_BODY '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/V2Error' example: error: You do not have access to do this. code: UNAUTHORIZED '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/V2Error' example: error: Could not find position '1234' code: POSITION_NOT_FOUND '500': description: Internal Error content: application/json: schema: $ref: '#/components/schemas/V2Error' example: error: There was a problem saving a position. code: INTERNAL_ERROR /2/locations: get: summary: List Schedules (Locations) description: List all the schedules in an account tags: - Schedules (Locations) parameters: - name: only_unconfirmed in: query description: Include only unconfirmed schedules/locations schema: type: boolean example: false responses: '200': description: Valid content: application/json: schema: type: object properties: locations: type: array items: $ref: '#/components/schemas/Schedule' post: summary: Create Schedule (Location) description: Used to create a schedule (location) within an account tags: - Schedules (Locations) requestBody: $ref: '#/components/requestBodies/ScheduleRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: location: $ref: '#/components/schemas/Schedule' /2/locations/{id}: get: summary: Get Schedule (Location) description: Get a single schedule/location by ID tags: - Schedules (Locations) parameters: - name: id in: path description: The ID of the schedule schema: type: integer required: true responses: '200': description: Valid content: application/json: schema: type: object properties: location: $ref: '#/components/schemas/Schedule' put: summary: Update Schedule (Location) description: Updates a single schedule (location) tags: - Schedules (Locations) parameters: - name: id in: path description: The ID of the schedule schema: type: integer required: true requestBody: $ref: '#/components/requestBodies/ScheduleRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: location: $ref: '#/components/schemas/Schedule' delete: summary: Delete Schedule (Location) description: 'Delete an existing schedule when no longer needed. This operation cannot be undone. Data will remain for historical purposes. ' tags: - Schedules (Locations) parameters: - name: id in: path description: The ID of the schedule schema: type: integer required: false - name: ids in: query description: The IDs of the multiple shift templates schema: type: string required: false example: 1,2,3,4 responses: '200': description: Valid content: application/json: schema: type: object properties: success: type: boolean example: true /2/sites: get: summary: List Sites description: List all the sites in an account tags: - Sites parameters: - name: include_deleted in: query description: Include deleted sites schema: type: boolean example: false responses: '200': description: Valid content: application/json: schema: type: object properties: sites: type: array items: $ref: '#/components/schemas/Site' post: summary: Create Site description: Used to create a site within an account tags: - Sites requestBody: $ref: '#/components/requestBodies/SiteRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: type: object properties: id: type: integer readOnly: true example: 10000 account_id: type: integer example: 10000 location_id: type: integer example: 145030 name: type: string example: Main venue. color: type: string example: 8da6d9 description: type: string example: Large meeting room address: type: string example: '420 N 5th St #500, Minneapolis, MN 55401, USA' coordinates: type: array example: - 44.983791 - -93.2774416 latitude: type: number format: float example: 44.983791 longitude: type: number format: float example: -93.2774416 place: $ref: '#/components/schemas/Place' place_id: type: string example: 2 is_deleted: type: boolean example: false deleted_at: type: string format: date-time created_at: type: string format: date-time example: '2020-05-16T06:57:28+05:00' updated_at: type: string format: date-time example: '2020-05-26T06:57:28+05:00' /2/sites/{id}: get: summary: Get Site description: Get a single site by ID tags: - Sites parameters: - name: id in: path description: The ID of the site schema: type: integer required: true responses: '200': description: Valid content: application/json: schema: type: object properties: site: $ref: '#/components/schemas/Site' put: summary: Update Site description: Updates a single site tags: - Sites parameters: - name: id in: path description: The ID of the site schema: type: integer required: true requestBody: $ref: '#/components/requestBodies/SiteRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: site: $ref: '#/components/schemas/Site' delete: summary: Delete Site description: "Delete an existing site when no longer needed. This operation cannot be undone. \n" tags: - Sites parameters: - name: id in: path description: The ID of the site schema: type: integer required: false - name: ids in: query description: The IDs of the multiple shift templates schema: type: string required: false example: 1,2,3,4 responses: '200': description: Valid content: application/json: schema: type: object properties: success: type: boolean example: true '403': description: 'Forbidden. The current user does not have permission to delete sites. ' '404': description: 'Not Found. The site to be deleted was not found. ' /2/blocks: get: summary: List Shift Templates (Blocks) description: List all the shift templates in an account tags: - Shift Templates (Blocks) responses: '200': description: Valid content: application/json: schema: type: object properties: blocks: type: array items: $ref: '#/components/schemas/ShiftTemplate' post: summary: Create Shift Template (Block) description: Used to create a shift template within an account tags: - Shift Templates (Blocks) requestBody: $ref: '#/components/requestBodies/ShiftTemplateRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: block: $ref: '#/components/schemas/ShiftTemplate' /2/blocks/{id}: get: summary: Get Shift Template (Block) description: Get a single shift template by ID tags: - Shift Templates (Blocks) parameters: - name: id in: path description: The ID of the shift template schema: type: integer required: true responses: '200': description: Valid content: application/json: schema: type: object properties: block: $ref: '#/components/schemas/ShiftTemplate' put: summary: Update Shift Template (block) description: Updates a single shift template tags: - Shift Templates (Blocks) parameters: - name: id in: path description: The ID of the shift template schema: type: integer required: true requestBody: $ref: '#/components/requestBodies/ShiftTemplateRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: block: $ref: '#/components/schemas/ShiftTemplate' delete: summary: Delete Shift Template (Block) description: Delete an existing shift template when no longer needed. This operation cannot be undone. tags: - Shift Templates (Blocks) parameters: - name: id in: path description: The ID of the shift template schema: type: integer required: false - name: ids in: query description: The IDs of the multiple shift templates schema: type: string required: false example: 1,2,3,4 responses: '200': description: Valid content: application/json: schema: type: object properties: success: type: boolean example: true /2/templates: get: summary: List Schedule Templates description: List all the shift templates in an account tags: - Schedule Templates responses: '200': description: Valid content: application/json: schema: type: object properties: templates: type: array items: $ref: '#/components/schemas/ScheduleTemplate' templateshifts: type: array items: $ref: '#/components/schemas/ScheduleTemplateShift' post: summary: Create Schedule Template description: Create a schedule template as a collection of shifts in a daily or weekly pattern which can be loaded to future schedules. The API will collect shifts which fall within the parameters provided; outline below. tags: - Schedule Templates requestBody: $ref: '#/components/requestBodies/ScheduleTemplateRequestCreate' responses: '200': description: Valid content: application/json: schema: type: object properties: templates: type: array items: $ref: '#/components/schemas/ScheduleTemplate' templateshifts: type: array items: $ref: '#/components/schemas/ScheduleTemplateShift' /2/templates/{id}: get: summary: Get Schedule Template description: Get a single schedule template by ID tags: - Schedule Templates parameters: - name: id in: path description: The ID of the shift template schema: type: integer required: true responses: '200': description: Valid content: application/json: schema: type: object properties: templates: type: array items: $ref: '#/components/schemas/ScheduleTemplate' templateshifts: type: array items: $ref: '#/components/schemas/ScheduleTemplateShift' put: summary: Update Schedule Template description: Update a single schedule template tags: - Schedule Templates parameters: - name: id in: path description: The ID of the schedule template schema: type: integer required: true requestBody: $ref: '#/components/requestBodies/ScheduleTemplateRequestUpdate' responses: '200': description: Valid content: application/json: schema: type: object properties: templates: type: array items: $ref: '#/components/schemas/ScheduleTemplate' templateshifts: type: array items: $ref: '#/components/schemas/ScheduleTemplateShift' delete: summary: Delete Schedule Template description: Delete an existing schedule template when no longer needed. This operation cannot be undone. tags: - Schedule Templates parameters: - name: id in: path description: The ID of the schedule template schema: type: integer required: true responses: '200': description: Valid content: application/json: schema: type: object properties: success: type: boolean example: true /2/annotations: get: summary: List Annotations description: List all the annotations in the specified date range tags: - Annotations parameters: - name: start_date in: query description: Optional start date to filter by (defaults to the beginning of today) schema: type: string format: date-time example: '2019-05-22T00:00:00+05:00' - name: end_date in: query description: Optional end date to filter by (defaults to the beginning of the day one year from start date) schema: type: string format: date-time example: '2020-05-22T00:00:00+05:00' - name: locations in: query description: Optional list of location IDs to filter by (defaults to all locations) schema: type: array items: type: integer example: - 1 - 2 - 3 - 4 - name: no_time_off in: query description: Optional flag to filter to only annotations that don't allow time-off (defaults to false) schema: type: boolean example: false responses: '200': description: Valid content: application/json: schema: type: object properties: annotations: type: array items: $ref: '#/components/schemas/Annotation' post: summary: Create Annotation description: Used to create an annotation tags: - Annotations requestBody: $ref: '#/components/requestBodies/AnnotationRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: annotation: $ref: '#/components/schemas/Annotation' '400': description: Failed validation content: application/json: schema: type: object properties: code: type: integer example: 2076 error: type: string example: You must select the type of annotation. '403': description: Conflicts content: application/json: schema: type: object properties: code: type: integer example: 3704 error: type: string example: Conflict(s) detected with the location(s) and date range provided. /2/annotations/{id}: get: summary: Get Annotation description: Get a single shift annotation by ID tags: - Annotations parameters: - name: id in: path description: The ID of the annotation schema: type: integer required: true responses: '200': description: Valid content: application/json: schema: type: object properties: annotation: $ref: '#/components/schemas/Annotation' put: summary: Update Annotation description: Updates a single annotation tags: - Annotations parameters: - name: id in: path description: The ID of the annotation schema: type: integer required: true requestBody: $ref: '#/components/requestBodies/AnnotationRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: annotation: $ref: '#/components/schemas/Annotation' delete: summary: Delete Annotation description: Delete an existing annotation when no longer needed. This operation cannot be undone. tags: - Annotations parameters: - name: id in: path description: The ID of the annotation schema: type: integer required: true responses: '200': description: Valid content: application/json: schema: type: object properties: success: type: boolean example: true /2/availabilityevents: get: summary: List Availability Events description: Get a list of availability events based on a set of filters. Requests date ranges will include events with recurrence patterns within the date range. Requests will be submitted with the supplied date range and the response will be in the requesting users timezone. tags: - Availabilities parameters: - name: start in: query description: The start of the filter range. Defaults to "now" schema: type: string format: date-time - name: end in: query description: The end of the filter range. Defaults to "two weeks from now" schema: type: string format: date-time - name: user_id in: query description: The optional User ID who's events you wish to fetch. If omitted, uses the calling user's ID schema: type: integer - name: include_all in: query description: Whether to include all availability data instead of just the requestor's. Only valid for managers schema: type: boolean responses: '200': description: Valid content: application/json: schema: type: object properties: availabilityevents: type: array items: $ref: '#/components/schemas/AvailabilityEvent' post: summary: Create Availability Event description: Create an availability preference tags: - Availabilities requestBody: $ref: '#/components/requestBodies/AvailabilityEventRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: availabilityevent: $ref: '#/components/schemas/AvailabilityEvent' /2/availabilityevents/{id}: get: summary: Get Availability Event description: Get a single availability event by ID tags: - Availabilities parameters: - name: id in: path description: The ID of the event schema: type: integer required: true responses: '200': description: Valid content: application/json: schema: type: object properties: availabilityevent: $ref: '#/components/schemas/AvailabilityEvent' put: summary: Update Availability Event description: Update an existing availability preference tags: - Availabilities parameters: - name: id in: path description: The ID of the shift schema: type: integer required: true requestBody: $ref: '#/components/requestBodies/AvailabilityEventRequest' responses: '200': description: Valid. The new preference and (potentially) the edited original preference content: application/json: schema: type: object properties: availabilityevents: type: array items: $ref: '#/components/schemas/AvailabilityEvent' delete: summary: Delete Availability Event description: Delete an existing event when no longer needed. This operation cannot be undone. tags: - Availabilities parameters: - name: id in: path description: The ID of the event schema: type: integer required: true responses: '200': description: Valid content: application/json: schema: type: object properties: success: type: boolean example: true /2/availabilityevents/{id}/exceptions: post: summary: Create Availability Event Exception description: Create a standalone availability preference in the middle of a recurring series tags: - Availabilities requestBody: content: application/json: schema: $ref: '#/components/schemas/AvailabilityEvent' description: The new event. Uses the new event's start time to update the existing series. responses: '200': description: Valid. The new preference and the edited original preference content: application/json: schema: type: object properties: availabilityevents: type: array items: $ref: '#/components/schemas/AvailabilityEvent' /2/requests: get: summary: List Time Off Requests description: 'Get a collection of request objects. Requests allow users to request time off. ' parameters: - name: end description: yyyy-mm-dd formatted end date for the request time-frame. in: query required: true schema: type: string format: date - name: include_deleted_users description: 'Return all requests including those made by deleted users. ' in: query schema: type: boolean default: false - name: limit description: Number of requests to load per page. in: query schema: type: integer minimum: 1 maximum: 200 default: 5 - name: location_id description: Location ID to show requests for. in: query schema: type: integer - name: max_id description: 'Return all requests created before the request with the given ID. ' in: query schema: type: integer - name: page description: Page of results to load. in: query schema: type: integer default: 0 - name: since_id description: 'Return all requests created since the request with given ID. ' in: query schema: type: integer - name: sortby description: 'Field to sort by. Can either be ''created'' and sort by the created_at date in descending order, or anything else and sort by status in ascending order, then by the updated_at date in descending order. ' in: query schema: type: string - name: start description: 'yyyy-mm-dd formatted start date for the request time-frame. ' in: query required: true schema: type: string format: date - name: status description: Only return requests with the given status. in: query schema: type: integer - name: type description: Type of request to filter by. in: query schema: type: integer - name: user_id description: 'Only return requests for the given user IDs. Multiple values can be comma separated. ' in: query schema: type: integer responses: '200': description: Collection of Request resources. content: application/json: schema: properties: requests: description: Array of request objects. items: $ref: '#/components/schemas/Request' type: array more: type: boolean page: description: Current page number. type: integer total: description: Total number of pages in the collection. type: integer messages: description: Array of message objects. items: $ref: '#/components/schemas/Message' type: array users: description: Array of user objects. items: $ref: '#/components/schemas/User' type: array type: object '400': description: 'Bad request. The given start and end dates were not valid. ' '403': description: 'Forbidden. The current user does not have permission to view the user''s requests. ' tags: - Time Off Requests post: summary: Create Time Off Request requestBody: content: application/json: schema: $ref: '#/components/schemas/Request' description: The request to create. responses: '201': description: Request was successfully created. content: application/json: schema: properties: request: $ref: '#/components/schemas/Request' type: object '400': description: Bad request. '403': description: Forbidden. tags: - Time Off Requests /2/requests/{request_id}: parameters: - name: request_id description: Request ID to return. in: path required: true schema: type: integer get: summary: Get Time Off Request description: 'Returns a single request object. Requests allow users to request time off. ' responses: '200': description: Individual Request resource. content: application/json: schema: properties: messages: description: Array of message objects. items: $ref: '#/components/schemas/Message' type: array request: $ref: '#/components/schemas/Request' users: description: Array of user objects. items: $ref: '#/components/schemas/User' type: array type: object '403': description: 'Forbidden. The current user does not have permission to view the request. ' content: application/json: schema: $ref: '#/components/schemas/V2Error' '404': description: ID was not found. content: application/json: schema: $ref: '#/components/schemas/V2Error' tags: - Time Off Requests put: summary: Update Time Off Request description: Replaces properties in the request with the values given. requestBody: content: application/json: schema: properties: end_time: description: (Optional) Full datetime the request ends at. Required if also supplying start_time. format: date-time type: string example: '2020-02-02T12:34:56' hours: description: (Optional) The number of hours of paid time off to use. format: float type: number example: 6.25 start_time: description: (Optional) Full datetime the request starts at. Required if also supplying end_time. format: date-time type: string example: '2020-02-02T12:34:56' status: description: "(Optional) The new status of the request.\n * `0` = Pending\n * `1` = Canceled\n * `2`\ \ = Accepted\n * `3` = Expired\n * `4` = Denied\n" enum: - 0 - 1 - 2 - 3 - 4 type: integer type: deprecated: true description: 'DEPRECATED IN FAVOR OF `type_id`. SEE Request Type. (Optional) Type code for the request. * `0` = Unpaid * `1` = Paid (PTO) * `2` = Sick * `3` = Holiday ' enum: - 0 - 1 - 2 - 3 type: integer type: object description: The details to update on the request. responses: '200': description: The request was successfully updated. content: application/json: schema: properties: request: $ref: '#/components/schemas/Request' type: object '400': description: 'Bad request. There was an error in one or more of the values sent. ' content: application/json: schema: $ref: '#/components/schemas/V2Error' '403': description: Forbidden. The current user does not have permission. content: application/json: schema: $ref: '#/components/schemas/V2Error' '404': description: Request ID was not found or the user does not exist. content: application/json: schema: $ref: '#/components/schemas/V2Error' tags: - Time Off Requests delete: summary: Delete Time Off Request responses: '200': description: The request was deleted. '403': description: 'Forbidden. The current user does not have permission to delete the request. ' content: application/json: schema: $ref: '#/components/schemas/V2Error' '404': description: The request was not found. content: application/json: schema: $ref: '#/components/schemas/V2Error' '500': description: The request must be canceled before it can be deleted. content: application/json: schema: $ref: '#/components/schemas/V2Error' tags: - Time Off Requests /2/requesttypes: get: summary: List Of Time Off Request Types description: 'Get a collection of request type objects. Request types are types available for taking time off. ' parameters: - name: end schema: type: integer responses: '200': description: Collection of Time Off Request Types. content: application/json: schema: type: object properties: request-types: description: Array of request type objects. items: $ref: '#/components/schemas/RequestType' '403': description: Forbidden. tags: - Request Type post: summary: Create or update a Collection of request types requestBody: content: application/json: schema: properties: request-types: type: array description: Array of Request Type objects to create or update. items: $ref: '#/components/schemas/RequestType' responses: '201': description: Request was successfully created. content: application/json: schema: type: object properties: request-types: description: Array of Request Type objects. items: $ref: '#/components/schemas/RequestType' '400': description: Bad request. '403': description: Forbidden. tags: - Request Type /2/requesttypes/{id}: parameters: - name: id description: Request Type with ID to return. in: path required: true schema: type: integer get: summary: Get Time Off Request Type description: 'Returns a single request object. Requests allow users to request time off. ' responses: '200': description: Individual Request Type resource. content: application/json: schema: properties: request-type: $ref: '#/components/schemas/RequestType' '403': description: 'Forbidden. The current user does not have permission to view the request type. ' content: application/json: schema: $ref: '#/components/schemas/V2Error' '404': description: ID was not found. content: application/json: schema: $ref: '#/components/schemas/V2Error' tags: - Request Type delete: summary: Delete Time Off Request Type responses: '200': description: The Request Type was deleted. '403': description: 'Forbidden. The current user does not have permission to delete the request type. ' content: application/json: schema: $ref: '#/components/schemas/V2Error' '404': description: The Request Type was not found. content: application/json: schema: $ref: '#/components/schemas/V2Error' tags: - Request Type /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 \n\ manager 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 /2/openshiftapprovalrequests: get: summary: List OpenShift Approval Requests tags: - OpenShift Requests description: 'List all the OpenShift Approval Requests that the user is allowed to see. Managers can see all, supervisors can see all tied to a shift at a schedule/location they supervise and employees can see all request that they''ve made. ' parameters: - name: start description: yyyy-mm-dd formatted end date for range of OpenShift Approval Requests you would like returned. in: query schema: type: string format: date - name: end description: yyyy-mm-dd formatted start date for the range of OpenShift Approval Requests you would like returned. in: query schema: type: string format: date - name: page description: Page number of results you are requesting. in: query schema: type: integer default: 0 - name: limit description: Number of results to load per page. in: query schema: type: integer responses: '200': description: Valid content: application/json: schema: type: object properties: openshiftapprovalrequests: type: array items: $ref: '#/components/schemas/OpenShiftApprovalRequest' post: summary: Create OpenShift Approval Requests tags: - OpenShift Requests description: 'Create an OpenShift Approval Request. This will most likely be done by the API when creating or publishing a shift, but it''s here if you need it. ' parameters: - name: body in: body schema: $ref: '#/components/schemas/OpenShiftApprovalRequest' produces: - application/json responses: '200': description: Valid schema: type: object properties: openshiftapprovalrequest: $ref: '#/components/schemas/OpenShiftApprovalRequest' /2/openshiftapprovalrequests/{request_id}: parameters: - name: request_id description: OpenShift Approval Request ID to return. in: path required: true schema: type: integer delete: tags: - OpenShift Requests summary: Delete an OpenShift Approval Request. responses: '200': description: The request was deleted. get: tags: - OpenShift Requests summary: Get specific OpenShift Approval Request responses: '200': description: Individual OpenShift Approval Request resource. content: application/json: schema: type: object properties: openshiftapprovalrequest: $ref: '#/components/schemas/OpenShiftApprovalRequest' put: tags: - OpenShift Requests summary: Update an OpenShift Approval Request. description: 'Replaces properties in the request with the values given. If you are looking to approve users who requested to take an OpenShift please refer to [Assign multiple users to an OpenShift](https://apidocs.wheniwork.com/external/index.html#tag/Shifts/paths/~12~1shifts~1{id}~1assign/post) ' requestBody: content: application/json: schema: $ref: '#/components/schemas/OpenShiftApprovalRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: openshiftapprovalrequest: $ref: '#/components/schemas/OpenShiftApprovalRequest' /2/openshiftapprovarequests/{request_id}/user-requests: parameters: - name: request_id description: OpenShift Approval Request ID to return. in: path required: true schema: type: integer delete: tags: - OpenShift Requests summary: Cancel an individual's request for an OpenShift responses: '200': description: The OpenShift request was canceled for this user /2/punch/state: get: summary: Punch State description: Gets a users punch state and allowed actions tags: - Punch parameters: - in: query description: User ID if looking up the punch state for another user, may allow additional actions name: userId required: false schema: type: integer - in: query description: Location ID (schedule) used to verify if the user can punch in at this location name: locationId required: false schema: type: integer - in: query description: Job site used to verify if the user can punch in at this site name: siteId required: false schema: type: integer - in: query description: Shift ID used to verify if the user can punch into this shift name: shiftId required: false schema: type: integer - in: query description: Type of device used to perform the punch name: deviceType required: false schema: type: string enum: - web - mobile - terminal - in: query description: Current latitude used to verify punch restrictions for strict location validation name: latitude required: false schema: type: number - in: query description: Current longitude used to verify punch restrictions for strict location validation name: longitude required: false schema: type: number - in: query description: Expand the location search area by a given confidence to the provided location name: confidence required: false schema: type: number responses: '200': description: The current punch state and allowed actions for the user content: application/json: schema: type: object properties: canClockIn: description: Can the user be clocked in type: boolean example: false canClockOut: description: Can the user be clocked out type: boolean example: false canStartBreak: description: Can the user start a break type: boolean example: false canEndBreak: description: Can the user end their break type: boolean example: true needsBreakConfirmation: description: True if the user is required to report on unused paid breaks type: boolean example: false needsUnpaidBreakConfirmation: description: True if the user is required to report on unused unpaid breaks type: boolean example: false punchStartTime: description: Time when the user punched in, date in ISO 8601 format (UTC timezone) type: string example: '2017-09-27T18:28:52' punchTimeId: description: The ID of the time object associated with the punch type: integer example: 1 errorCode: description: 'Error code describing why punch in or punch out is not allowed * `101` - Bad device location received * `102` - Bad shift location received * `103` - Out of range for shift location * `104` - Not near the punch location * `105` - Clock-in time too early * `106` - No shift scheduled, or manual selection required (see: availableShifts) ' type: integer enum: - 101 - 102 - 103 - 104 - 105 - 106 schedules: example: 1 oneOf: - schedule: null type: integer description: The schedule ID to punch in at or the schedule currently punched in at - scheduled: null type: string description: URL used to load a listing of possible schedules jobSites: example: 1 oneOf: - site: null type: integer description: The job site ID to punch in at or the job site currently punched in at - sites: null type: string description: URL used to load a listing of possible job sites positions: example: 1 oneOf: - position: null type: integer description: The position ID to punch in at or position currently punched in as - positions: null type: string description: URL used to load a listing of possible positions shift: example: 1 description: The shift ID that should be used when punching in or the shift ID currently punched in as type: integer break: description: The break object currently punched into if currently on a punched break type: object $ref: '#/components/schemas/PunchStateRootShiftBreak' availableShifts: description: A list of available shift IDs the user is allowed to punch in to example: - 4 - 6 - 7 type: array items: type: integer recordingUnpaidBreaksAllowed: description: True if the user is allowed to record unpaid breaks type: boolean example: true recordingPaidBreaksAllowed: description: True if the user is allowed to record paid breaks type: boolean example: true scheduledBreaks: type: array description: A list of scheduled breaks if the clocked in time has a shift which has scheduled breaks. (Only provided when clocked in, there's a shift, and the shift has scheduled breaks) items: type: object $ref: '#/components/schemas/PunchStateScheduledBreak' unscheduledBreaks: type: array description: A list of any taken unscheduled breaks. (Only provided when clocked in and there are shift breaks for the time) items: type: object $ref: '#/components/schemas/PunchStateNestedShiftBreak' '400': description: Bad request contains missing or invalid parameters content: application/json: schema: type: object properties: errors: description: A list of validation errors example: - Invalid value for userID - Missing required parameter deviceType type: array items: type: string '403': description: Forbidden access, account setting or permissions do not allow this action content: application/json: schema: type: object properties: errors: description: A list of validation errors example: - Web punch state not active on account type: array items: type: string '404': description: Not found, requested resource could not be found content: application/json: schema: type: object properties: errors: description: A list of validation errors example: - User not found type: array items: type: string /2/payrolls: get: summary: List Payrolls description: Listing of payroll periods and totals within a specified date range for an account. tags: - Payrolls parameters: - name: start in: query description: Start date of search range (datetime formatted ISO8601) schema: type: date-time default: now - name: end in: query description: End date of search range (datetime formatted ISO8601) schema: type: date-time default: now + 3 days x-code-samples: - lang: shell source: 'curl -X Get https://api.wheniwork.com/2/payrolls -H "W-Token: ilovemyboss" ' responses: '200': description: Valid content: application/json: schema: type: object properties: payrolls: type: array items: $ref: '#/components/schemas/Payroll' /2/payrolls/{id}: get: summary: Get Payroll description: Get an existing payroll period by ID tags: - Payrolls parameters: - name: id in: path description: The ID of the payroll period requested. schema: type: integer required: true - Payrollhours x-code-samples: - lang: shell source: 'curl -X Get https://api.wheniwork.com/2/payrolls/{Id} -H "W-Token: ilovemyboss" ' responses: '200': description: Valid content: application/json: schema: type: object properties: payroll: $ref: '#/components/schemas/Payroll' payrollhours: type: array description: 'The final unchanging snapshot of hours for a closed out payroll. Broken out by type, split as needed when crossing pay periods. **🔥WARNING🔥** Only for a closed payroll (see is_closed) please use `hourstats` for a payroll that is currently open. ' items: $ref: '#/components/schemas/PayrollHours' put: summary: Update Payroll description: Update a selected payroll. The PUT body can include fields from the Payroll Object. tags: - Payrolls requestBody: $ref: '#/components/requestBodies/PayrollRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: payroll: $ref: '#/components/schemas/Payroll' /2/payrolls/{id}/stats: get: summary: Get Payroll Statistics for current hours description: Get the aggregate statistics for payroll period by ID tags: - Payrolls parameters: - name: id in: path description: The ID of the payroll period requested. schema: type: integer required: true - name: mapObjects in: query description: Force structured listings to use maps by ID and not arrays required: false schema: type: boolean x-code-samples: - lang: shell source: 'curl -X Get https://api.wheniwork.com/2/payrolls/{Id}/Stats -H "W-Token: ilovemyboss" ' responses: '200': description: Valid content: application/json: schema: type: object properties: payroll: $ref: '#/components/schemas/Payroll' /2/payrolls/notices: get: summary: List Notices description: 'Get all attendance notices since the last time they were dismissed. Attendance notices can be generated by absences, early/late clock ins/outs, no shows, etc. ' tags: - Payrolls parameters: - name: ignoreDismissedAt in: query schema: type: boolean description: 'Sometimes you may want to view notices that have already been dismissed. Set this parameter to `true` to view all notices regardless of when they''ve been dismissed. ' required: false example: true - name: rangeInDays in: query schema: type: integer description: 'Limit the range of the notices that will be returned. By default, the endpoint will pull in everything since the last time the user dismissed notices. This parameter can help restrict the window further. ' required: false example: -7 responses: '200': description: Valid content: application/json: schema: type: object properties: absences: type: array description: Any absences that generated a notice. items: $ref: '#/components/schemas/Absence' notices: type: array description: Attendance anomalies that may need to be reviewed. items: $ref: '#/components/schemas/Notice' punches: type: array description: All punches associated with times that generate a notice. items: $ref: '#/components/schemas/Punch' shifts: type: array description: Any shifts that were associated with absences or times that generated a notice. items: $ref: '#/components/schemas/Shift' times: type: array description: Any times that generated a notice. items: $ref: '#/components/schemas/Time' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/V2Error' example: error: You do not have permission to do this. code: 3005 /v3/scheduled-breaks: openapi: 3.0.0 get: summary: List Scheduled Shift Breaks parameters: - in: query description: Gets shift breaks with start after (datetime formatted ISO8601) required: false name: startTime schema: type: string format: date-time - in: query description: Gets shifts breaks with end before (datetime formatted ISO8601) required: false name: endTime schema: type: string format: date-time - in: query description: Comma separated list of shift ids to filter results required: false name: shiftId schema: type: string - in: query description: Comma separated list of user ids to filter results required: false name: userId schema: type: string - in: query description: Comma separated list of location ids to filter results required: false name: locationId schema: type: string - in: query description: Limit results required: false name: limit schema: type: integer - in: query description: Start on page required: false name: page schema: type: integer description: Get scheduled shift breaks tags: - Shift Breaks responses: '200': description: Valid content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ScheduledBreak' '400': description: Bad Request occurs if start/end is in an invalid format content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' /v3/shift-breaks: get: summary: List Shift Breaks description: List actual shift breaks tags: - Shift Breaks parameters: - in: query description: An array of Time query parameters (e.g. ?time[startTime][gte]=2019-01-01T00:00:00Z) name: time schema: type: array items: {} - in: query description: Gets shift breaks with start after (datetime formatted ISO8601) name: startTime required: false schema: type: string format: date-time - in: query description: Gets shift breaks with end before (datetime formatted ISO8601) name: endTime required: false schema: type: string format: date-time - in: query description: Comma separated list of shift ids to filter results name: shiftId required: false schema: type: string - in: query description: Comma separated list of time ids to filter results name: timeId required: false schema: type: string - in: query description: Comma separated list of location ids to filter results name: locationId required: false schema: type: string - in: query description: Comma separated list of user ids to filter results name: userId required: false schema: type: string - in: query description: Only return breaks that are either ended or not ended (0=not ended, 1=ended) name: ended required: false schema: type: integer - in: query description: Limit results name: limit required: false schema: type: integer - in: query description: Start on page name: page required: false schema: type: integer - in: query description: Flag to overwrite the start/end/length values with their rounded counterparts (if account setting is enabled) name: overwriteWithRounded required: false default: false schema: type: integer responses: '200': description: Valid content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ShiftBreak' '400': description: Bad Request occurs if any required field is missing or dates are formatted incorrectly content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' post: summary: Create Shift Break requestBody: content: application/json: schema: type: object required: - timeId properties: timeId: description: The id of the time associated with the break type: integer length: description: Length of break in minutes. If not sent, start must be sent. type: integer start: description: Start of break formated as ISO8601. If not sent, length must be sent. type: string format: date-time end: description: End of break formated as ISO8601. If not sent, start or length must be sent. type: string format: date-time scheduledBreakId: description: The id of the scheduled break associated with the break, used to signal which scheduled break is being clocked in to. Mutually exclusive with `type` field (this field has precedence). When provided, the time must have a shift which has this scheduled break. No other shift breaks must exist with this scheduled break id. type: integer type: description: The type of shift break being created (1=paid, 2=unpaid). When not provided, it is set to 2 (unpaid). Mutually exclusive with `scheduledBreakId` field (the former has precedence). When provided, it must be 1 or 2. type: integer enum: - 1 - 2 example: timeId: 12 length: 15 startTime: '2018-01-01T00:00:00Z' endTime: '2018-01-01T00:15:00Z' type: 1 description: The Shift Break to create description: Create an actual shift break tags: - Shift Breaks responses: '201': description: Valid content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ShiftBreak' '400': description: Bad Request occurs if any required field is missing or attempting to start multiple breaks content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - if an invalid time id is submitted content: application/json: schema: $ref: '#/components/schemas/Error' /v3/shift-breaks/{id}: openapi: 3.0.0 get: summary: Get Shift Break description: Get single shift breaks tags: - Shift Breaks parameters: - in: path description: Shift Break ID name: id required: true schema: type: integer responses: '200': description: Valid content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ShiftBreak' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' patch: summary: Update Shift Break description: Update single shift breaks tags: - Shift Breaks parameters: - in: path description: Shift Break ID name: id required: true schema: type: integer responses: '200': description: Valid content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ShiftBreak' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' delete: summary: Delete Shift Break description: Delete single shift breaks tags: - Shift Breaks parameters: - in: path description: Shift Break ID name: id required: true schema: type: integer responses: '204': description: Deleted '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' /v3/shift-break-audits: openapi: 3.0.0 get: deprecated: true summary: List Shift Break - Paid Rest records description: List Shift Break - Paid Rest records (Deprecated - please refer to the [updated documentation](https://apidocs.wheniwork.com/external/index.html?repo=attendance#tag/Times/paths/~1times~1break-attestations/get)) tags: - Shift Break - Paid Rest parameters: - in: query description: Gets shift breaks with start after (datetime formatted ISO8601) name: startTime required: false schema: type: string format: date-time - in: query description: Gets shift breaks with end before (datetime formatted ISO8601) name: endTime required: false schema: type: string format: date-time - in: query description: Comma separated list of time ids to filter results name: timeId required: false schema: type: string - in: query description: Comma separated list of user ids to filter results name: userId required: false schema: type: string - in: query description: Only return paid rest records for breaks that are either taken or not taken (0=not taken, 1=taken) name: taken required: false schema: type: integer - in: query description: Limit results name: limit required: false schema: type: integer - in: query description: Start on page name: page required: false schema: type: integer responses: '200': description: Valid content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ShiftBreakAudit' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' post: deprecated: true summary: Create Shift Break Paid Record Entry requestBody: content: application/json: schema: type: object required: - timeId - taken properties: timeId: description: The id of the time associated with the break paid record type: integer taken: description: True if all breaks were taken type: boolean note: description: A note that should be populated if taken is false type: string example: timeId: 12 taken: false note: I missed my lunch break description: The Shift Break Paid Rest Entry to create description: Create a Shift Break Paid Rest Entry (Deprecated - Please refer to the [updated documentation](https://apidocs.wheniwork.com/external/index.html?repo=attendance#tag/Times/paths/~1times~1%7Bid%7D~1break-attestations~1/post)) tags: - Shift Break - Paid Rest responses: '201': description: Valid content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ShiftBreakAudit' '400': description: Bad Request occurs if any required field is missing content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - if an invalid time id is submitted content: application/json: schema: $ref: '#/components/schemas/Error' /v3/shift-break-audits/{id}: openapi: 3.0.0 get: deprecated: true summary: Get Shift Break - Paid Rest Record description: Get single shift breaks (Deprecated - Please refer to the [updated documentation](https://apidocs.wheniwork.com/external/index.html?repo=attendance#tag/Times/paths/~1times~1break-attestations/get)) tags: - Shift Break - Paid Rest parameters: - in: path description: Shift Break Paid Rest Record ID name: id required: true schema: type: integer responses: '200': description: Valid content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ShiftBreakAudit' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' delete: deprecated: true summary: Delete Shift Break Paid Rest description: Delete single shift break paid rest (Deprecated - Please refer to the [updated documentation](https://apidocs.wheniwork.com/external/index.html?repo=attendance#tag/Times/paths/~1times~1break-attestations~1%7Bid%7D/delete)) tags: - Shift Break - Paid Rest parameters: - in: path description: Shift Break Paid Rest ID name: id required: true schema: type: integer responses: '204': description: Deleted '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' /v3/auto-assign: openapi: 3.0.0 get: summary: List Auto Scheduled shifts parameters: - in: query description: The start range of the auto-schedule window required: true name: start example: Sun Nov 17 2019 00:00:00 GMT-0600 schema: type: string format: date-time - in: query description: The end range of the auto-schedule window required: true name: end example: Sun Nov 17 2019 00:00:00 GMT-0600 schema: type: string format: date-time - in: query description: Comma separated list of openshift ids to include in auto schedule algorithm required: true name: ids example: 1,2 schema: type: string format: csv - in: query description: The schedule (location) to include in auto schedule algorithm required: true name: location example: '2' schema: type: string - in: query description: The maximum hours any individual can be assigned per week, defaults to 40 required: false name: autoScheduleMaxHours example: 40 schema: type: integer - in: query description: Instruct algorithm to avoid unavailable preferences, defaults to true required: false name: autoScheduleUnavailability example: true schema: type: boolean - in: query description: Instruct algorithm to respect preferences, defaults to false required: false name: autoSchedulePreferredTimes example: false schema: type: boolean - in: query description: Instruct algorithm to allow multiple shifts per day, defaults to false required: false name: autoScheduleMultiShifts example: false schema: type: boolean - in: query description: The maximum hours any individual can be assigned per day required: false name: autoScheduleMaxDailyHours example: 9 schema: type: integer - in: query description: A randomization seed to get predictable assignment results required: false name: seed example: 1 schema: type: integer - in: query description: Instruct algorithm to prioritize weekend shifts (5pm Fri to 11:59pm Sun) during assignment, defaults to false required: false name: autoScheduleWeekendShifts example: true schema: type: boolean - in: query description: Comma separated list of user ids to exclude in auto schedule algorithm required: false name: excludedUserIds example: 1,2 schema: type: string format: csv description: Autoschedule a list of OpenShifts tags: - Shifts responses: '200': description: Valid content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/schemas-Shift' '400': description: Bad Request occurs if start/end is in an invalid format content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' /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' /2/account: get: summary: Get Account description: "This endpoint returns the first account associated with the current login token. To get information about\ \ a different account, set the W-UserId header to the user id associated with the other account. (See the Authentication\ \ section for details.)\n > If the account being queried for is a parent account, the response provides an object\ \ with two members: an `account` object, which specifies the parent account for a given user, and an array, `accounts`,\ \ containing all child accounts of the parent account.\n" tags: - Accounts x-code-samples: - lang: shell source: "curl https://api.wheniwork.com/2/account \\\n -H \"W-Token: ilovemyboss\"\n" responses: '200': description: Valid content: application/json: schema: type: object properties: account: $ref: '#/components/schemas/schemas-Account' post: summary: Create Account description: Used to create an account tags: - Accounts requestBody: $ref: '#/components/requestBodies/AccountRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: success: type: boolean example: true account: $ref: '#/components/schemas/schemas-Account' /2/account/{id}: put: summary: Update Account description: Updates an account tags: - Accounts parameters: - name: id in: path description: The ID of the account schema: type: integer required: true requestBody: $ref: '#/components/requestBodies/AccountRequest' responses: '200': description: Valid content: application/json: schema: type: object properties: account: $ref: '#/components/schemas/schemas-Account' /2/account/settings: post: summary: Update Account Settings description: Admins and Managers can update certain account settings using this endpoint. tags: - Accounts requestBody: $ref: '#/components/requestBodies/AccountSettingsRequest' responses: '200': description: Valid content: application/json: schema: type: object $ref: '#/components/schemas/schemas-Account' /2/account/{id}/admins: get: summary: List Admins description: List all the admins for the given account tags: - Accounts parameters: - name: id in: path description: The ID of the account schema: type: integer required: true responses: '200': description: Valid content: application/json: schema: type: object properties: admins: type: array items: $ref: '#/components/schemas/components-schemas-User' /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 /2/timezones: get: summary: List Timezones description: Fetch a list of timezones tags: - Timezones responses: '200': description: Valid content: application/json: schema: type: object properties: timezone: type: array items: $ref: '#/components/schemas/Timezones' /2/timezones/{id}: get: summary: Get Timezone description: Get a single timezone by ID tags: - Timezones parameters: - name: id in: path description: The ID of the timezone schema: type: integer required: true responses: '200': description: Valid content: application/json: schema: type: object properties: time: $ref: '#/components/schemas/Timezones' components: 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" schemas: 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 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 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 ShiftChain: type: object properties: key: type: string rrule: description: The RFC5545-compliant RRule representing the shift chain. type: string format: RFC5545 example: 'DTSTART;TZID=America/Chicago:20240603T090000 RRULE:FREQ=WEEKLY;UNTIL=20240629T045959Z;WKST=SU;BYDAY=MO,TU,WE,TH,FR ' until: description: The date when the shift chain ends. type: string format: date week: description: Represents the week frequency interval. `1` means weekly, `2` means every two weeks, etc. type: int example: 1 weekdays: description: 'A bitmask of the weekdays which shifts in this chain occur on. In a seven-bit binary number, the most significant bit represents Sunday and the least significant bit represents Monday (0b1000001). Examples: | Days | Binary | Decimal | |---------------------------|-------------|---------| | Monday through Friday | `0b0011111` | 31 | | Monday, Wednesday, Friday | `0b0010101` | 21 | | Saturday and Sunday | `0b1100000` | 96 | ' type: int example: 31 timezone_id: description: The timezone this chain is built in type: string example: America/Chicago count: deprecated: true description: The number of shifts created by this chain. type: int example: 30 Chain: type: object required: timezone_id properties: until: description: 'The date you want the recurrence to end on. It must be in UTC, such that when shifted to the provided timezone (see `timezone_id` below) the time will be midnight in a local time. Example: You''re creating a shift chain in the `America/Chicago` timezone that you want to end on 7/29/24 locally. You would send `2024-07-29T05:00:00Z`, which when converted to the provided timezone would be `2024-07-29T00:00:00-05:00`. **NOTE**: This is required when _creating_ a repeating shift. It may be omitted when editing one. ' type: string format: iso8601 example: '2024-07-29T05:00:00Z' week: description: 'Represents the week frequency interval. `1` means weekly, `2` means every two weeks, etc. **NOTE**: This is required when _creating_ a repeating shift. It may be omitted when editing one. ' type: int example: 2 weekdays: description: 'A bitmask of the weekdays which shifts in this chain occur on. In a seven-bit binary number, the most significant bit represents Sunday and the least significant bit represents Monday (0b1000001). Examples: | Days | Binary | Decimal | |---------------------------|-------------|---------| | Monday through Friday | `0b0011111` | 31 | | Monday, Wednesday, Friday | `0b0010101` | 21 | | Saturday and Sunday | `0b1100000` | 96 | ' type: int example: 31 timezone_id: description: 'The timezone this chain is built in. This must be either the `timezone_id` or `olson_id` from one of the timezones available through [this endpoint](#tag/Timezones). ' type: - string - int example: America/Chicago V2Error: type: object required: - error properties: error: type: string description: A description of the specific error code: oneOf: - type: integer - type: string description: The API error code Time: type: object properties: id: type: integer readOnly: true example: 10000 description: The time id account_id: type: integer readOnly: true example: 10000 description: The account id user_id: type: integer example: 101 description: The user assigned to the time. creator_id: type: integer readOnly: true example: 100 description: The user that created the time. position_id: type: integer example: 19483 description: Position the time belongs to. 0 if unassigned. location_id: type: integer example: 1045 description: Location the time belongs to. 0 if unassigned. site_id: type: integer example: 4351 description: Site the time belongs to. 0 if unassigned. shift_id: type: integer example: 5451 description: A shift tied to this time. 0 if unassigned. start_time: type: string format: date-time example: Fri, 07 Mar 2016 08:30:00 -0600 description: The start time end_time: type: string format: date-time example: Fri, 07 Mar 2016 14:30:00 -0600 description: The end time rounded_start_time: type: string format: date-time example: Fri, 07 Mar 2016 08:30:00 -0600 description: The rounded start time. If rounding is not enabled this field will not be present. rounded_end_time: type: string format: date-time example: Fri, 07 Mar 2016 14:30:00 -0600 description: The rounded end time. If rounding is not enabled this field will not be present. notes: type: string example: A time note description: Notes for a time length: type: float readOnly: true example: 8 description: The length of the time in hours. rounded_length: type: float readOnly: true example: 8 description: The rounded length calculated from the rounded_start_time and rounded_end_time. If rounding is not enabled this field will not be present. hourly_rate: type: float readOnly: true example: 15 description: The base hourly rate for this time. cash_tips: type: string format: decimal nullable: true description: 'Any cash tips reported for the shift. Note: the tips feature is required to see and use this field. ' example: '123.45' alert_type: type: integer readOnly: true example: 16 description: The type of alert for this time is_approved: type: boolean example: false description: If the time is approved modified_by: type: integer readOnly: true example: 18438 description: The user that modified the time sync_id: type: string readOnly: true example: '' description: The quickbooks sync id sync_hash: type: string readOnly: true example: '' description: The quickbooks sync hash updated_at: type: string readOnly: true format: date-time example: Tue, 17 Mar 2020 14:48:43 -0700 description: When the time was updated created_at: type: string readOnly: true format: date-time example: Tue, 17 Mar 2020 14:25:48 -0700 description: When the time was created split_time: type: string readOnly: true format: date-time example: Fri, 07 Mar 2016 00:00:00 -0600 description: If the time crosses payroll periods, when to split it is_alerted: type: boolean readOnly: true example: false description: If alert_type > 0 paid_break_note: type: string default: null readOnly: true example: I am a note entered for the shift break paid record description: The note associated with the shift break paid record. The include_paid_break_note query param must be set to true for this to be returned. 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 PunchResponse: type: object properties: time: description: The Time object that the punch is associated with $ref: '#/components/schemas/Time' overtime_alert: description: Was an over-time alert triggered type: boolean example: false user: description: The User that has punched in $ref: '#/components/schemas/User' punches: description: 'Array of punches associated with the current Time * Punch in/out * Punch break start/stop ' type: array OpenShiftApprovalRequestUser: type: object properties: id: description: The ID of the OpenShift Approval Request type: integer example: 1 user_id: description: The ID of the user that raised their hand for this request type: integer example: 1 created_at: type: string format: date-time example: Thu, 06 Mar 2016 21:12:14 -0600 readOnly: true deleted_at: type: string format: date-time example: Thu, 06 Mar 2016 22:17:14 -0600 readOnly: true OpenShiftApprovalRequest: type: object properties: id: description: The ID of the OpenShift Approval Request type: integer example: 1 readOnly: true account_id: description: The ID of the account that this OpenShift Approval Request belongs to type: integer example: 1 shift_id: description: The ID of the shift that this OpenShift Approval Request is for type: integer example: 1 shift: $ref: '#/components/schemas/Shift' creator_id: description: The ID of the user that created this request type: integer example: 1 readOnly: true updater_id: description: The ID of the user that last updated this request type: integer example: 1 readOnly: true status: description: The current status of the OpenShift Approval Request. type: integer enum: - 0 = Pending - 1 = Approved - 4 = Canceled - 5 = Expired - 6 = Denied example: 0 user_status: description: Copy of the status field to mirror the data model of other request types example: 0 is_shared: description: Is this approval request shared across schedules type: boolean example: false created_at: type: string format: date-time example: Thu, 06 Mar 2016 21:12:14 -0600 updated_at: type: string format: date-time example: Thu, 06 Mar 2016 22:17:14 -0600 readOnly: true user_requests: type: array items: $ref: '#/components/schemas/OpenShiftApprovalRequestUser' readOnly: true ShiftHistory: type: object required: - start_time - end_time - location_id properties: type: description: The type of history event type: string enum: - current - created - confirmed - published - unpublished - reassigned - taken - deleted - location_changed - position_changed - position_removed - site_removed - site_changed - break_changed - break_removed - time_changed - accepted - released example: current attributes: type: object required: - actor - at properties: actor: type: string description: The name of the user that triggered this shift history event at: type: string format: date-time example: Fri, 07 Mar 2016 08:30:00 -0600 description: The timestamp of when this shift history event was recorded reason: type: string example: edit description: A reason code to provide additional context for why a shift history event was recorded enum: - assign - take - delete - split - swap - drop - edit - assign-approve - repeating-delete - overwrite-conflicts-delete - deleted-assigned-user - user-removed-from-schedule - created-from-repeating-series - updated-from-repeating-series - publish - unpublish - delete-bulk - delete-clear user: type: string description: Present in `current`, `created`, `reassigned`, `taken`, `accepted` and `released` events. The new user assigned to the shift. example: John Doe start: type: string format: date-time description: Present in `current`, `created`, and `time_changed` events. The new start time. end: type: string format: date-time description: Present in `current`, `created`, and `time_changed` events. The new end time. position: type: string description: Present in `current`, `created`, `position_changed` and `position_removed` events. The new position. site: type: string description: Present in `current`, `created`, `site_changed` and `site_removed` events. The new site. break: type: float description: Present in `created`, `current`, `break_changed` and `break_removed` events . The new value of shift break. example: 15 ShiftBulk: type: object required: - id - start_time - end_time - location_id properties: id: type: integer 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 color: type: string example: cc000 description: Assign color to shift notes: type: string example: Shift test description: Text notation for a Shift 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. published: type: boolean example: false description: Is the shift published is_open: type: boolean example: false requires_openshift_approval: description: Does this shift require OpenShift Approval type: boolean example: true is_shared: description: Is the shift a shared OpenShift type: boolean example: false schemas-Shift: type: object required: - startTime - endTime - locationId properties: id: type: integer readOnly: true example: 10000 accountId: type: integer example: 10000 userId: type: integer example: 101 description: The user assigned to the shift. Set to `0` for an Open Shift. locationId: type: integer example: 1045 description: Location the shift belongs to positionId: type: integer example: 19483 siteId: type: integer example: 4351 startTime: type: string format: date-time example: '2017-10-23T05:00:00+00:00' endTime: type: string format: date-time example: '2017-10-23T13:00:00+00:00' breakTime: type: float example: 0.5 color: type: string example: cc0000 alerted: type: bool example: false shiftchainKey: type: string published: type: bool example: true notifiedAt: type: string format: date-time example: '2017-10-23T19:18:01+00:00' createdAt: type: string format: date-time example: '2017-10-23T19:17:59+00:00' updatedAt: type: string format: date-time example: '2017-10-23T19:18:00+00:00' acknowledged: type: bool example: false instances: type: integer example: 1 Error: type: object required: - error properties: error: type: object required: - code - title properties: code: description: The API error code type: string title: description: The API error code description type: string errorData: description: Context for the error Position: type: object properties: id: type: integer readOnly: true example: 10000 account_id: type: integer example: 10000 name: type: string example: Dishwasher color: type: string example: cc0000 sort: type: integer example: 2 description: Custom sort order applied to this position tips_tracking: type: boolean example: true description: 'Whether this position tracks tips. Note: the tips feature is needed to use this field. ' created_at: type: string format: date-time example: Thu, 06 Mar 2016 21:12:14 -0600 updated_at: type: string format: date-time example: Thu, 06 Mar 2016 22:17:14 -0600 Place: type: object properties: address: type: string example: '420 N 5th St #500, Minneapolis, MN 55401, USA' business_name: type: string example: When I Work country: type: string example: US id: type: integer example: 2 latitude: type: number format: float example: 44.983791 locality: type: string example: Minneapolis longitude: type: number format: float example: -93.277442 place_id: type: string example: ChIJYfRBzjfVslIRQLB018IGX3o place_type: type: array example: - point_of_interest - establishment postal_code: type: string example: '55401' region: type: string example: MN street_name: type: string example: N 5th St street_number: type: string example: '420' sub_locality: type: string updated_at: type: string format: date-time example: '2019-05-16T09:14:45+05:45' Schedule: type: object properties: id: type: integer readOnly: true example: 10000 account_id: type: integer example: 10000 name: type: string example: Front of House address: type: string example: '420 N 5th St #500, Minneapolis, MN 55401, USA' coordinates: type: array example: - 44.983791 - -93.2774416 deleted_at: type: string format: date-time ip_address: type: string format: ipv4 example: 192.168.1.1 is_default: type: boolean example: false is_deleted: type: boolean example: false latitude: type: number format: float example: 44.983791 longitude: type: number format: float example: -93.2774416 max_hours: type: integer example: 0 place: $ref: '#/components/schemas/Place' place_confirmed: type: boolean example: true place_id: type: string example: 2 radius: type: integer example: 100 sort: type: integer example: 0 created_at: type: string format: date-time example: '2019-05-16T06:57:28+05:00' updated_at: type: string format: date-time example: '2019-05-16T06:57:28+05:00' Site: type: object properties: id: type: integer readOnly: true example: 10000 account_id: type: integer example: 10000 location_id: type: integer example: 145030 name: type: string example: Main venue. color: type: string example: 8da6d9 description: type: string example: Large meeting room address: type: string example: '420 N 5th St #500, Minneapolis, MN 55401, USA' coordinates: type: array example: - 44.983791 - -93.2774416 latitude: type: number format: float example: 44.983791 longitude: type: number format: float example: -93.2774416 place: $ref: '#/components/schemas/Place' place_id: type: string example: 2 is_deleted: type: boolean example: false deleted_at: type: string format: date-time created_at: type: string format: date-time example: '2020-05-16T06:57:28+05:00' updated_at: type: string format: date-time example: '2020-05-26T06:57:28+05:00' BlockScheduledBreak: allOf: - $ref: '#/components/schemas/BaseScheduledBreak' - type: object properties: block_id: type: integer example: 1234 description: The ID of the shift template that the break applies to. readOnly: true start_time: example: '9:30:00' description: The start time of the break. Null if the break does not have a start time. type: string end_time: example: '10:00:00' 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 ShiftTemplate: type: object properties: id: type: integer readOnly: true example: 10000 account_id: type: integer example: 10000 break_time: type: number format: double example: 0.5 breaks: description: An array of breaks for the shift template. When updating a template, any existing breaks for the shift that are not included in the request will be deleted. type: array items: $ref: '#/components/schemas/BlockScheduledBreak' color: type: string example: 8da6d9 end_time: type: string example: '17:00:00' start_time: type: string example: 09:00:00 location_id: type: integer example: 10000 notes: type: string example: Here are some shift notes position_id: type: integer example: 10000 created_at: type: string format: date-time example: '2019-05-16T06:57:28+05:00' updated_at: type: string format: date-time example: '2019-05-16T06:57:28+05:00' ScheduleTemplate: type: object properties: id: type: integer readOnly: true example: 10000 account_id: readOnly: true type: integer example: 10000 name: type: string example: Typical Work Week description: type: string example: Use this template for most work weeks start_date: type: string example: '2019-05-12' end_date: type: string example: '2019-05-18' location_id: type: integer example: 10000 deprecated: true user_id: type: integer example: 10000 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' ScheduleTemplateShift: allOf: - $ref: '#/components/schemas/Shift' - type: object properties: template_id: type: integer example: 10000 Annotation: type: object properties: id: type: integer readOnly: true example: 10000 account_id: type: integer example: 10000 readOnly: true all_locations: type: boolean example: false announcement: type: boolean example: false business_closed: type: boolean example: true color: type: string example: cccccc creator_id: type: integer example: 1000 readOnly: true end_date: type: string format: date-time example: '2019-05-23T23:59:59+05:00' locations: type: array items: ref: schedules.yaml#/components/schemas/Schedule message: type: string example: asdf no_time_off: type: boolean example: false start_date: type: string format: date-time example: '2019-05-23T00:00:00+05:00' title: type: string example: Example Annotation required: true relevant_at: type: string format: date-time readOnly: true description: Read only date set to 2 weeks before start date example: '2019-05-09T00:00:00+05:45' 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' AvailabilityEvent: type: object required: - start_time - type properties: id: type: integer readOnly: true example: 10000 account_id: type: integer example: 10000 user_id: type: integer example: 10000 login_id: type: string example: '10000' type: type: integer example: 1 enum: - 1 - 2 description: Type code. 1 for "unavailable", 2 for "preferred" start_time: type: string format: date-time example: Thu, 06 Mar 2016 21:12:14 -0600 description: Start time of the event. Must be no more than 24 hours in the past end_time: type: string format: date-time example: Thu, 06 Mar 2016 21:12:14 -0600 description: End time of the event. If "all_day" is sent and true, this field is optional all_day: type: boolean example: false notes: type: string example: No evenings in March description: Maximum of 160 characters recurrence: type: string example: FREQ=YEARLY;INTERVAL=2;COUNT=5;BYMONTH=1,2,3 description: Recurrence rule. See https://tools.ietf.org/html/rfc5545 recurrence_end: type: string readOnly: true format: date-time example: Thu, 06 Mar 2016 21:12:14 -0600 description: End date of the recurring series. Null for "does not repeat" or "repeats infinitely" created_at: type: string format: date-time example: Thu, 06 Mar 2016 21:12:14 -0600 updated_at: type: string format: date-time example: Thu, 06 Mar 2016 22:17:14 -0600 Request: properties: id: description: Unique ID of the request. type: integer account_id: description: The ID of the account this request belongs to. type: integer created_at: description: Full datetime the request was created. format: date-time type: string creator_id: description: The ID of the user creating the request. type: integer end_time: description: Full datetime the request ends at. format: date-time type: string hours: description: The number of hours of paid time off to use. format: float type: number status: description: "The current status of the request. The field user_status is more\ngranular (it supports the Denied\ \ status) and should be used instead of\nstatus..\n * `0` = Pending\n * `1` = Canceled\n * `2` = Accepted\n\ \ * `3` = Expired\n" enum: - 0 - 1 - 2 - 3 type: integer start_time: description: Full datetime the request starts at. format: date-time type: string type: type: integer nullable: true deprecated: true description: "DEPRECATED IN FAVOR OF `type_id`. SEE Request Type.\n\nThe type of timeoff request being made\n *\ \ `0` - Unpaid Time Off\n * `1` - Paid Time Off\n * `2` - Sick\n * `3` - Holiday\n" type_id: description: 'The RequestType ID referencing the type of timeoff (Personal, Sick, Holiday). Only certain plans can create non-built-in types. ' type: integer type_label: description: The label for the custom timeoff type (Personal, Sick, Holiday) type: string readOnly: true paid: description: If the timeoff request is for paid timeoff type: boolean updated_at: description: Full datetime the request was last updated. format: date-time type: string user_id: description: The ID of the user requesting time off. type: integer can_edit: readOnly: true description: 'Is the timeoff request editable by the authenticated user. * `true` * `false` ' type: boolean example: false user_status: description: 'The current user status of the request. * `0` = Pending * `1` = Canceled * `2` = Accepted * `3` = Expired * `4` = Denied ' enum: - 0 - 1 - 2 - 3 - 4 type: integer type: object 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 RequestType: properties: id: description: Unique ID of the request type. type: integer example: 123 account_id: description: The ID of the account this request type belongs to. type: integer example: 321 name: type: string description: Label for the time off request type. example: Holiday built_in: type: boolean description: Is this a default type all accounts have or a custom type. Built in types cannot be deleted. example: true enabled: type: boolean description: Enabled toggles if the type is available for selecting. example: true allow_paid: type: boolean description: Describes if the timeoff type is available for paid time off. example: true allow_unpaid: type: boolean description: Describes if the timeoff type is available for unpaid time off. example: true is_deleted: type: boolean description: Has the timeoff type been deleted. example: false created_at: type: string description: Full datetime for when the type was created in ISO8601. updated_at: type: string description: Full datetime for when the type was last updated in ISO8601. deleted_at: type: string description: Full datetime for when the type was deleted in ISO8601. 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 PunchStateShiftBreakBase: type: object properties: id: description: The shift break id type: integer example: 2 account_id: description: The account id associated with the break type: integer example: 3 time_id: description: The time id associated with the break type: integer example: 1 type: description: The type of break (1=paid, 2=unpaid) type: integer example: 2 creator_id: description: The id of the user who created the break type: integer example: 238 auto_deducted: description: Whether the break was auto deducted (0 = false, 1 = true) type: integer example: 0 edited_by: description: The id of the user who edited the break type: integer example: 238 skipped: description: Whether the break was skipped (0 = false, 1 = true) type: integer example: 0 created_at: description: Date and time the break was created at type: string format: date-time example: 2025-05-19T11:25:04-0400 updated_at: description: Date and time the break was last updated type: string format: date-time example: 2025-05-19T11:25:04-0400 scheduledbreaks_id: description: The scheduled break associated with this shift break, if it is a scheduled break. Otherwise `0` type: integer example: 0 PunchStateRootShiftBreak: allOf: - $ref: '#/components/schemas/PunchStateShiftBreakBase' - type: object properties: start: description: The break start time type: string format: date-time example: 2025-05-19T10:45:00-0400 end: description: The break end time. Will always be an empty string; once the break has an end, it is no longer returned by this endpoint under the `break` key type: string format: date-time example: '' length: description: The break length from the database model once the break is complete, in minutes. Until the break is complete, this value remains zero. However, once the break is complete, the `break` object is not longer returned by this endpoint. Hence, break length should be calculated based on the `start` instead type: integer example: 0 PunchStateNestedShiftBreak: allOf: - $ref: '#/components/schemas/PunchStateShiftBreakBase' - type: object properties: start: description: The break start time. Null if the break does not have an start time. Perhaps because it was added on Timesheets. type: string format: date-time nullable: true example: 2025-05-19T10:00:00-0400 end: description: The break end time. Null if the break does not have an end time. Perhaps because it was added on Timesheets. type: string format: date-time nullable: true example: 2025-05-19T10:08:00-0400 length: description: The length of the break if it's completed, in minutes. Length will be zero until the break has ended type: integer example: 6 PunchStateScheduledBreak: allOf: - type: object properties: id: type: integer description: Scheduled Break Id example: 1 account_id: type: integer description: Account Id associated with this break example: 3 start_time: description: The start time of the break. Null if the break does not have a start time type: string example: '2025-05-19T14:30:00+00:00' end_time: 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 example: '2025-05-19T14:45:00+00:00' length: description: The length of the break (seconds) type: integer example: 900 paid: description: Whether the break is a paid rest break (true) or unpaid meal break (false) type: boolean example: true created_by: description: The id of the user who created the break type: integer example: 201 created_at: description: Date and time the break was created at type: string example: '2025-05-10T14:45:00+00:00' updated_by: description: The id of the user who last edited the break type: string example: '202' updated_at: description: Date and time the break was last updated type: string example: '2025-05-10T15:45:00+00:00' 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 shift_id: type: integer example: 1234 description: The ID of the shift that the break applies to readOnly: true shift_break: type: object description: When not null, at least a start time was created for an associated shift break. Otherwise, no breaks have been taken for this scheduled break $ref: '#/components/schemas/PunchStateNestedShiftBreak' Payroll: type: object description: 'Payroll is a pay period (start and end) and a collection paid hours (worked or paid time off) within that pay period. ' properties: id: type: integer readOnly: true example: 100000 description: The payroll ID account_id: type: integer example: 100000 description: The ID of the account that the payroll belongs to creator_id: type: integer example: 1000000 description: The ID of the user that created the payroll (pay period) start_date: type: string format: date-time example: Sun, 16 May 2021 00:00:00 -0500 description: When the pay period for this payroll starts (RFC 2822) end_date: type: string format: date-time example: Sat, 29 May 2021 23:59:59 -0500 description: When the pay period for this payroll ends (RFC 2822) offset: type: string format: time example: 00:00:00 description: Time offset from midnight for when the pay period should start or end (hours:mins:seconds) notes: type: string example: Holiday payroll run. description: Notes about this pay period deprecated: true is_edited: type: boolean example: false description: Has the payroll been edited after being generated deprecated: true is_closed: type: boolean example: false description: 'If the payroll (pay period) is closed. **Note** An open pay period will build out live data from `hourstats`. A closed pay period will have a snapshot of the data from the time of closing called `payrollhours` ' closed_at: type: string format: date-time example: Sun, 16 May 2021 00:00:00 -0500 description: When the payroll (pay period) was closed (RFC 2822) deprecated: true is_finalized: type: boolean example: false description: A finalized pay period that has been reviewed and fully approved deprecated: true finalized_at: type: string format: date-time example: Sun, 16 May 2021 00:00:00 -0500 description: When the payroll (pay period) was finalized (RFC 2822) deprecated: true nullable: true created_at: type: string format: date-time example: Mon, 03 May 2021 09:35:38 -0500 description: Time when the pay period was created (RFC 2822) updated_at: type: string format: date-time example: Thu, 10 Jun 2021 10:19:47 -0500 description: Time when the pay period was last updated (RFC 2822) PayrollHours: type: object description: The paid time for users within a given payroll (broken out by type, split as needed when crossing pay periods) properties: id: description: The unique ID of the payroll hours object. type: integer payroll_id: description: The ID of the Payroll this object belongs to. type: integer type: type: integer description: "The type of time associated with the payroll hours\n * `1` - Regular Time\n * `2` - Over Time\n *\ \ `3` - Paid Time Off\n * `4` - Holiday\n * `5` - Double Time\n * `6` - Sick\n * `7` - Time Off (custom type,\ \ unpaid time-off not included)\n" type_label: description: The label for the type of time off if a timeoff type (Personal, Sick, Holiday) type: string readOnly: true user_id: description: The ID of the user who these hours belong to. type: integer position_id: description: The ID of the position that is associated with these hours. Default 0 for none. type: integer hours: description: The number hours. type: number format: float rate: description: The hourly rate paid for these hours. type: number format: float total: description: The total wages for these hours. type: number format: float AbsenceActions: type: object required: - actionType - createdBy - createdAt properties: actionType: type: string enum: - timeoff - drop - swap - moved-to-open description: Type of action taken on the shift createdBy: type: string description: The user ID of who created the action. example: '221' createdAt: type: string format: date-time readOnly: true shiftId: type: string description: Will be present if move to open action was taken. example: '221' requestId: type: string description: Will be present if a time-off action was taken. example: '125' swapId: type: string description: Will be present if a swap or drop action was taken. example: '312' Absence: type: object required: - userId - shiftId - shiftStartTime - shiftEndTime - locationId - creatorId properties: id: type: string example: '1' description: ID of the absence readOnly: true accountId: type: string example: '7' description: Account ID of the absence readOnly: true userId: type: string example: '226' description: User ID of the absence shiftId: type: string example: '9' description: Shift ID of the absence shiftStartTime: type: string format: date-time example: '2016-12-19T16:39:57-08:00' description: Start time of the shift shiftEndTime: type: string format: date-time example: '2016-12-19T16:39:57-08:00' description: End time of the shift locationId: type: string example: '13' description: Location ID of the absence siteId: type: string example: '10' description: Site ID of the absence positionId: type: string example: '38' description: Position ID of the absence creatorId: type: string example: '226' description: User ID of the creator of the absence notes: type: string example: Absence note description: Note of the absence actions: type: array description: List of actions taken on a shift. items: $ref: '#/components/schemas/AbsenceActions' readOnly: true createdAt: type: string format: date-time example: '2016-12-19T16:39:57-08:00' description: Time the absence was created readOnly: true updatedBy: type: integer example: 226 description: User ID of the last updater of the absence updatedAt: type: string format: date-time example: '2016-12-19T16:39:57-08:00' description: Time the absence was last updated readOnly: true isDeleted: type: boolean example: false description: Whether the absence has been deleted readOnly: true Notice: type: object properties: time_id: type: integer description: The ID of the time that generated the notice. user_id: type: integer description: The ID of the user who the notice is for. shift_id: type: integer description: 'The ID of the shift that generated the notice of is associated with the time or absence which generated the notice. ' title: type: string description: The title of the notice, matches the code. enum: - Wrong Location - Forgot to Clock Out - Not Scheduled - Absent - No Show - Clocked In Early - Clocked In Late - Clocked Out Early - Clocked Out Late - Missed Clock In code: type: integer description: 'The type of notice. Matches the title. * `103` - Wrong Location * `107` - Forgot to Clock Out * `110` - Not Scheduled * `121` - Absent * `120` - No Show * `131` - Clocked In Early * `132` - Clocked In Late * `133` - Clocked Out Early * `134` - Clocked Out Late * `135` - Missed Clock In ' punch_id: type: integer description: The ID of the punch that generated the notice. absence_id: type: integer description: The ID of the absence that generate the notice. created_at: type: string format: date-time description: 'The time the notice was created at. This depends on the kind of entity that generated the notice. For example, this could be the `created_at` time of the punch, `start_time` of the time, `start_time` or `end_time` of the shift, or the `created_at` time of the absence. ' Punch: type: object properties: id: type: integer description: The ID of the punch. account_id: type: integer description: The ID of the account the punch is associated with. location_id: type: integer description: The ID of the schedule that the punch is associated with. alert_type: type: integer description: 'A bitmask representing any alerts that might apply to the punch. ' method: type: integer description: A bitmask representing how the punch was created. See `method_name` for a human readable version. method_name: type: string nullable: true description: How the punch was created. enum: - Third Party App - Mobile - Computer - Terminal site_id: type: integer description: The ID of the site the punch is associated with. type: type: integer description: A code representing whether the punch was an "In" (`1`) or "Out" (`2`) punch. time_id: type: integer description: The ID of the time the punch is associated with. user_id: type: integer description: The ID of the user who is punching in or out. accuracy: type: number format: float description: The radius of uncertainty for the punch coordinates in meters. altitude: type: number format: float description: The altitude of the punch in meters. latitude: type: number format: float description: The latitude coordinate of the punch. longitude: type: number format: float description: The longitude coordinate of the punch. ip_address: type: string description: The IP address of the device used to create the punch. notes: type: string description: Any notes associated with the punch. FreeTrialStatus: type: object properties: status: description: 'Current status for the free trial * `available` - Free trial is available for the account * `active` - Free trial is currently active for the account * `unavailable` - Account is not currently eligible for a free trial ' type: string enum: - available - active - unavailable example: unavailable type: description: 'The type of free trial that the account currently has or is available or is eligible for * `small-business` - Small business free trial * `enterprise` - Enterprise free trial * `undefined` - Error determining eligibility ' type: string enum: - small-business - enterprise - undefined nullable: true expiresDate: description: When the current subscription expires. ISO 8601 format. type: string format: date-time nullable: true renewalDate: description: When a new subscription for the account will be available. type: string format: date-time nullable: true featureSet: description: "The set of features that will be added to the account from this subscription.\n\n**Note**: Only set\ \ when the subscription status is `available`.\n\n**Example**\n```\n \"featureSet\": {\n \"attendance\"\ : true,\n \"auto-assign\": true,\n \"coverage-view\": true,\n \"custom-timeoff-types\": true,\n\ \ \"doc-storage\": true,\n }\n" type: object additionalProperties: true example: attendance: true auto-assign: true coverage-view: true nullable: true deniedReason: description: 'The reason that the account is not eligible for a free subscription * `currently-active` - A free trial is currently active * `renewal-backoff` - The account needs to wait before a free trial becomes available again * `account-type-child` - The account is a child account and not eligible * `account-plan-not-eligible` - The accounts current plan is ineligible for a free trial * `no-new-features` - The account would receive no new features from the trial subscription * `account-too-new` - The account was created too recently to be eligible for a free trial * `account-inactive` - The accounts is inactive and not eligible * `account-deleted` - The accounts is deleted and not eligible ' type: string enum: - currently-active - renewal-backoff - account-type-child - account-plan-not-eligible - no-new-feature - account-too-new - account-inactive - account-deleted nullable: true HourAndWageTotals: type: object required: - regularHours - overtimeHours - doubleOvertimeHours - regularWages - overtimeWages - doubleOvertimeWages - totalHours - totalWages properties: regularHours: description: Number of regular hours type: number overtimeHours: description: Number of overtime hours type: number doubleOvertimeHours: description: Number of double overtime hours type: number regularWages: description: Number of regular wages type: number overtimeWages: description: Number of overtime wages type: number doubleOvertimeWages: description: Number of double overtime wages type: number totalHours: description: Total number of hours type: number totalWages: description: Total number of wages type: number HourAndWageTotalsWithRequests: type: object required: - regularHours - overtimeHours - doubleOvertimeHours - regularWages - overtimeWages - doubleOvertimeWages - totalHours - totalWages - ptoHours - sickHours - holidayHours - ptoWages - sickWages - holidayWages - totalPaidHours - totalPaidWages properties: regularHours: description: Number of regular hours type: number overtimeHours: description: Number of overtime hours type: number doubleOvertimeHours: description: Number of double overtime hours type: number regularWages: description: Number of regular wages type: number overtimeWages: description: Number of overtime wages type: number doubleOvertimeWages: description: Number of double overtime wages type: number ptoHours: description: Number of pto hours type: number sickHours: description: Number of sick hours type: number holidayHours: description: Number of holiday hours type: number ptoWages: description: Number of pto wages type: number sickWages: description: Number of sick wages type: number holidayWages: description: Number of holiday wages type: number totalHours: description: Total number of hours type: number totalWages: description: Total number of wages type: number totalPaidHours: description: Total number of paid hours (includes requests) type: number totalPaidWages: description: Total number of paid wages (includes requests) type: number paidTimeoff: description: "Time off for the period grouped by type\n```json\n\"paidTimeoff\": {\n \"24\": {\n \"hours\"\ : 8,\n \"wages\": 80\n },\n \"27\": {\n \"hours\": 16,\n \"wages\": 160\n }\n}\n\ ```\n" type: object additionalProperties: type: object additionalProperties: type: object properties: hours: description: Hours for the timeoff type type: number wages: description: Wages for the timeoff type type: number ScheduledAndActual: type: object required: - scheduled - actual properties: scheduled: $ref: '#/components/schemas/HourAndWageTotals' actual: $ref: '#/components/schemas/HourAndWageTotalsWithRequests' HoursByUser: type: object allOf: - $ref: '#/components/schemas/ScheduledAndActual' - type: object required: - identifier properties: identifier: description: The user id type: string HoursByPosition: type: object allOf: - $ref: '#/components/schemas/ScheduledAndActual' - type: object required: - identifier properties: identifier: description: The position id type: string HoursByLocation: type: object allOf: - $ref: '#/components/schemas/ScheduledAndActual' - type: object required: - identifier properties: identifier: description: The location id type: string HoursBySite: type: object allOf: - $ref: '#/components/schemas/ScheduledAndActual' - type: object required: - identifier properties: identifier: description: The site id type: string HoursByWeek: type: object allOf: - $ref: '#/components/schemas/ScheduledAndActual' - type: object required: - identifier properties: identifier: description: The week start date formatted in ISO8601 type: string HoursByPayroll: type: object allOf: - $ref: '#/components/schemas/ScheduledAndActual' - type: object required: - identifier properties: identifier: description: The payroll week date formatted in ISO8601 type: string HoursByDay: type: object allOf: - $ref: '#/components/schemas/ScheduledAndActual' - type: object required: - identifier properties: identifier: description: The day date formatted as Y-m-d type: string HourWageStats: type: object required: - users - positions - locations - sites - weeks - payrolls - days - totals properties: users: description: Hours and wages by user type: array items: $ref: '#/components/schemas/HoursByUser' positions: description: Hours and wages by position type: array items: $ref: '#/components/schemas/HoursByPosition' locations: description: Hours and wages by location type: array items: $ref: '#/components/schemas/HoursByLocation' sites: description: Hours and wages by site type: array items: $ref: '#/components/schemas/HoursBySite' weeks: description: Hours and wages by week type: array items: $ref: '#/components/schemas/HoursByWeek' payrolls: description: Hours and wages by payroll week type: array items: $ref: '#/components/schemas/HoursByPayroll' days: description: Hours and wages by day type: array items: $ref: '#/components/schemas/HoursByDay' totals: $ref: '#/components/schemas/ScheduledAndActual' Hours: description: Hours for a given day. properties: doubleOvertimeHours: description: Number of hours classified as double overtime. format: double type: number overtimeHours: description: Number of hours classified as daily overtime hours. format: double type: number regularHours: description: Number of hours classified as regular hours. format: double type: number totalHours: description: Total number of hours. format: double type: number weeklyOvertimeHours: description: 'Number of weekly overtime hours. Weekly hours are hours above the account''s weekly overtime threshold that are not classified as double overtime hours for a given day. ' format: double type: number required: - doubleOvertimeHours - overtimeHours - regularHours - totalHours - weeklyOvertimeHours type: object OvertimeUser: properties: days: additionalProperties: properties: actual: $ref: '#/components/schemas/Hours' normalized: $ref: '#/components/schemas/Hours' scheduled: $ref: '#/components/schemas/Hours' required: - normalized type: object description: 'Normalized hours, optionally with scheduled and actual hours with the given date as the key. ' example: 2019-03-24T00:00:00-0500: normalized: doubleOvertimeHours: 6 overtimeHours: 2 regularHours: 8 totalHours: 16 weeklyOvertimeHours: 0 id: description: User's ID example: 1234 format: int64 type: integer maxHours: description: Maximum hours example: 40 format: int32 type: integer weeks: additionalProperties: properties: normalized: $ref: '#/components/schemas/Hours' required: - normalized type: object description: Normalized hours, summarized by week. example: 2019-03-24T00:00:00-0500: normalized: doubleOvertimeHours: 36 overtimeHours: 10 regularHours: 40 totalHours: 96 weeklyOvertimeHours: 10 required: - days - id - maxHours - weeks type: object Overtime: properties: accountSettings: description: Overtime thresholds for the account. properties: dailyDoubleOvertimeThreshold: description: Threshold for daily hours to be double overtime. example: 10 format: int32 type: integer dailyOvertimeThreshold: description: Threshold for daily hours to be overtime. example: 8 format: int32 type: integer weeklyOvertimeThreshold: description: Threshold for weekly hours to be overtime. example: 40 format: int32 type: integer required: - dailyDoubleOvertimeThreshold - dailyOvertimeThreshold - weeklyOvertimeThreshold type: object users: type: array items: $ref: '#/components/schemas/OvertimeUser' required: - accountSettings - users type: object Meta: description: 'Meta information about the request, showing the state of query parameters and additional account settings. ' properties: convertedEndDate: description: 'End date the resource is returning, pushed out to the end of a week if the requested date is not at the end. Defaults to the end of the current week. ' example: 2019-03-30T23:59:59-0500 format: date-time type: string convertedStartDate: description: 'Start date the resource is returning, pushed back to the beginning of a week if the requested date is not at the beginning. Defaults to the beginning of the current week. ' example: 2019-03-24T00:00:00-0500 format: date-time type: string excludeUnpublished: description: 'Whether the resource is excluding shifts that have been placed in the scheduler, but not published. ' enum: - false - true type: string hasAttendance: description: 'Whether the currently logged in account has the attendance feature. ' enum: - false - true type: string includeRaw: description: 'Whether the resource is including raw statistics, meaning that it will return scheduled and actual blocks for days in addition to the actual and scheduled blocks. ' enum: - false - true type: string locations: description: List of location IDs the request is filtered to. example: ☃,10,42 type: string originalEndDate: description: 'End date sent by the client, which may be empty or improperly formatted. ' example: '2019-03-29' type: string originalStartDate: description: 'Start date sent by the client, which may be empty or improperly formatted. ' example: 2019-03-24T12:34:56-0600 type: string positions: description: List of position IDs the request is filtered to. example: 1,☃,42 type: string sites: description: List of site IDs the request is filtered to. example: 9,☃,42 type: string startOfWeek: description: Day abbreviation for the account's start of week setting. enum: - Sun - Mon - Tue - Wed - Thu - Fri - Sat type: string users: description: 'Users parameter sent by the client, which may be empty or improperly formatted. ' example: ,99,1000 type: string required: - convertedEndDate - convertedStartDate - excludeUnpublished - hasAttendance - includeRaw - locations - originalEndDate - originalStartDate - positions - sites - startOfWeek - users type: object HourStats: type: object required: - id - start - startOfDay - userId - regular - dailyOt - weeklyOt - dailyDoubleOt - breakTime properties: id: description: The ID of the shift, time, or request. type: number example: 10123 start: description: The start time of the shift or time or request. type: string example: '2019-01-01T00:00:00Z' end: description: The end time of the shift or time. If the `includeOngoing` parameter is specified, this may be missing for some times. type: string example: '2019-01-01T00:00:00Z' startOfDay: description: The start of the work day for the given shift. type: string example: '2019-01-01T00:00:00Z' userId: description: The ID of the user this is for. type: number example: 323484 positionId: description: The ID of the position this is for. type: number example: 3490234 locationId: description: The ID of the location this is for. type: number example: 19643 siteId: description: The ID of the site this is for. type: number example: 48432 regular: description: The count of regular hours. Breaks are already subtracted. type: number example: 8 dailyOt: description: The count of daily overtime hours. type: number example: 4 weeklyOt: description: The count of weekly overtime hours. type: number example: 4 dailyDoubleOt: description: The count of daily double overtime hours. type: number example: 1.34 breakTime: description: The amout of recorded break time in minutes. This is already subtracted and only for reference. type: number example: 30 hourlyRate: description: The user's hourly rate. Will be missing if the authorized user does not have access. type: number example: 8.45 otRate: description: The user's blended overtime rate. Will be missing if the authorized user does not have access. type: number example: 12.34 doubleOtRate: description: The user's double overtime rate. Will be missing if the authorized user does not have access. type: number example: 9.9 RequestHourStats: type: object required: - id - start - end - startOfDay - userId - hours - type - typeId - paid properties: id: description: The ID of the request. type: number example: 10123 start: description: The start and end time of the request. In the event of a multi-day request, this will be the start of the workday. type: string example: '2019-01-01T00:00:00Z' end: description: The end time of the request. In the event of a multi-day request, this will be the end of the workday. type: string example: '2019-01-01T00:00:00Z' startOfDay: description: The start of the work day for the given request. type: string example: '2019-01-01T00:00:00Z' userId: description: The ID of the user this is for. type: number example: 323484 hours: description: The count of hours. type: number example: 8 hourlyRate: description: The user's hourly rate. Will be missing if the authorized user does not have access. type: number example: 8.45 type: description: The type of request (pto = 1, sick = 2, holiday = 3) type: number example: 1 typeId: description: Reference to the request-type for this timeoff request (Personal, Sick, Holiday, ...) type: number example: 1 paid: description: If the timeoff request is paid or unpaid time off type: boolean example: true Timezone: type: object required: - name properties: name: type: string example: America/Chicago schemas-User: type: object required: - accountId properties: id: type: string readOnly: true example: 1 accountId: type: integer example: 1 personId: type: string example: 9100000 role: type: integer example: 1 timezone: $ref: '#/components/schemas/Timezone' createdBy: type: number example: 123456 roles: type: array items: type: string example: - ROLE_SUPERVISOR - ROLE_EMPLOYEE payroll: type: boolean example: false trusted: type: boolean example: false type: type: integer example: 1 email: type: string format: email firstName: type: string example: Bobbie lastName: type: string example: Lehner phoneNumber: type: string example: 9025551234 employeeCode: type: string example: XTR1234 activated: type: boolean example: true hidden: type: boolean example: false uuid: type: string example: 9d0b5296-9b67-4d93-bf8b-d716f869f7db notes: type: string example: my note private: type: boolean example: true hoursPreferred: type: float example: 10.5 hoursMax: type: float example: 40 hourlyRate: type: float example: 15.15 alertSettings: type: array example: [] reminderTime: type: integer example: 2 sleepStart: type: string example: '23:00:00' sleepEnd: type: string example: 05:00:00 myPositions: type: array example: [] locations: type: array items: type: number example: 1234 positions: type: array items: type: object required: - userId - positionId properties: userId: type: number example: 123456 positionId: type: number example: 123456 hourlyRate: type: number example: 15.5 onboarded: type: boolean example: false lastLogin: type: string format: date-time example: '2017-10-23T19:17:29+00:00' dismissedAt: type: string format: date-time example: '2017-10-23T19:17:29+00:00' notifiedAt: type: string format: date-time example: '2017-10-23T19:17:29+00:00' invitedAt: type: string format: date-time example: '2017-10-23T19:17:29+00:00' createdAt: type: string format: date-time example: '2017-10-23T19:16:32+00:00' updatedAt: type: string format: date-time example: '2017-10-23T19:17:34+00:00' deletedAt: type: string format: date-time example: '2017-10-23T19:17:34+00:00' deleted: type: boolean example: false Account: type: object properties: id: type: integer readOnly: true example: 1 company: type: string timezone: $ref: '#/components/schemas/Timezone' ShiftBreak: type: object required: - id - timeId - creatorId - type - length - isPunched properties: id: description: The shift break id type: integer timeId: description: The time id associated with the break type: integer creatorId: description: The id of the user who created the break type: integer type: description: The type of break (1=paid, 2=unpaid) type: integer length: description: The break time rounded to the nearest minute type: integer isPunched: description: If the break was punched type: boolean editedBy: description: The id of the user who edited the break type: integer start: description: The break start time type: string format: date-time end: description: The break end time type: string format: date-time roundedStartTime: description: The rounded start time. Will only be visible if rounding is enabled. type: string format: date-time roundedEndTime: description: The rounded end time. Will only be visible if rounding is enabled. type: string format: date-time roundedLength: description: The break time rounded based on the roundedStartTime and roundedEndTime if punched. If not punched, rounded to the nearest minute increment when rounding is enabled. type: integer isOrphaned: description: If the break begins after its associated time entry ends. type: boolean scheduledBreakId: description: The scheduled break associated with this shift break, if it is a scheduled break. Otherwise `0` type: integer example: id: 34 timeId: 12 creatorId: 43 type: 2 length: 15 isPunched: true start: 2018-01-01T00:00:00+00:00:00 end: 2018-01-01T00:15:00+00:00:00 scheduledBreakId: 0 schemas-Time: type: object required: - id - userId - creatorId - length - alertType - isApproved - startTime properties: id: description: The time id type: number userId: description: The user id of the user that worked this time type: number creatorId: description: The user id that created this time type: number positionId: description: The position id worked type: number locationId: description: The location id worked type: number siteId: description: The site id worked type: number shiftId: description: The associated shift id type: number startTime: description: The start of the time type: string endTime: description: The end of the time type: string roundedStartTime: description: The rounded start time. Will only be visible if rounding is enabled. type: string format: date-time roundedEndTime: description: The rounded end time. Will only be visible if rounding is enabled. type: string format: date-time roundedLength: description: The length of the time in hours based on the roundedStartTime and roundedEndTime. Will only be visible if startTime and endTime exist. type: integer notes: description: Any applicable notes type: string length: description: The length of the itme in hours, defaults to 0 type: number hourlyRate: description: The hourly rate for the time. Defaults to 0, will be null if the user does not have access. type: number cashTips: type: string format: decimal nullable: true description: 'Any cash tips reported for the shift. Note: the tips feature is required to see and use this field. ' example: '123.45' alertType: description: The id of the alert. This is a bitmap that represents different kinds of alerts. type: number isApproved: description: If the time is approved type: boolean modifiedBy: description: The user id of the user that edited the time type: number shiftBreaks: description: An array of shift breaks type: array items: $ref: '#/components/schemas/ShiftBreak' createdAt: description: The creation date of the time type: string updatedAt: description: The date when the time was most recently updated type: string example: id: 345 userId: 45 creatorId: 453 positionId: 678 locationId: 12 siteId: 735 shiftId: 156 startTime: 2018-01-01T00:00:00+00:00:00 endTime: 2018-01-01T08:00:00+00:00:00 notes: This is a note length: 8 hourlyRate: 15 alertType: 0 isApproved: false modifiedBy: 145 TimeHistory: type: object required: - id - timeId properties: id: description: The time history id type: number timeId: description: The time id this time history is associated with type: number userId: description: The user id of the user that worked this time type: number creatorId: description: The user id that created this time type: number positionId: description: The position id worked type: number locationId: description: The location id worked type: number siteId: description: The site id worked type: number shiftId: description: The associated shift id type: number startTime: description: The start of the time type: string endTime: description: The end of the time type: string notes: description: Any applicable notes type: string length: description: The length of the itme in hours, defaults to 0 type: number hourlyRate: description: The hourly rate for the time. Defaults to 0, will be null if the user does not have access. type: number alertType: description: The id of the alert. This is a bitmap that represents different kinds of alerts. type: number isApproved: description: If the time is approved type: boolean modifiedBy: description: The user id of the user that edited the time type: number example: id: 42 timeId: 345 userId: 45 creatorId: 453 positionId: 678 locationId: 12 siteId: 735 shiftId: 156 startTime: 2018-01-01T00:00:00+00:00:00 endTime: 2018-01-01T08:00:00+00:00:00 notes: This is a note length: 8 hourlyRate: 15 alertType: 0 isApproved: false modifiedBy: 145 schemas-Punch: type: object required: - timeId - userId - type - latitude - longitude - altitude - alerted - alertType - method properties: id: description: The punch id type: number applicationId: description: The id of the application used to authenticate this punch type: number timeId: description: The time id type: number userId: description: The user id of the user that worked this time type: number positionId: description: The position id worked type: number locationId: description: The location id worked type: number siteId: description: The site id worked type: number type: description: The type of punch (1=in, 2=out) type: number latitude: description: The punch latitude type: number longitude: description: The punch longitude type: number accuracy: description: A modifier to use when checking the radius type: number altitude: description: The altitude of the punch type: number ipAddress: description: The ip address of the punch type: string alerted: description: If the punch has alerts type: boolean alertType: description: The id of the alert. This is a bitmap that represents different kinds of alerts. type: number method: description: A number representing the application the punch originated from type: number notes: description: Any notes about the punch type: string createdAt: description: The creation date of the punch type: string updatedAt: description: The date when the punch was most recently updated type: string example: id: 462 applicationId: 158 timeId: 3548 userId: 1568 positionId: 53547 locationId: 158 siteId: 657 type: 2 latitude: 58.5751 longitude: -84.8732 accuracy: 10 altitude: 1542.5871 ipAddress: 192.168.0.1 alerted: false alertType: 0 method: 4 notes: Punch note ScheduledBreak: type: object required: - shiftId - type - length properties: shiftId: description: The id of the associated shift type: integer type: description: The type of break (1=paid, 2=unpaid) type: integer length: description: The break time rounded to the nearest minute type: integer ShiftBreakAudit: type: object required: - id - timeId - creatorId - taken properties: id: description: The shift break audit id type: integer timeId: description: The time id associated with the break audit type: integer creatorId: description: The id of the user who created the break audit type: integer taken: description: True if all breaks were taken type: boolean note: description: A note that should be populated if taken is false type: string example: id: 23 timeId: 12 creatorId: 43 taken: false note: I missed my lunch break Country: type: object required: - id - name - iso2 properties: id: description: The country id type: integer name: description: The country name type: string iso2: description: The country iso2 code type: string example: id: 233 name: United States iso2: US Plan: type: object required: - id - name - type - price - unitMax - maxEmployees - freemium properties: id: description: The plan id type: integer name: description: The plan name type: string type: description: The plan type type: integer price: description: The plan price type: double unitMax: description: The maximum number of units allowed type: integer maxEmployees: description: The maximum number of employees allowed type: integer freemium: description: If the plan is a freemium plan type: boolean example: id: 172 name: Plus type: 1 price: 99 unitMax: 0 maxEmployees: 100 freemium: false 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 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. schemas-Place: type: object properties: business_name: type: string example: When I Work description: (Optional) Business Name address: type: string example: 420 N 5th St, Minneapolis, MN 55401, USA description: Place Address place_id: type: string example: ChIJc9x2LYwys1IReiu9JB3DLGY description: Place id returned by google place_type: type: string example: premise description: Types returned by google latitude: type: number format: double example: 44.98364 description: Latitude of place location longitude: type: number format: double example: -93.277486 description: Longitude of place location schemas-Account: type: object properties: id: type: integer readOnly: true example: 10000 description: Unique identifier for the account. master_id: type: integer example: 0 readOnly: true description: "This ID indicates the status of a parent/child relationship\n * `0` - Indicates that this account\ \ does NOT have a parent/child relationship.\n * `An ID that does NOT match the account's ID` - Indicates that\ \ this account is a child and `master_id` is the parent.\n * `An ID that DOES match the account's ID` - Indicates\ \ that this account is the parent and has children.\n" type: readOnly: true type: integer enum: - 1 - 2 - 3 description: "The account's type, must be one of:\n * `1` - Scheduling\n * `2` - Attendance\n * `3` - Both\n" logo: type: string example: https://s3.amazonaws.com/path/to/logo.jpg description: Path to the image file for the company's logo. company: readOnly: true type: string example: When I Work description: Name of the company for which this account is in use. subdomain: type: string example: wheniwork deprecated: true description: Subdomain of wheniwork.com to access company-specific When I Work web application. No longer used. enabled: type: boolean example: true readOnly: true description: Whether the account is enabled (i.e. not on an expired plan or failed credit card payment) bad_credit_card: type: boolean example: false readOnly: true description: Whether this account has an invalid credit card in use plan_expires: type: string format: date-time example: '2021-01-06T10:55:58-06:00' readOnly: true description: Date and time when this account's plan expires features: readOnly: true type: array items: type: string example: - attendance - openshifts - annotations description: List of all the enabled features on the account timezone_id: readOnly: true type: integer example: 11 description: Identifier for the account's timezone timezone_name: readOnly: true type: string example: America/Chicago description: Name for the timezone specified in the timezone_id settings: type: string format: json description: A list of settings for this account place: $ref: '#/components/schemas/schemas-Place' 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' 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 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 EmployeeExtra: type: object properties: invite: type: boolean description: 'Whether to send invitations to new employees. ' Reinvite: type: object properties: registered: description: Whether the given email or phone number is associated with a registered user type: boolean pendingInvite: description: Whether the associated user (if any) has a pending invite type: boolean Timezones: type: object properties: timezone_id: example: 12 type: integer timezone_name: example: Eastern Time (US/Detroit) type: string offset: example: -4 type: integer olson_id: example: America/Detroit type: string requestBodies: ShiftRequest: description: Shift data content: application/json: schema: oneOf: - allOf: - $ref: '#/components/schemas/Shift' - type: object properties: chain: $ref: '#/components/schemas/Chain' - type: array items: allOf: - $ref: '#/components/schemas/Shift' - type: object properties: chain: $ref: '#/components/schemas/Chain' TimeRequest: content: application/json: schema: type: object properties: user_id: type: integer example: 101 description: The user assigned to the times. position_id: type: integer example: 19483 description: Position the time belongs to. 0 if unassigned. location_id: type: integer example: 1045 description: Location the time belongs to. 0 if unassigned. site_id: type: integer example: 4351 description: Site the time belongs to. 0 if unassigned. shift_id: type: integer example: 5451 description: A shift tied to this time. 0 if unassigned. start_time: type: string format: date-time example: Fri, 07 Mar 2016 08:30:00 -0600 description: The start time. For accounts with Check payroll onboarded, time must not be past the end of the current pay period end_time: type: string format: date-time example: Fri, 07 Mar 2016 14:30:00 -0600 description: The end time rounded_start_time: type: string format: date-time example: Fri, 07 Mar 2016 08:30:00 -0600 description: The rounded start time. If rounding is not enabled this field will not be present. rounded_end_time: type: string format: date-time example: Fri, 07 Mar 2016 14:30:00 -0600 description: The rounded end time. If rounding is not enabled this field will not be present. notes: type: string example: A time note description: Notes for a time is_approved: type: boolean example: false description: If the time is approved cash_tips: description: The amount of cash tips reported for the time entry. type: string format: decimal example: '54.32' description: Time data ClockInRequest: description: Clock In (Punch) request data content: application/json: schema: type: object properties: id: type: integer description: The ID of the user you are creating the clock-in for example: 14 site_id: type: integer description: The ID of the job site to punch in at. This is an optional parameter. example: 1 required: false position_id: type: integer description: The ID of the position the user is clocking in as. This is an optional parameter. example: 102 required: false shift_id: type: integer description: The Shift ID for the shift to punch in for, 0 if punching into an unscheduled shift. example: 0 required: false location_id: type: integer description: The Schedule ID for the schedule the user is punching in at. This is an optional parameter. example: 1 required: false notes: type: string description: Optional notes that can be added to the punch that will show up on the timesheets. example: Punching in today, running a little late due to traffic problems required: false coordinates: type: array description: The GPS coordinates of the clock-in. This is an optional parameter. example: - 44.937422 - -93.084009 required: false altitude: type: number description: The altitude that the user is currently at in meters. example: 20 required: false accuracy: type: number description: The accuracy in meters of the coordinates being sent. example: 20 required: false terminal: type: boolean description: Is the user clocking in from a terminal (web or mobile/tablet terminal app) example: true required: false default: false ClockOutRequest: description: Clock Out (Punch) request data content: application/json: schema: type: object properties: id: type: integer description: The ID of the user you are creating the clock-in for example: 14 notes: type: string description: Optional notes that can be added to the punch that will show up on the timesheets example: Punching out late there was a delay in the shift change required: false coordinates: type: array description: The GPS coordinates of the clock-out. This is an optional parameter. example: - 44.983791 - -93.2774416 required: false altitude: type: number description: The altitude that the user is currently at in meters. example: 20 required: false accuracy: type: number description: The accuracy in meters of the coordinates being sent. example: 20 required: false terminal: type: boolean description: Is the user clocking out from a terminal (web or mobile/tablet terminal app) example: true required: false default: false cashTips: description: The amount of cash tips reported for the shift. type: string format: decimal example: '54.32' ShiftUnassignRequest: content: application/json: schema: type: object properties: shift_ids: description: Array of shift IDs type: array items: type: string example: '555555' ShiftAssignRequest: content: application/json: schema: type: object properties: user_ids: description: Array of user IDs type: array items: type: string example: '555555' ShiftPublish: content: application/json: schema: type: object properties: ids: type: array items: type: integer example: - 878787 - 656565 description: List of shift IDs ShiftNotifyRequest: content: application/json: schema: type: object required: - start - end properties: all: type: boolean value: true description: Should notifications be sent for all matching shifts, or only new and/or changed shifts since last notification. start: type: string format: date-time example: '2020-10-03T22:00:00.000Z' description: The start of the date range of shifts for which to send notifications end: type: string format: date-time example: '2020-10-10T21:59:56.999Z' description: The end of the date range of shifts for which to send notifications location_id: type: integer example: 9 description: The location (schedule) with shifts to send notifications. If not set, all locations will be included. message: type: string example: hello world description: A custom message to send with the shift notifications position_ids: type: array items: type: integer example: 12342 description: Limit schedule notifications to only shifts tagged to the given position IDs. Defaults to all positions. example: [] site_ids: type: array items: type: integer example: 512352 description: Limit schedule notifications to only shifts tagged to the given site IDs. Defaults to all sites. example: [] user_ids: type: array items: type: integer example: 231523 description: Limit schedule notifications to only shifts tagged to the given user IDs. Defaults to all users. example: [] SingleShiftNotifyRequest: content: application/json: schema: type: object properties: message: type: string example: hello world description: A custom message to send with the shift notifications. BulkEditShiftRequest: content: application/json: schema: description: Array of shift objects to update type: array items: $ref: '#/components/schemas/ShiftBulk' PositionRequest: content: application/json: schema: $ref: '#/components/schemas/Position' description: The position data ScheduleRequest: content: application/json: schema: $ref: '#/components/schemas/Schedule' description: The schedule (location) data SiteRequest: content: application/json: schema: $ref: '#/components/schemas/Site' description: The site data ShiftTemplateRequest: content: application/json: schema: $ref: '#/components/schemas/ShiftTemplate' description: The shift template (block) data ScheduleTemplateRequestCreate: content: application/json: schema: type: object properties: description: type: string example: This is a description of a schedule template start: type: string format: date-time example: '2019-05-12T00:00:00+05:45' end: type: string format: date-time example: '2019-05-18T23:59:59+05:45' include_repeating_shifts: type: boolean example: false location_id: type: integer example: 7 name: type: string example: Schedule Template Example position_id: type: array items: type: integer example: - 0 - 23 - 22 - 24 - 19 - 20 - 21 site_id: type: array items: type: integer example: - 0 description: The schedule template data ScheduleTemplateRequestUpdate: content: application/json: schema: type: object properties: description: type: string exapmle: This is a description of a schedule template name: type: string example: Schedule Template Example description: The schedule template data to update AnnotationRequest: content: application/json: schema: $ref: '#/components/schemas/Annotation' description: The annotation data AvailabilityEventRequest: content: application/json: schema: $ref: '#/components/schemas/AvailabilityEvent' PayrollRequest: content: application/json: schema: $ref: '#/components/schemas/Payroll' description: The payroll data 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 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 AvatarRequest: content: image/*: schema: type: string format: binary 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 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 AccountRequest: description: The account data content: application/json: schema: allOf: - $ref: '#/components/schemas/schemas-Account' - type: object properties: referral_reason: type: string example: goog description: (Optional) referral reason, which will persist as the referral_code. AccountSettingsRequest: content: application/json: schema: type: object properties: company: type: string example: When I Work description: Company name timezone_id: type: integer example: 11 description: Identifier for the account's timezone industry_id: type: integer example: 2 description: ID of the industry relevant to this account. ref_employees: type: integer example: 20 description: Number of employees for this account 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