Toast Employees API

openapi: 3.2.0
info:
  version: 1.9.0
  title: Toast Labor Employees 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: Employees
paths:
  /employees:
    get:
      tags:
      - Employees
      summary: Toast Get Employees
      description: 'Returns an array of `Employee` objects containing information

        about restaurant employees.'
      operationId: employeesGet
      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: employeeIds
        description: "An optional identifier that filters return values for a \nspecific employee. The identifier can be a Toast platform \nGUID or an external identifier. If present, the `employees` \nresource will only return the employees you specify. You \ncan include multiple `employeeIds` query parameters \n(maximum 100). If not present, the resource returns each \nemployee for the restaurant.\n"
        in: query
        schema:
          type: string
          format: string
      responses:
        '200':
          description: 'JSON objects for all employees in the restaurant

            '
          content:
            application/json:
              schema:
                title: Response
                type: array
                items:
                  $ref: '#/components/schemas/Employee'
        '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.employees:read
    post:
      tags:
      - Employees
      summary: Toast Add an Employee
      description: Creates a restaurant employee record.
      operationId: employeesPost
      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 created employee.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '400':
          description: "The request contains data that is not supported by the \ncurrent version of the API as described.\n"
        '415':
          description: "The request did not have \"application/json\" in the \nContent-Type header.\n"
        '500':
          description: "An unexpected internal error occurred. There is a requestId \nattached to this error that can be referenced by Toast \nsupport.\n"
      security:
      - oauth2:
        - labor.employees:write
      requestBody:
        content:
          application/json:
            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
        description: "An `Employee` object containing information about the \nemployee, including the employee's name and email address.\n"
        required: true
  /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
      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: employeeId
        description: 'The Toast platform GUID or external identifier for the

          employee to be returned.

          '
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Returns the employee information.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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 \nemployees at the current restaurant.\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.employees:read
    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
      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: employeeId
        description: "The Toast platform GUID or external identifier for the \nemployee to be deleted.\n"
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: "The employee has been deleted. Returns an `Employee` object \ncontaining information about the deleted restaurant \nemployee.\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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 \n`requestId` attached to this error that can be referenced \nby Toast support.\n"
      security:
      - oauth2:
        - labor.employees:write
    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
      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
      - name: employeeId
        description: "The Toast platform GUID or external identifier for the \nemployee to be returned.\n"
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Returns the updated Toast platform employee record.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '400':
          description: "The Toast platform GUID or external identifier was \nmalformed, or the body of the request was malformed.\n"
        '404':
          description: "The Toast platform GUID or external identifier does not \nmatch any employees at the current restaurant.\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.employees:write
      requestBody:
        content:
          application/json:
            schema:
              type: string
              example:
                firstName: Mynewfirstname
                chosenName: Mynewchosenname
                lastName: Mynewlastname
                externalEmployeeId: '1234567890'
                passcode: '1234'
                currentPasscode: '1111'
        description: "A JSON object containing the employee information that you \nare updating. You can update an employee's:\n\n* `firstName` - First name.\n\n* `chosenName` - Chosen name.\n\n* `lastName` - Last name.\n\n* `externalEmployeeId` - External employee identifier.\n\n* `passcode` - The passcode for access to Toast POS devices.\n\nAll values are optional. You must include at least one \nvalue. Each value that you include must contain information \n(not null). If you include the `passcode` value to update \nan employee's passcode you must include the employee's \ncurrent passcode in the `currentPasscode` value.\n"
        required: true
  /employees/{employeeId}/externalId:
    parameters:
    - name: employeeId
      description: 'The Toast platform GUID of the employee record.

        '
      in: path
      required: true
      schema:
        type: string
    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
      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 employee record.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
      security:
      - oauth2:
        - labor.employees:write
      requestBody:
        content:
          application/json:
            schema:
              type: string
              example: MyToastNamingAuthority:9876543210
        description: "The JSON string value of the `externalId` for the employee \nrecord. Wrap the value in double quotation marks to make it \nvalid JSON syntax.\n"
        required: true
    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
      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 employee record.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
      security:
      - oauth2:
        - labor.employees:write
      requestBody:
        content:
          application/json:
            schema:
              type: string
              example: MyToastNamingAuthority:9876543210
        description: "The JSON string value of the `externalId` for the employee \nrecord. Wrap the value in double quotation marks to make it \nvalid JSON syntax.\n"
        required: true
  /employees/{employeeId}/unarchive:
    parameters:
    - name: employeeId
      description: 'The Toast platform GUID of the employee record.

        '
      in: path
      required: true
      schema:
        type: string
    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
      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 employee record.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '400':
          description: 'Employee being unarchived is not currently archived.

            '
      security:
      - oauth2:
        - labor.employees:write
  /employees/{employeeId}/jobs:
    parameters:
    - name: employeeId
      description: 'The Toast platform GUID of the employee record.

        '
      in: path
      required: true
      schema:
        type: string
    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
      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 employee record.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
      security:
      - oauth2:
        - labor.employees:write
      requestBody:
        content:
          application/json:
            schema:
              type: string
              example:
              - guid: dd8cea7a-add5-4508-b8fe-ffd0b584e4da
              - externalId: MyToastNamingAuthority:9876543210
        description: "An array of JSON objects containing identifiers for jobs. \nThe identifiers can be either Toast platform GUIDs or \nexternal identifiers.\n"
        required: true
  /employees/{employeeId}/wageOverrides:
    parameters:
    - name: employeeId
      description: 'The Toast platform GUID of the employee record.

        '
      in: path
      required: true
      schema:
        type: string
    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
      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: "The wage overrides for the employee are replaced. Returns \nthe updated employee record.\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
      security:
      - oauth2:
        - labor.employees:write
      requestBody:
        content:
          application/json:
            schema:
              type: string
              example:
              - jobReference:
                  guid: 8d3bba92-10e4-4345-9ae6-ed94c09dc332
                wage: 15.75
        description: 'An array of JSON `JobWageOverride` objects.

          '
        required: true
