{ "openapi": "3.1.0", "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.\n\nWhen 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.\nFind 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.\n\nFor 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/).\n" }, "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.\n\nFor more information about how to use Shifts, visit the [Help Center](https://help.wheniwork.com/article-categories/scheduling-your-team/).\n" }, { "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.\n\nFor more information about Accounts, visit the [Help Center](https://help.wheniwork.com/article-categories/account-settings/).\n" }, { "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.\nFor 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.\n\nFor more information about Users, visit the [Help Center](https://help.wheniwork.com/articles/user-access-privileges-computer/).\n" }, { "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.\n\nFor more information about using Positions, visit the [Help Center](https://help.wheniwork.com/articles/creating-and-managing-positions-computer/).\n" }, { "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.\n\nIf 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.\n" }, { "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.\n\nFor more information about using Scheduled, visit the [Help Center](https://help.wheniwork.com/articles/creating-and-managing-schedules-computer/).\n" }, { "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.\n\nFor more information about using Shift Templates, visit the [Help Center](https://help.wheniwork.com/articles/creating-and-managing-shift-templates-computer/).\n" }, { "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.\n\nFor more information about using Time Off Requests, visit the [Help Center](https://help.wheniwork.com/articles/requesting-time-off-computer/).\n" }, { "name": "Request Type", "description": "Types of time off that can be selected when submitting a time off request.\n\nFor more information about using Time Off Requests, visit the [Help Center](https://help.wheniwork.com/articles/requesting-time-off-computer/).\n" }, { "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).\n\nFor more information about using Shift Requests, visit the [Help Center](https://help.wheniwork.com/articles/swapping-and-dropping-shifts-computer/).\n" }, { "name": "Availabilities", "description": "Set your availability preferences to let your employer know when you prefer to work and when you prefer not to work.\n\nFor more information about using Availabilities, visit the [Help Center](https://help.wheniwork.com/articles/setting-your-availability-computer/).\n" }, { "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.\n\nFor more information about using Schedule Templates, visit the [Help Center](https://help.wheniwork.com/articles/using-schedule-templates-computer/).\n" }, { "name": "Annotations", "description": "Annotations convey important information to all staff for the given schedules (locations) and date range.\n\nAny or none of the following tags may apply to an Annotation:\n\n* Time Off Not Allowed\n* Business Closed\n* Announcement\n\nThe \"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).\n\nFor more on using Annotations, visit the [Help Center](https://help.wheniwork.com/hc/en-us/articles/204348065-Annotations).\n" }, { "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.\n\nFor more info about using OpenShift Requests, visit the [Help Center](https://help.wheniwork.com/articles/shift-bidding/).\n" }, { "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.\n\nFor more info about user Times, visit the [Help Center](https://help.wheniwork.com/articles/reviewing-employees-time-sheets-computer/).\n" }, { "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.\n\n> Please note that payrolls cannot be created or deleted via the API\n\nFor more info about managing Payroll, visit the [Help Center](https://help.wheniwork.com/articles/close-and-export-payroll/).\n" }, { "name": "Subscriptions", "description": "Subscriptions are additional plans that can be attached to an account. Subscriptions may include free or paid plans.\n" }, { "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.\n\nUse 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.\n\nFor more info about using Forecast Tools, visit the [Help Center](https://help.wheniwork.com/articles/forecast-tools/).\n" }, { "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.\nCommon practice is to combine allopen with one of the other inclusion options.\n", "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.\n\nIf this option is included in addition to the `location_id` option, all shifts linked to other\nlocations, through users in other locations, will also be included.\n", "schema": { "type": "boolean" } }, { "name": "location_id", "in": "query", "description": "One or more location IDs by which to limit results\n\n_Also see `all_locations` above_\n", "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\nfetched shift, if it is on a shift chain, we will insert all the shifts on that chain from the\nfirst up to the date specified in the parameter.\n", "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.\n\n**NOTE:** The response is slightly different if you create many shifts instead of one.\n", "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\nwill only be populated with shifts if a shift chain is created with the shift and it we will\ninsert the created shifts from the beginning of the chain up to the date specified in the\nparameter.\n\n**NOTE:** This does not apply when creating shifts in bulk.\n", "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\nis provided and a set of shifts match the criteria.\n", "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.\nIf filters are used, the `start`, `end`, and `location_id` properties are required.\n", "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\nfetched shift has a shift chain, we will insert all the shifts on that chain from the first up\nto the date specified in the parameter.\n", "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\ninsert the created or edited shifts from the beginning of the chain up to the date specified in\nthe parameter.\n\n**NOTE:** This does not apply when updating shifts in bulk.\n", "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.\n\nThis can also be used by employees when the Shift Release setting is enabled.\n", "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\n\nThis can also be used to approve multiple users for an OpenShift that requires approval.\n", "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.\n", "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\n", "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.\n", "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\nspecified in the path or query string.\n", "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.\n", "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.\n", "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.\n", "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.\n" }, "404": { "description": "Not Found. The site to be deleted was not found.\n" } } } }, "/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.\n", "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.\n", "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.\n", "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.\n", "in": "query", "schema": { "type": "integer" } }, { "name": "sortby", "description": "Field to sort by. Can either be 'created' and sort by the created_at\ndate in descending order, or anything else and sort by status in\nascending order, then by the updated_at date in descending order.\n", "in": "query", "schema": { "type": "string" } }, { "name": "start", "description": "yyyy-mm-dd formatted start date for the request time-frame.\n", "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\ncomma separated.\n", "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.\n" }, "403": { "description": "Forbidden. The current user does not have permission to view the\nuser's requests.\n" } }, "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.\n", "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\nrequest.\n", "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.\n\n(Optional) Type code for the request.\n\n* `0` = Unpaid\n* `1` = Paid (PTO)\n* `2` = Sick\n* `3` = Holiday\n", "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.\n", "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.\n", "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.\n", "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.\n", "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\nrequest type.\n", "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.\n", "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\nother or drop shifts for other users to pick up.\n", "parameters": [ { "name": "end", "description": "End time for the shift search window. Must be included if start is defined.\n", "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.\n", "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.\n", "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\nresults. For multiple statuses, enter a list separated by commas.\n\nStatuses available are:\n* `0` - Pending\n* `1` - Approved\n* `2` - Declined\n* `3` - Completed\n* `4` - Canceled\n* `5` - Expired\n", "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.\nFor multiple types, enter a list separated by commas.\n\nTypes available are:\n* `1` - Swap\n* `2` - Drop\n* `3` - Alert\n", "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.\n", "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 \nmanager 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\ndrop shifts for other users to pick up.\n", "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.\n", "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.\n", "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)\n", "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\n* `101` - Bad device location received\n* `102` - Bad shift location received\n* `103` - Out of range for shift location\n* `104` - Not near the punch location\n* `105` - Clock-in time too early\n* `106` - No shift scheduled, or manual selection required (see: availableShifts)\n", "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\n-H \"W-Token: ilovemyboss\"\n" } ], "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}\n-H \"W-Token: ilovemyboss\"\n" } ], "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.\n\n**🔥WARNING🔥**\nOnly for a closed payroll (see is_closed) please use `hourstats` for a payroll that is currently open.\n", "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\n-H \"W-Token: ilovemyboss\"\n" } ], "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\nabsences, early/late clock ins/outs, no shows, etc.\n", "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\nall notices regardless of when they've been dismissed.\n", "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\nthe last time the user dismissed notices. This parameter can help restrict the window further.\n", "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.", "schema": { "type": "boolean", "example": false } }, { "name": "only_deleted", "in": "query", "description": "Only include deleted/archived users in results. Defaults to false.", "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 \\\n-H \"W-Token: ilovemyboss\"\n" } ], "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.\n> 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.\n", "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.\n\nNote that unlike most API endpoints, this endpoint does not use JSON for the request body.\n", "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.\n" } }, "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.\n", "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.\n", "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.\n", "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\ngenerated for any of these rows.\n", "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.\n", "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.\n", "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\nnewly-created users when importing employees. The type of this field varies per resource; expand\nthe details of this field to learn more.\n", "oneOf": [ { "$ref": "#/components/schemas/EmployeeExtra" } ] } }, "required": [ "columns" ], "example": { "columns": { "start_time": "Start", "end_time": "End", "position": null } } } } } }, "responses": { "200": { "description": "Import Finalized" } } } }, "/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\nRRULE:FREQ=WEEKLY;UNTIL=20240629T045959Z;WKST=SU;BYDAY=MO,TU,WE,TH,FR\n" }, "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\nsignificant bit represents Sunday and the least significant bit represents Monday (0b1000001).\n\nExamples:\n| Days | Binary | Decimal |\n|---------------------------|-------------|---------|\n| Monday through Friday | `0b0011111` | 31 |\n| Monday, Wednesday, Friday | `0b0010101` | 21 |\n| Saturday and Sunday | `0b1100000` | 96 |\n", "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\ntimezone (see `timezone_id` below) the time will be midnight in a local time.\n\nExample: You're creating a shift chain in the `America/Chicago` timezone that you want to end on 7/29/24\nlocally. You would send `2024-07-29T05:00:00Z`, which when converted to the provided timezone would be\n`2024-07-29T00:00:00-05:00`.\n\n**NOTE**: This is required when _creating_ a repeating shift. It may be omitted when editing one.\n", "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.\n\n**NOTE**: This is required when _creating_ a repeating shift. It may be omitted when editing one.\n", "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\nsignificant bit represents Sunday and the least significant bit represents Monday (0b1000001).\n\nExamples:\n| Days | Binary | Decimal |\n|---------------------------|-------------|---------|\n| Monday through Friday | `0b0011111` | 31 |\n| Monday, Wednesday, Friday | `0b0010101` | 21 |\n| Saturday and Sunday | `0b1100000` | 96 |\n", "type": "int", "example": 31 }, "timezone_id": { "description": "The timezone this chain is built in.\n\nThis must be either the `timezone_id` or `olson_id` from one of the timezones available through\n[this endpoint](#tag/Timezones).\n", "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.\n\nNote: the tips feature is required to see and use this field.\n", "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\nthe user's email address, or it can be used to help map users in When\nI Work to other services.\n", "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\nbased on the position they are working at the time. There is no currency\nattached, so customers are expected to input correct values for their\ncurrency or do their own conversion from USD.\n", "format": "float", "type": "number" }, "hours_max": { "description": "The max hours that this user prefers to work. A manager may still\nschedule the user beyond this value.\n", "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\nand supervisors.)\n", "type": "boolean" }, "is_private": { "description": "Whether the user has privacy enabled, which will hide their contact\ndetails from other employees. Supervisors+ can not hide their\nemail/phone from other employees.\n", "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:\n1 = hourly employee\n2 = salaried employee\n4 = Exempt from overtime\n", "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\n* Punch in/out\n* Punch break start/stop\n", "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.\n\nNote: the tips feature is needed to use this field.\n" }, "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).\n\nOnly certain plans can create non-built-in types.\n", "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.\n* `true`\n* `false`\n", "type": "boolean", "example": false }, "user_status": { "description": "The current user 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": "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,\nreplaced by either request_id or swap_id.\n", "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\nare required.\n", "type": "integer" }, "swap_id": { "description": "The ID of the swap the message is for. Either request_id OR swap_id are\nrequired.\n", "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\nto pick up.\n", "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\nrole of the current user and their relationship to the request.\n", "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.\n* `0` - Pending\n* `1` - Approved\n* `2` - Declined\n* `3` - Completed\n* `4` - Canceled\n* `5` - Expired\n", "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.\n* `1` - Swap\n* `2` - Drop\n* `3` - Alert\n", "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.\n* `0` - Pending Approval\n* `1` - Pending Acceptance\n* `2` - Declined\n* `3` - Accepted\n* `4` - Canceled\n* `5` - Expired\n* `6` - Denied\n", "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)\nwithin that pay period.\n", "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.\n**Note**\nAn open pay period will build out live data from `hourstats`.\nA closed pay period will have a snapshot of the data from the time of closing called `payrollhours`\n" }, "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\nnotice.\n" }, "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.\n* `103` - Wrong Location\n* `107` - Forgot to Clock Out\n* `110` - Not Scheduled\n* `121` - Absent\n* `120` - No Show\n* `131` - Clocked In Early\n* `132` - Clocked In Late\n* `133` - Clocked Out Early\n* `134` - Clocked Out Late\n* `135` - Missed Clock In\n" }, "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\nexample, this could be the `created_at` time of the punch, `start_time` of the time, `start_time` or\n`end_time` of the shift, or the `created_at` time of the absence.\n" } } }, "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.\n" }, "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\n* `available` - Free trial is available for the account\n* `active` - Free trial is currently active for the account\n* `unavailable` - Account is not currently eligible for a free trial\n", "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\n* `small-business` - Small business free trial\n* `enterprise` - Enterprise free trial\n* `undefined` - Error determining eligibility\n", "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\n* `currently-active` - A free trial is currently active\n* `renewal-backoff` - The account needs to wait before a free trial becomes available again\n* `account-type-child` - The account is a child account and not eligible\n* `account-plan-not-eligible` - The accounts current plan is ineligible for a free trial\n* `no-new-features` - The account would receive no new features from the trial subscription\n* `account-too-new` - The account was created too recently to be eligible for a free trial\n* `account-inactive` - The accounts is inactive and not eligible\n* `account-deleted` - The accounts is deleted and not eligible\n", "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\naccount's weekly overtime threshold that are not classified as double\novertime hours for a given day.\n", "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\ngiven date as the key.\n", "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\nand additional account settings.\n", "properties": { "convertedEndDate": { "description": "End date the resource is returning, pushed out to the end of a week if\nthe requested date is not at the end. Defaults to the end of the current\nweek.\n", "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\nweek if the requested date is not at the beginning. Defaults to the\nbeginning of the current week.\n", "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\nscheduler, but not published.\n", "enum": [ false, true ], "type": "string" }, "hasAttendance": { "description": "Whether the currently logged in account has the attendance feature.\n", "enum": [ false, true ], "type": "string" }, "includeRaw": { "description": "Whether the resource is including raw statistics, meaning that it will\nreturn scheduled and actual blocks for days in addition to the actual\nand scheduled blocks.\n", "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.\n", "example": "2019-03-29", "type": "string" }, "originalStartDate": { "description": "Start date sent by the client, which may be empty or improperly\nformatted.\n", "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\nformatted.\n", "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.\n\nNote: the tips feature is required to see and use this field.\n", "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.\n" }, "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.\n\nA full list of accepted column names for each type can be found in the Import section documentation.\n", "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.\n\nA null value means no match was suggested, and you should prompt the user to provide the mapping if necessary.\n" }, "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.\n" } } }, "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 } } } } } } } } }