Toast Jobs API

openapi: 3.2.0
info:
  version: 1.9.0
  title: Toast Labor Jobs 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
servers:
- url: https://toast-api-server/labor/v1
tags:
- name: Jobs
paths:
  /jobs:
    get:
      tags:
      - Jobs
      summary: Toast Get Jobs
      description: 'Returns an array of `Job` objects containing information about

        the employee jobs configured at a restaurant. By default, if no

        job IDs are provided in the request, deleted jobs will be excluded

        from the array.'
      operationId: jobsGet
      parameters:
      - name: Toast-Restaurant-External-ID
        description: "The Toast platform GUID of the restaurant that is the \ncontext for this operation.\n"
        in: header
        required: true
        schema:
          type: string
          format: string
      - name: jobIds
        description: "An optional array of one or more job identifiers, either \nthe Toast platform GUID or an external identifier assigned \nby the client. 100 max. If not provided, all jobs known to \nthe Toast platform for this restaurant will be returned.\n"
        in: query
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: 'Returns the specified jobs.

            '
          content:
            application/json:
              schema:
                title: Response
                type: array
                items:
                  $ref: '#/components/schemas/Job'
        '500':
          description: "An unexpected internal error occurred. There is a \n`requestId` attached to this error that can be referenced \nby Toast support.\n"
      security:
      - oauth2:
        - labor:read
  /jobs/{jobId}:
    get:
      tags:
      - Jobs
      summary: Toast Get One Job
      description: 'Returns a `Job` object containing information about one

        employee job at a restaurant.'
      operationId: jobsJobIdGet
      parameters:
      - name: Toast-Restaurant-External-ID
        description: "The Toast platform GUID of the restaurant that is the \ncontext for this operation.\n"
        in: header
        required: true
        schema:
          type: string
          format: string
      - name: jobId
        description: "The Toast platform GUID or an external identifier for the \njob.\n"
        in: path
        required: true
        schema:
          type: string
          format: string
      responses:
        '200':
          description: 'Returns the specified job.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: "The Toast platform GUID or external identifier was \nmalformed.\n"
        '500':
          description: "An unexpected internal error occurred. There is a \n`requestId` attached to this error that can be referenced \nby Toast support.\n"
      security:
      - oauth2:
        - labor:read
  /jobs/{jobId}/externalId:
    parameters:
    - name: jobId
      description: "The Toast platform GUID or external identifier of the job \nrecord.\n"
      in: path
      required: true
      schema:
        type: string
    post:
      tags:
      - Jobs
      summary: Toast Add an External Identifier
      description: 'Adds an external identifier for an existing job. Include the

        string value of the new external identifier in the message

        body.


        You cannot change an existing external identifier with another

        `POST` request. The Toast platform uses this external

        identifier as one of the unique, persistent identifiers for a

        job record.'
      operationId: jobsJobIdExternalIdPost
      parameters:
      - name: Toast-Restaurant-External-ID
        description: "The Toast platform GUID of the restaurant that is the \ncontext for this operation.\n"
        in: header
        required: true
        schema:
          type: string
          format: string
      - name: Content-Type
        description: "The Internet Assigned Numbers Authority (IANA) media type \nof the message body data. The value must be \n`application/json`.\n"
        in: header
        required: true
        schema:
          type: string
          format: string
      responses:
        '200':
          description: 'Returns the updated job record.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
      security:
      - oauth2:
        - labor.jobs:write
      requestBody:
        content:
          application/json:
            schema:
              type: string
              example: MyToastNamingAuthority:9876543210
        description: "The JSON string value of the `externalId` for the job \nrecord. Wrap the value in double quotation marks to make it \nvalid JSON syntax.\n"
        required: true
    put:
      tags:
      - Jobs
      summary: Toast Add or Replace an External Identifier
      description: 'Adds or replaces the external identifier for an existing job.

        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 a job record. _Changing the

        external identifier for an existing job might affect reporting

        and other Toast platform functions that select jobs using the

        `externalId` value._'
      operationId: jobsJobIdExternalIdPut
      parameters:
      - name: Toast-Restaurant-External-ID
        description: "The Toast platform GUID of the restaurant that is the \ncontext for this operation.\n"
        in: header
        required: true
        schema:
          type: string
          format: string
      - name: Content-Type
        description: "The Internet Assigned Numbers Authority (IANA) media type \nof the message body data. The value must be \n`application/json`.\n"
        in: header
        required: true
        schema:
          type: string
          format: string
      responses:
        '200':
          description: 'Returns the updated job record.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
      security:
      - oauth2:
        - labor.jobs:write
      requestBody:
        content:
          application/json:
            schema:
              type: string
              example: MyToastNamingAuthority:9876543210
        description: "The JSON string value of the `externalId` for the job \nrecord. Wrap the value in double quotation marks to make it \nvalid JSON syntax.\n"
        required: true
