Toast Jobs API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Toast Authentication Jobs API
  description: 'The authentication API returns an authentication token that you can present

    when your integration client software uses other Toast APIs. For more

    information about authentication, see [the Toast Developer

    Guide](https://doc.toasttab.com/doc/devguide/authentication.html).

    '
  termsOfService: https://pos.toasttab.com/api-terms-of-use
  contact:
    name: Toast developer support
servers:
- url: https://toast-api-server/authentication/v1
tags:
- name: Jobs
paths:
  /jobs:
    get:
      tags:
      - Jobs
      summary: Toast Get Jobs
      description: "Returns an array of `Job` objects containing information about \nthe employee jobs configured at a restaurant. By default, if no\njob IDs are provided in the request, deleted jobs will be excluded\nfrom the array.\n"
      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 \nemployee job at a restaurant.\n"
      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 \nstring value of the new external identifier in the message \nbody.\n\nYou cannot change an existing external identifier with another \n`POST` request. The Toast platform uses this external \nidentifier as one of the unique, persistent identifiers for a \njob record.\n"
      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. \nInclude the string value of the new external identifier in the \nmessage body.\n\nThe Toast platform uses this external identifier as one of the \nunique, persistent identifiers for a job record. _Changing the \nexternal identifier for an existing job might affect reporting \nand other Toast platform functions that select jobs using the \n`externalId` value._\n"
      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:
    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
    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"
externalDocs:
  description: Authentication developer guide
  url: https://doc.toasttab.com/doc/devguide/authentication.html