openapi: 3.2.0
info:
  title: Analytics Labor API
  description: "The analytics API provides an enterprise reporting and analytics service, \nand includes operations that retrieve information for all restaurants, or a\nsubset of restaurants, in a management group, create requests for reporting data, \nand retrieve the reporting data.\n\nThe types of reporting data include:\n* Aggregated sales reporting data covering sales and labor information.\n* Check reporting data providing information for each check.\n* Labor reporting data providing information for employees and jobs that are paid hourly.\n* Menu reporting data providing information for menu entities as they relate to sales.\n* Payout reporting data providing information for payouts organized either by settled date, payments, or sales date.\n* Guest reporting data providing information for guest's payment cards organized by payments.\n"
  version: 1.0.0
  contact:
    name: Toast developer support
servers:
- url: https://toast-api-server/era/v1
tags:
- name: Labor
  description: The analytics API endpoints for labor reporting data. This only supports hourly job and employee data.
paths:
  /labor/{timeRange}:
    post:
      summary: Post a labor data request for a specific time range
      description: "Creates a labor reporting data request for a specific time range.\n\nSpecify the time range with the `timeRange` path parameter.\n\nSpecify whether to include data from inactive restaurants using the `onlyInactiveRestaurants` query parameter.\n\nSpecify the `startBusinessDate` and `endBusinessDate` for the labor data in the message body.\n\nInclude information about which restaurants to include or exclude with the \n`restaurantIds` and `excludedRestaurantIds` properties.\n\nInclude information about how to aggregate the data with the `groupBy` property.\n"
      operationId: postLaborReportingDataSpecificTimeRangeRequest
      parameters:
      - name: timeRange
        description: 'The specific time range that you are requesting reporting data for.


          Valid values:


          * `day` - The request covers a one day time range.


          * `week` - The request covers a time range of seven days or fewer.


          * `month` - The request covers a time range of 31 days or fewer.

          '
        in: path
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
      - name: onlyInactiveRestaurants
        description: "Specifies whether the data is for inactive restaurants only. Active restaurant data is \nreturned by default.\n\nValid values:\n\n* `true` - The data retrieved is for inactive restaurants only.\n\n* `false` - The data retrieved is for active restaurants only.\n"
        in: query
        required: false
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LaborReportingDataRequest'
        description: "A JSON object containing the starting and ending dates for the reporting metrics \nrequest, included or excluded restaurants, and aggregation options.\n"
        required: true
      responses:
        '200':
          description: The `reportRequestGuid` used to retrieve the reporting data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportRequestGuid'
        '400':
          description: The request contains invalid information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: 'An unexpected internal error occurred. The

            `requestId` attached to this error can be referenced by

            the Toast support team.

            '
      security:
      - oauth2:
        - enterprise-metrics:read
      tags:
      - Labor
  /labor/{reportRequestGuid}:
    get:
      summary: Get the labor reporting data
      description: 'Returns the labor data for the reporting data request.


        Specify the `reportRequestGuid` for the reporting data.

        '
      operationId: getLaborReportingData
      parameters:
      - name: reportRequestGuid
        description: The Toast platform identifier for the reporting data request.
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The reporting data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LaborReportingData'
        '202':
          description: The Toast platform is in the process of gathering the reporting data. Try the request again at a later time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportingDataInProgress'
        '404':
          description: An unexpected error occurred. Refer to the `message` attached to this error for more information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: The Toast platform was unable to process the request. Request a new `reportRequestGuid` and try again.
        '500':
          description: 'An unexpected internal error occurred. The

            `requestId` attached to this error can be referenced by

            the Toast support team.

            '
        '504':
          description: The Toast platform was unable to process the request because internal services took too long to process, resulting in a timeout.
      security:
      - oauth2:
        - enterprise-metrics:read
      tags:
      - Labor