components:
  schemas:
    Job:
      type: object
      description: A restaurant job.
      allOf:
      - $ref: '#/components/schemas/ExternalReference'
      - type: object
        properties:
          createdDate:
            type: string
            format: date-time
            description: 'Date created, in UTC format (read-only).

              '
          modifiedDate:
            type: string
            format: date-time
            description: 'Date modified, in UTC format (read-only).

              '
          deletedDate:
            type: string
            format: date-time
            description: 'Date deleted, in UTC format (read-only).

              '
          title:
            type: string
            description: 'Title of the job.

              '
          deleted:
            type: boolean
            description: 'If the job is deleted in the Toast platform.

              '
          wageFrequency:
            type: string
            description: "An enumerated type specifying how to interpret the \ndefault wage for this job.\n"
            enum:
            - HOURLY
            - SALARY
          defaultWage:
            type: number
            format: double
            description: 'The default wage of the job.

              '
          tipped:
            type: boolean
            description: 'Indicates whether the job receives gratuities (tips).

              '
          code:
            type: string
            description: "A reference identifier for the job. This is an optional \nfield entered when the job is created. For example, it \ncan be used to match Toast platform jobs to jobs \nconfigured in external labor management systems.\n"
          excludeFromReporting:
            type: boolean
            description: "Indicates whether labor summary reports should include hours and pay \nfor this job. Restaurant employees set this configuration option for a job \non the **Jobs** page of Toast Web.\n"
    ToastReference:
      type: object
      description: "A wrapper object with fields that allow reference to a Toast \nplatform entity by Toast GUID.\n"
      required:
      - guid
      - entityType
      properties:
        guid:
          description: 'The GUID maintained by the Toast platform.

            '
          type: string
        entityType:
          description: 'The type of object this is.

            '
          type: string
    ExternalReference:
      type: object
      description: "A wrapper object with fields that allow reference to a Toast \nplatform entity by Toast GUID or an external identifier.\n"
      allOf:
      - $ref: '#/components/schemas/ToastReference'
      - type: object
        properties:
          externalId:
            description: "External identifier string that is prefixed by the naming \nauthority. You can, for example, use the labor API to \n`POST` an `externalId` for an employee and then `GET` the \nemployee with that `externalId`.\n"
            type: string
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            labor.employees:read: 'Allows reading employee information from the labor API.

              '
            labor.employees:write: 'Allows updating employee information in the labor API.

              '
            employees.tax-identifier-unmasked:read: 'Allows reading full unmasked tax identifier (SSN) information for employees

              via expand parameter.

              '
            employees.tax-identifier-masked:read: 'Allows reading masked tax identifier (SSN) information for employees via

              expand parameter.

              '
            labor:read: 'Allows reading all data except employees from the labor API.

              '
            labor.shifts:write: 'Allows updating shift information in the labor API.

              '
            labor.jobs:write: 'Allows updating job information in the labor API.

              '
          tokenUrl: https://toast-api-server/authentication/v1/authentication/login
      description: "Access to Toast APIs, specific endpoints, \nand specific API endpoint operations is \ncontrolled by the scopes that are associated \nwith your API account. \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"