Toast Labor API

swagger: '2.0'
info:
  version: 1.9.0
  title: Toast Labor API
  description: |
    Toast labor API is a set of REST web services that you can use to 
    manage the employees, jobs, and shifts for your restaurant. The 
    labor API is intended for software engineers, managers, and 
    technical staff who are responsible for integrating third-party 
    systems with the Toast platform.
  contact:
    name: Toast developer support
host: toast-api-server
basePath: /labor/v1
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Employees
- name: Jobs
- name: Shifts
- name: Time entries
paths:
  /employees:
    get:
      tags:
      - Employees
      summary: Toast Get Employees
      description: |
        Returns an array of `Employee` objects containing information 
        about restaurant employees.
      operationId: employeesGet
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The Toast platform GUID of the restaurant that is the 
          context for this operation.
        in: header
        type: string
        format: string
        required: true
      - name: employeeIds
        description: |
          An optional identifier that filters return values for a 
          specific employee. The identifier can be a Toast platform 
          GUID or an external identifier. If present, the `employees` 
          resource will only return the employees you specify. You 
          can include multiple `employeeIds` query parameters 
          (maximum 100). If not present, the resource returns each 
          employee for the restaurant.
        in: query
        type: string
        format: string
      responses:
        '200':
          description: |
            JSON objects for all employees in the restaurant
          schema:
            title: Response
            type: array
            items:
              $ref: '#/definitions/Employee'
        '500':
          description: |
            An unexpected internal error occurred. There is a 
            `requestId` attached to this error that can be referenced 
            by Toast support.
      security:
      - oauth2:
        - labor.employees:read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Employees
      summary: Toast Add an Employee
      description: |
        Creates a restaurant employee record.
      operationId: employeesPost
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The Toast platform GUID of the restaurant that is the 
          context for this operation.
        in: header
        type: string
        format: string
        required: true
      - name: Content-Type
        description: |
          The Internet Assigned Numbers Authority (IANA) media type 
          of the message body data. The value must be 
          `application/json`.
        in: header
        type: string
        format: string
        required: true
      - name: body
        description: |
          An `Employee` object containing information about the 
          employee, including the employee's name and email address.
        in: body
        required: true
        schema:
          type: string
          example:
            entityType: RestaurantUser
            email: email
            firstName: first name
            chosenName: optional chosen name
            lastName: last name
            externalId: optional external ID
            externalEmployeeId: optional external employee ID
            jobReferences":
            - guid: f290a951-2042-4f3d-b861-d89e9e583876
              entityType: RestaurantJob
            wageOverrides:
            - jobReference:
                guid: f290a951-2042-4f3d-b861-d89e9e583876
                entityType: RestaurantJob
              wage: 10
      responses:
        '200':
          description: Returns the created employee.
          schema:
            $ref: '#/definitions/Employee'
        '400':
          description: |
            The request contains data that is not supported by the 
            current version of the API as described.
        '415':
          description: |
            The request did not have "application/json" in the 
            Content-Type header.
        '500':
          description: |
            An unexpected internal error occurred. There is a requestId 
            attached to this error that can be referenced by Toast 
            support.
      security:
      - oauth2:
        - labor.employees:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /employees/{employeeId}:
    get:
      tags:
      - Employees
      summary: Toast Get Information About One Employee
      description: |
        Returns an `Employee` object containing information about one 
        restaurant employee.
      operationId: employeesEmployeeIdGet
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The Toast platform GUID of the restaurant that is the 
          context for this operation.
        in: header
        type: string
        format: string
        required: true
      - name: employeeId
        description: |
          The Toast platform GUID or external identifier for the
          employee to be returned.
        in: path
        type: string
        required: true
      responses:
        '200':
          description: |
            Returns the employee information.
          schema:
            $ref: '#/definitions/Employee'
        '400':
          description: |
            The GUID or external identifier was malformed.
        '401':
          description: |
            Unauthorized - Missing or invalid authentication.

            **Cause:** No valid OAuth token provided in Authorization header.
        '403':
          description: |
            Forbidden - Insufficient permissions.
        '404':
          description: |
            The GUID or external identifier does not match any 
            employees at the current restaurant.
        '500':
          description: |
            An unexpected internal error occurred. There is a 
            `requestId` attached to this error that can be referenced 
            by Toast support.
      security:
      - oauth2:
        - labor.employees:read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      tags:
      - Employees
      summary: Toast Delete an Employee
      description: |
        Deletes a restaurant employee record by marking the record as 
        deleted. A deleted employee cannot log in at the restaurant or 
        open new time entries.

        If you `GET` an employee record that has been deleted, its 
        `deleted` value is `true` and its `deletedDate` value contains 
        the date and time the record was deleted. 

        If you delete an employee that has already been deleted then 
        the result is successful (200) and no change is made.

        The deleted record appears in the list of deleted employees for 
        the restaurant in Toast Web. From the 
        list of deleted employees, you can enable a deleted record so 
        that the employee can use it again. Information about deleted 
        employees remains available in reports.

        You cannot delete employees who have open time entries (time 
        entries that do not have an out date value).
      operationId: employeesEmployeeIdDelete
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The Toast platform GUID of the restaurant that is the 
          context for this operation.
        in: header
        type: string
        format: string
        required: true
      - name: employeeId
        description: |
          The Toast platform GUID or external identifier for the 
          employee to be deleted.
        in: path
        type: string
        required: true
      responses:
        '200':
          description: |
            The employee has been deleted. Returns an `Employee` object 
            containing information about the deleted restaurant 
            employee.
          schema:
            $ref: '#/definitions/Employee'
        '400':
          description: |
            The GUID or external identifier was malformed.
        '404':
          description: |
            The GUID or external identifier does not match any
            employees at the current restaurant.
        '500':
          description: |
            An unexpected internal error occurred. There is a 
            `requestId` attached to this error that can be referenced 
            by Toast support.
      security:
      - oauth2:
        - labor.employees:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      tags:
      - Employees
      summary: Toast Update Employee Information
      description: |
        Updates the first name, chosen name, last name, external employee ID, and/or 
        passcode of a restaurant employee. The `PATCH` operation cannot 
        update any other employee information.
      operationId: employeesEmployeeIdPatch
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The Toast platform GUID of the restaurant that is the 
          context for this operation.
        in: header
        type: string
        format: string
        required: true
      - name: Content-Type
        description: |
          The Internet Assigned Numbers Authority (IANA) media type 
          of the message body data. The value must be 
          `application/json`.
        in: header
        type: string
        format: string
        required: true
      - name: employeeId
        description: |
          The Toast platform GUID or external identifier for the 
          employee to be returned.
        in: path
        type: string
        required: true
      - name: body
        description: |
          A JSON object containing the employee information that you 
          are updating. You can update an employee's:

          * `firstName` - First name.

          * `chosenName` - Chosen name.

          * `lastName` - Last name.

          * `externalEmployeeId` - External employee identifier.

          * `passcode` - The passcode for access to Toast POS devices.

          All values are optional. You must include at least one 
          value. Each value that you include must contain information 
          (not null). If you include the `passcode` value to update 
          an employee's passcode you must include the employee's 
          current passcode in the `currentPasscode` value.
        in: body
        required: true
        schema:
          type: string
          example:
            firstName: Mynewfirstname
            chosenName: Mynewchosenname
            lastName: Mynewlastname
            externalEmployeeId: '1234567890'
            passcode: '1234'
            currentPasscode: '1111'
      responses:
        '200':
          description: |
            Returns the updated Toast platform employee record.
          schema:
            $ref: '#/definitions/Employee'
        '400':
          description: |
            The Toast platform GUID or external identifier was 
            malformed, or the body of the request was malformed.
        '404':
          description: |
            The Toast platform GUID or external identifier does not 
            match any employees at the current restaurant.
        '500':
          description: |
            An unexpected internal error occurred. There is a 
            `requestId` attached to this error that can be referenced 
            by Toast support.
      security:
      - oauth2:
        - labor.employees:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /employees/{employeeId}/externalId:
    parameters:
    - name: employeeId
      description: |
        The Toast platform GUID of the employee record.
      in: path
      type: string
      required: true
    post:
      tags:
      - Employees
      summary: Toast Add an External Identifier
      description: |
        Adds an external identifier for an existing employee. Include 
        the string value of the new external identifier in the message 
        body.

        You cannot change an existing external identifier with another 
        `POST` request; use `PUT` instead. The Toast platform uses this 
        external identifier as one of the unique, persistent 
        identifiers for an employee record.
      operationId: employeesEmployeeIdExternalIdPost
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The Toast platform GUID of the restaurant that is the 
          context for this operation.
        in: header
        type: string
        format: string
        required: true
      - name: Content-Type
        description: |
          The Internet Assigned Numbers Authority (IANA) media type 
          of the message body data. The value must be 
          `application/json`.
        in: header
        type: string
        format: string
        required: true
      - name: body
        description: |
          The JSON string value of the `externalId` for the employee 
          record. Wrap the value in double quotation marks to make it 
          valid JSON syntax.
        in: body
        required: true
        schema:
          type: string
          example: MyToastNamingAuthority:9876543210
      responses:
        '200':
          description: |
            Returns the updated employee record.
          schema:
            $ref: '#/definitions/Employee'
      security:
      - oauth2:
        - labor.employees:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Employees
      summary: Toast Add or Replace an External Identifier
      description: |
        Adds or replaces the external identifier for an
        existing employee. Include the string value of the new external
        identifier in the message body.

        The Toast platform uses this external identifier as one of the 
        unique, persistent identifiers for an employee record. 
        _Changing the external identifier for an existing employee 
        might affect reporting and other Toast platform functions that 
        select employees using the `externalId` value._
      operationId: employeesEmployeeIdExternalIdPut
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The Toast platform GUID of the restaurant that is the 
          context for this operation.
        in: header
        type: string
        format: string
        required: true
      - name: Content-Type
        description: |
          The Internet Assigned Numbers Authority (IANA) media type 
          of the message body data. The value must be 
          `application/json`.
        in: header
        type: string
        format: string
        required: true
      - name: body
        description: |
          The JSON string value of the `externalId` for the employee 
          record. Wrap the value in double quotation marks to make it 
          valid JSON syntax.
        in: body
        required: true
        schema:
          type: string
          example: MyToastNamingAuthority:9876543210
      responses:
        '200':
          description: |
            Returns the updated employee record.
          schema:
            $ref: '#/definitions/Employee'
      security:
      - oauth2:
        - labor.employees:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /employees/{employeeId}/unarchive:
    parameters:
    - name: employeeId
      description: |
        The Toast platform GUID of the employee record.
      in: path
      type: string
      required: true
    put:
      tags:
      - Employees
      summary: Toast Unarchive an Employee
      description: |
        Unarchives an employee record that was previously archived.

        * Unarchived employees can sign into the Toast POS.
        * Unarchived employees can sign in to Toast Web. 
        * When you unarchive an employee, the employee has all 
          jobs that were previously assigned to them.
        * If an employee had a swipe card for signing into the 
          Toast POS, the swipe card _is not_ re-associated with 
          the employee when you unarchive them.

        If you unarchive an employee who will take a different 
        role than the one they had when they were archived, you 
        must update the employee's jobs list and verify that the 
        employee should continue to sign into Toast Web.
      operationId: employeesEmployeeIdUnarchivePut
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The Toast platform GUID of the restaurant that is the 
          context for this operation.
        in: header
        type: string
        format: string
        required: true
      - name: Content-Type
        description: |
          The Internet Assigned Numbers Authority (IANA) media type 
          of the message body data. The value must be 
          `application/json`.
        in: header
        type: string
        format: string
        required: true
      responses:
        '200':
          description: |
            Returns the updated employee record.
          schema:
            $ref: '#/definitions/Employee'
        '400':
          description: |
            Employee being unarchived is not currently archived.
      security:
      - oauth2:
        - labor.employees:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /employees/{employeeId}/jobs:
    parameters:
    - name: employeeId
      description: |
        The Toast platform GUID of the employee record.
      in: path
      type: string
      required: true
    put:
      tags:
      - Employees
      summary: Toast Replace a Jobs List
      description: |
        Replaces the list of jobs for an employee. Include a JSON  
        array of job identifiers in the message body.

        If a job is defined at the restaurant group or subgroup level, 
        this operation adds or removes that job for the the employee at 
        _all restaurant locations_ in the group or subgroup.
      operationId: employeesEmployeeIdJobsPut
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The Toast platform GUID of the restaurant that is the 
          context for this operation.
        in: header
        type: string
        format: string
        required: true
      - name: Content-Type
        description: |
          The Internet Assigned Numbers Authority (IANA) media type 
          of the message body data. The value must be 
          `application/json`.
        in: header
        type: string
        format: string
        required: true
      - name: body
        description: |
          An array of JSON objects containing identifiers for jobs. 
          The identifiers can be either Toast platform GUIDs or 
          external identifiers.
        in: body
        required: true
        schema:
          type: string
          example:
          - guid: dd8cea7a-add5-4508-b8fe-ffd0b584e4da
          - externalId: MyToastNamingAuthority:9876543210
      responses:
        '200':
          description: |
            Returns the updated employee record.
          schema:
            $ref: '#/definitions/Employee'
      security:
      - oauth2:
        - labor.employees:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /employees/{employeeId}/wageOverrides:
    parameters:
    - name: employeeId
      description: |
        The Toast platform GUID of the employee record.
      in: path
      type: string
      required: true
    put:
      tags:
      - Employees
      summary: Toast Replace Wage Overrides
      description: |
        Replaces the list of wage overrides for the jobs that are 
        assigned to an employee. Include a JSON  array of 
        `JobWageOverride` objects in the message body. Include the new 
        wage for the employee in the `wage` value. Specify the wage in 
        U.S. dollars.

        You must include all existing wage overrides in the message 
        body. Any wage overrides that are not present in the array are 
        removed from the employee record.
      operationId: employeesEmployeeIdWageOverridesPut
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The Toast platform GUID of the restaurant that is the 
          context for this operation.
        in: header
        type: string
        format: string
        required: true
      - name: Content-Type
        description: |
          The Internet Assigned Numbers Authority (IANA) media type 
          of the message body data. The value must be 
          `application/json`.
        in: header
        type: string
        format: string
        required: true
      - name: body
        description: |
          An array of JSON `JobWageOverride` objects.
        in: body
        required: true
        schema:
          type: string
          example:
          - jobReference:
              guid: 8d3bba92-10e4-4345-9ae6-ed94c09dc332
            wage: 15.75
      responses:
        '200':
          description: |
            The wage overrides for the employee are replaced. Returns 
            the updated employee record.
          schema:
            $ref: '#/definitions/Employee'
      security:
      - oauth2:
        - labor.employees:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /shifts:
    get:
      tags:
      - Shifts
      summary: Toast Get Shifts
      description: |
        Returns an array of `Shift` objects that contain information 
        about schedule shifts for restaurant employees.
      operationId: shiftsGet
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The Toast platform GUID of the restaurant that is the 
          context for this operation.
        in: header
        type: string
        format: string
        required: true
      - name: shiftIds
        description: |
          An optional identifier that filters return values for a
          specific shift. The identifier can be a Toast platform GUID
          or an external identifier. If present, the shifts
          resource will only return the shifts you specify. You
          can include multiple `shiftIds` query parameters (maximum
          100).
        in: query
        type: string
        format: string
        required: false
      - name: startDate
        description: |
          Optional start date and time of time period to match 
          shifts. A shift matches the time period if the shift 
          `inDate` is after (inclusive) the specified `startDate` and 
          the shift `outDate` is before the `endDate` (exclusive). 
          These parameters are required if the `shiftIds` parameter 
          is not defined. The specified period cannot be longer than 
          one month.
        in: query
        type: string
        format: ISO-8601
      - name: endDate
        description: |
          Optional end date and time of time period to match shifts. 
          A shift matches the time period if the shift `inDate` is 
          after (inclusive) the specified `startDate` and the shift 
          `outDate` is before the `endDate` (exclusive). These 
          parameters are required if the `shiftIds` parameter is not 
          defined. The specified period cannot be longer than one 
          month.
        in: query
        type: string
        format: ISO-8601
      responses:
        '200':
          description: |
            Returns the specified shifts in an unordered list.
          schema:
            title: Response
            type: array
            items:
              $ref: '#/definitions/Shift'
        '500':
          description: |
            An unexpected internal error occurred. There is a 
            `requestId` attached to this error that can be referenced 
            by Toast support.
      security:
      - oauth2:
        - labor:read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Shifts
      summary: Toast Create a Shift
      description: |
        Creates a schedule shift for a restaurant employee.
      operationId: shiftsPost
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The Toast platform GUID of the restaurant that is the 
          context for this operation.
        in: header
        type: string
        format: string
        required: true
      - name: Content-Type
        description: |
          The Internet Assigned Numbers Authority (IANA) media type 
          of the message body data. The value must be 
          `application/json`.
        in: header
        type: string
        format: string
        required: true
      - name: body
        description: |
          A `Shift` object containing information about the shift, 
          including the job identifier, the employee identifier, and 
          the start and end times.
        in: body
        required: true
        schema:
          type: string
          example:
            externalId: MyToastNamingAuthority:1234
            entityType: Shift
            jobReference:
              guid: 678758d1-6aa8-494c-be55-0614f761d160
              externalId: ''
              entityType: RestaurantJob
            employeeReference:
              guid: 7030407f-761c-4d92-86d9-4e84bc700d0f
              externalId: ''
              entityType: RestaurantUser
            inDate: 2015-10-10T06:00:00.000+0000
            outDate: 2015-10-10T12:00:00.000+0000
      responses:
        '200':
          description: |
            Creates a shift record and returns information about it.
          schema:
            $ref: '#/definitions/Shift'
        '400':
          description: |
            The request contains data that is not supported by the 
            current version of the API as described.
        '415':
          description: |
            The request did not have "application/json" in the 
            `Content-Type` header.
        '500':
          description: |
            An unexpected internal error occurred. There is a 
            `requestId` attached to this error that can be referenced 
            by Toast support.
      security:
      - oauth2:
        - labor.shifts:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /shifts/{shiftId}:
    get:
      tags:
      - Shifts
      summary: Toast Get a Shift
      description: |
        Returns a `Shift` object containing of information about one 
        schedule shift for a restaurant employee.
      operationId: shiftsShiftIdGet
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The Toast platform GUID of the restaurant that is the 
          context for this operation.
        in: header
        type: string
        format: string
        required: true
      - name: shiftId
        description: |
          The Toast platform GUID or an external identifier for the 
          shift.
        in: path
        type: string
        required: true
      responses:
        '200':
          description: |
            Returns the specified shifts in an unordered list.
          schema:
            $ref: '#/definitions/Shift'
        '400':
          description: |
            The GUID or external identifier was malformed.
        '404':
          description: |
            The GUID or external identifier does not match any shifts
            at the current restaurant.
        '500':
          description: |
            An unexpected internal error occurred. There is a 
            `requestId` attached to this error that can be referenced 
            by Toast support.
      security:
      - oauth2:
        - labor:read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Shifts
      summary: Toast Update a Shift
      description: |
        Updates an existing schedule shift record for a restaurant 
        employee. A `PUT` request completely replaces the information 
        in the existing record.
      operationId: shiftsShiftIdPut
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The Toast platform GUID of the restaurant that is the 
          context for this operation.
        in: header
        type: string
        format: string
        required: true
      - name: shiftId
        description: |
          The shift identifier, either the Toast platform GUID or an 
          external identifier.
        in: path
        type: string
        format: string
        required: true
      - name: body
        description: |
          The shift information. The `externalId` identifier is not 
          allowed for`PUT` requests.
        in: body
        required: true
        schema:
          type: string
          example:
            entityType: Shift
            jobReference:
              guid: 678758d1-6aa8-494c-be55-0614f761d160
              externalId: ''
              entityType: RestaurantJob
            employeeReference:
              guid: 7030407f-761c-4d92-86d9-4e84bc700d0f
              externalId: ''
              entityType: RestaurantUser
            inDate: 2015-10-10T06:00:00.000+0000
            outDate: 2015-10-10T12:00:00.000+0000
      responses:
        '200':
          description: |
            Returns the updated `Shift`.
          schema:
            $ref: '#/definitions/Shift'
        '400':
          description: |
            The request contains data that is not supported by the 
            current version of the API as described.
        '404':
          description: |
            The GUID or external identifier does not match any shifts
            at the current restaurant.
        '415':
          description: |
            The request did not have `application/json` in the 
            `Content-Type` header.
        '500':
          description: |
            An unexpected internal error occurred. There is a 
            `requestId` attached to this error that can be referenced 
            by Toast support.
      security:
      - oauth2:
        - labor.shifts:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      tags:
      - Shifts
      summary: Toast Delete a Shift
      description: |
        Marks an existing schedule shift record for a restaurant 
        employee as deleted. If the shift record was already deleted, 
        then the operation will succeed (HTTP 200 response code) and no 
        change will be made.
      operationId: shiftsShiftIdDelete
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The Toast platform GUID of the restaurant that is the 
          context for this operation.
        in: header
        type: string
        format: string
        required: true
      - name: shiftId
        description: |
          The shift identifier, either the Toast platform GUID or an 
          external identifier.
        in: path
        type: string
        format: string
        required: true
      responses:
        '200':
          description: |
            Returns the specified shift, with the deleted flag set to 
            `true`.
          schema:
            $ref: '#/definitions/Shift'
        '400':
          description: |
            The Toast platform GUID or external identifier was 
            malformed.
        '40

# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/toast-tab/refs/heads/main/openapi/toast-tab-labor-openapi.yml