components:
  schemas:
    LaborReportingDataRequest:
      description: "Information about what the labor data covers and how it is presented. This includes \nthe starting and ending dates of the time range, the included or excluded restaurants, and \naggregation options.\n"
      type: object
      properties:
        startBusinessDate:
          description: 'The starting date of the time range for the reporting data.


            Specify the business day in the format YYYYMMDD. For example, `20220824`.

            '
          format: integer
          type: number
        endBusinessDate:
          description: 'The ending date of the time range for the reporting data.


            Specify the business day in the format YYYYMMDD. For example, `20220824`.

            '
          format: integer
          type: number
        restaurantIds:
          description: "The `restaurantGuid` values of specific restaurants in the management group to include in the \nreporting data. If used, only the data for listed restaurants in the management group \nthat are identified by `restaurantGuid` is included. If left blank, all restaurants are included \nby default.\n"
          items:
            format: uuid
            type: string
          type: array
        excludedRestaurantIds:
          description: "The `restaurantGuid` values of specific restaurants in the management group to exclude from the \nreporting data. If used, the data for listed restaurants in the management group \nthat are identified by `restaurantGuid` is excluded. If left blank, all restaurants are included \nby default.\n"
          items:
            format: UUID
            type: string
          type: array
        groupBy:
          description: 'The way the reporting data results are aggregated.


            Valid values:


            * `JOB` - The reporting data is grouped by job.


            * `EMPLOYEE` - The reporting data is grouped by employee.

            '
          type: array
          items:
            enum:
            - JOB
            - EMPLOYEE
            type: string
      required:
      - restaurantIds
      - excludedRestaurantIds
      - startBusinessDate
      - endBusinessDate
    ReportRequestGuid:
      description: The Toast platform assigned identifier used to identify a specific analytics reporting data request.
      format: UUID
      type: string
    LaborReportingData:
      description: The labor reporting data.
      type: object
      properties:
        businessDate:
          description: "The date for the aggregated reporting data. The business \nday uses the YYYYMMDD format. For example, `20220824`.\n"
          format: integer
          type: string
        restaurantGuid:
          description: 'The identifier assigned by the Toast platform used to identify a restaurant location.

            '
          format: UUID
          type: string
        restaurantName:
          description: 'The restaurant''s name.

            '
          format: string
          type: string
        restaurantLocationName:
          description: 'The restaurant''s location name.

            '
          format: string
          type: string
        restaurantLocationCode:
          description: 'The restaurant''s location code.

            '
          format: string
          type: string
        regularHours:
          description: 'The total regular hours logged between clock-in and clock-out for employees with hourly jobs. This does not include overtime hours.

            '
          format: double
          type: number
        overtimeHours:
          description: 'The total overtime hours logged between clock-in and clock-out for employees with hourly jobs. This only includes overtime hours.

            '
          format: double
          type: number
        totalHours:
          description: 'The total hours logged between clock-in and clock-out for employees with hourly jobs. This includes regular and overtime hours.

            '
          format: double
          type: number
        regularCost:
          description: The operation costs related to employees with hourly jobs from all regular hours, including all shifts.
          format: double
          type: number
        overtimeCost:
          description: The operation costs related to employees with hourly jobs from all overtime hours, including all shifts.
          format: double
          type: number
        totalCost:
          description: The operation costs related to employees with hourly jobs from all work hours, including all shifts.
          format: double
          type: number
        netSalesAmount:
          description: "The total sales, excluding tax, gratuity, tips, discounts, refunds, and \ndeferred amounts. This property is only included when no `groupBy` value is specified.\n"
          format: double
          type: number
        grossSalesAmount:
          description: 'The total sales, including discounts and refunds. This property is only included when no `groupBy` value is specified.

            '
          format: double
          type: number
        netSalesPerEmployeeHour:
          description: 'The average of the location''s total net sales for each hour clocked by an employee. This property is only included when no `groupBy` value is specified.

            '
          format: double
          type: number
        grossSalesPerEmployeeHour:
          description: 'The average of the location''s total gross sales for each hour clocked by an employee. This property is only included when no `groupBy` value is specified.

            '
          format: double
          type: number
        totalCostPerNetSales:
          description: 'The ratio of employee operational costs compared to total net sales, expressed as a percentage.

            '
          format: double
          type: number
        totalCostPerGrossSales:
          description: 'The ratio of employee operational costs compared to gross sales, expressed as a percentage.

            '
          format: double
          type: number
        jobGuid:
          description: 'The identifier assigned by the Toast platform used to identify a job. This property only appears when the request for labor data includes the `groupBy` property with value `JOB`.

            '
          format: UUID
          type: string
        jobTitle:
          description: 'The guest-facing job name. This property only appears when the request for labor data includes the `groupBy` property with value `JOB`.

            '
          type: string
        jobCode:
          description: 'The guest-facing job code. This property only appears when the request for labor data includes the `groupBy` property with value `JOB`.

            '
          type: string
        employeeGuid:
          description: 'The identifier assigned by the Toast platform used to identify an employee. This property only appears when the request for labor data includes the `groupBy` property with value `EMPLOYEE`.

            '
          type: string
        employeeFirstName:
          description: 'The employee''s first name. This property only appears when the request for labor data includes the `groupBy` property with value `EMPLOYEE`.

            '
          type: string
        employeeLastName:
          description: 'The employee''s last name. This property only appears when the request for labor data includes the `groupBy` property with value `EMPLOYEE`.

            '
          type: string
        employeeChosenName:
          description: 'The employee''s chosen name. This property only appears when the request for labor data includes the `groupBy` property with value `EMPLOYEE`.

            '
          type: string
    ErrorMessage:
      type: object
      description: Information about an unsuccessful REST request.
      properties:
        status:
          description: The HTTP status code.
          format: integer
          type: number
        code:
          description: The service-specific result code.
          format: integer
          type: number
        message:
          description: A brief message describing the error.
          type: string
        messageKey:
          description: Reserved for future use.
          type: string
        fieldName:
          description: Reserved for future use.
          type: string
        link:
          description: The URL of a Toast page that provides more information about the error.
          format: URL
          type: string
        requestId:
          description: The identifier of the HTTP request that generated the error.
          format: UUID
          type: string
        developerMessage:
          description: Optional, technical information to help a developer investigate the cause of the error.
          type: string
        errors:
          description: A list of JSON `ErrorMessage` objects.
          items:
            type: string
          type: array
        canRetry:
          description: Reserved for future use.
          type: string
    ReportingDataInProgress:
      description: The Toast platform is in the process of gathering the reporting data. Try the request again at a later time.
      type: object
      properties:
        message:
          description: A brief message describing that the reporting data is still in progress and to try again at a later time.
          format: string
          type: string
        reportStatus:
          description: Reflects the in progress status of the reporting data using the IN_PROGRESS value.
          format: text
          type: string
        reportRequestGuid:
          description: The Toast platform assigned identifier used to identify a specific analytics reporting data request.
          format: UUID
          type: string
  securitySchemes:
    oauth2:
      description: "Access to Toast APIs, specific endpoints, \nand specific API endpoint operations is \ncontrolled by the scopes that are associated \nwith your API account. \n\nA full reference for Toast API scopes and \ntheir capabilities can be found in the\n[_Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiScopes.html).\n"
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://toast-api-server/authentication/v1/authentication/login
          scopes:
            enterprise-metrics:read: 'Allows reading from the analytics API.

              '
x-components: {}