components:
  schemas:
    JobWageOverride:
      type: object
      description: "The overriding job wage, for an employee that has a wage that \ndiffers from the job's default wage.\n"
      required:
      - wage
      - jobReference
      properties:
        wage:
          type: number
          format: double
          description: 'Required currency value of the employee''s overriding job wage.

            '
        jobReference:
          type: object
          description: "Required external reference to the job to which this wage \napplies overridden\n"
          $ref: '#/components/schemas/ExternalReference'
    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
    Employee:
      type: object
      description: A restaurant employee
      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).

              '
          firstName:
            type: string
            description: 'Optional, first name of the employee.

              '
          chosenName:
            type: string
            description: 'Optional, chosen name of the employee. To be used, when appropriate, in place of first name.

              '
          lastName:
            type: string
            description: 'Optional, last name of the employee.

              '
          email:
            type: string
            description: 'Employee''s email address.

              '
          phoneNumber:
            type: string
            description: 'Employee''s phone number

              '
          phoneNumberCountryCode:
            type: string
            description: "A numeric code corresponding to one or more countries, \nused as a telephone number prefix when making international telephone calls.\n"
          passcode:
            type: string
            description: "An optional numeric security code that a new employee can \nuse to begin a session in a Toast POS device. The \npasscode value can only occur in `POST` requests. The \nvalue must be numeric and it must contain at least one \nand no more than eight digits. The employee can only use \nthe passcode at the restaurant specified in the `POST` \nrequest.   The response to a successful `POST` request \nwill include the passcode value in clear text. A `GET` \nrequest for the employee will not return the passcode.\n"
          externalEmployeeId:
            type: string
            description: 'Optional, employee’s external ID in the Toast platform.

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

              '
          jobReferences:
            type: array
            description: "An array of external references to jobs assigned to this \nemployee. If the job is deleted, it will be excluded from this array.\n"
            minItems: 0
            items:
              $ref: '#/components/schemas/ExternalReference'
          wageOverrides:
            type: array
            description: "An optional array of per job wage overrides, where each \nelement defines a job reference and the wage override for \nthis employee when performing that job. If the underlying job\nis deleted, it will be excluded from the array.\n"
            minItems: 0
            items:
              $ref: '#/components/schemas/JobWageOverride'
          v2EmployeeGuid:
            type: string
            description: "This value is included for future use. An alternate Toast \nplatform GUID for the employee that will be used in \nupcoming labor API functionality.\n"
    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"