This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

Adding an employee

Send a POST request to the /labor/v1/employees resource of the labor API to add an employee to your restaurant. The resource returns a JSON object containing information about the employee, including the Toast POS GUID, when it creates the employee record.

Note

The labor API will reject new or updated employee names and external identifiers that include special characters. The Employee object values that will reject special characters are firstName, lastName, and externalEmployeeId. Special characters that are not allowed are: {}<>$=\;%

The following example curl command sends a POST request to the /labor/v1/employees resource.

Add an Employee to a Restaurant

curl -X POST \
-H "Authorization: Bearer eyJzI1NiJ9hbGciOiJSU.eyJhd9yaXR5Ij
oiQ1JVTkNIVElNRSIsInJzR3VpZCI6IjE4YzQ5YWJlLWFlODItNGFlYy04ND
M1LWJhYTRjMjVlYTY2MiIsInNjb3BlIjpbImxWQiOlsidG9hc3QiXSwibmFt
aW5nQXV0aGhYm9yIiwib3JkZXJzIiwidXNlcm1nbXQiXSwiZXhwIjoxNDg0M
zg5ODUwLCJqdGkiOiJlMDYzZjJkMy1jNGYyLTRiZjItODJmNi01MTg1NWMzZ
DAxM2YiLCJjbGllbnRfaWQiOiJjcnVuY2h0aW1lIn0.X1_0y9Hzj5F9gdOw2
o6VSYTyZwooAJiFMDmNakbZrtiUdYwLzuLwLpCMQzX5pKYtOqDUz_cetGJL3
txKL1L-K2j1Enoq8An8hEM6e8J0KdAiwrYFO3W3CmWedaoz95K9ghNZVCs28
Td2Sp3Ix3fObxbrvanocx9_OT8S9uM8hdSXmBI_ykTWvOVgK4hO24V3DJy4b
9bz1FtgOvrClhELxCe8dJy7jiwAR60xczlCF5rna98RMLN6zY4ffjmljKFZ6
QV0KkVppWjEiJn7oFHiIylCX1sSg7sddrGatj0xJzts3GJ8u8_lryUNHaEvJ
dWq4Yzwo007AMgxjH9d241Y-g" \
-H "Toast-Restaurant-External-ID: 4622e7a9-b4be-3fef-9220-b3dad273e0b4" \1
-H "Content-Type: application/json" \2
-d @my-new-employee-data.json \3
https://[toast-api-hostname]/labor/v1/employees

1

Specify the GUID of the restaurant that you want to add an employee to. This must be an individual restaurant, not the GUID for a restaurant group.

2

Specify the data type of the message body in the Content-Type header field. The value must be application/json.

3

Include information about the new employee in the message body of the POST request. This example curl command sends message body data from the contents of a file.


The following example shows the JSON message body data that provides information about the new employee.

JSON Message Body Content to Add an Employee

{
  "entityType": "RestaurantUser",1
  "firstName": "Josephine",2
  "lastName": "Gauthier",3
  "email": "jgauthier@example.com",4
  "passcode": "12345",5
  "jobReferences": [6
    {
      "guid": "8d3bba92-10e4-4345-9ae6-ed94c09dc332",
      "entityType": "RestaurantJob"
    }
  ]
}

1

Specify the data type of the Toast POS input object. The value must be RestaurantUser.

2

Specify the first name of the employee.

3

Specify the last name of the employee.

4

Specify an email address for the employee. Email addresses for employees must be unique. If you specify an email address that is in use by an employee, the request fails with an HTTP 400 (bad request) response.

5

You can specify the initial Toast POS pass code number for the employee. This value is optional.

6

You can specify the job for the new employee. This value is optional. To assign a job you need the Toast POS GUID or the external identifier for the job.


The following example shows the JSON response data for a POST request to the /labor/v1/employees resource.

Add Employee Response Data

{
  "guid": "e5c3a2f3-8aa2-4a66-b379-6c80b7277dc3",1
  "entityType": "RestaurantUser",
  "externalId": null,
  "lastName": "Gauthier",
  "wageOverrides": [],
  "firstName": "Josephine",
  "createdDate": "2019-10-02T13:11:22.824+0000",
  "deleted": false,
  "deletedDate": null,
  "jobReferences": [2
    {
      "guid": "8d3bba92-10e4-4345-9ae6-ed94c09dc332",
      "entityType": "RestaurantJob",
      "externalId": null
    }
  ],
  "modifiedDate": "2019-10-02T13:11:22.824+0000",
  "disabled": null,
  "externalEmployeeId": null,
  "email": "jgauthier@example.com",
  "passcode": "12345"3
}

1

The guid value contains the GUID value that the Toast POS assigns to the new employee.

2

If you assign a job to the new employee, the response data will return the job. This is optional.

3

If you assign an initial pass code to the new employee, the employee will be able to log in to the Toast POS. This is optional.