Review and implement the instructions in How to build a Toast integration.

The labor API allows integration partners to create new employees, delete employees, and update existing employees in the Toast platform. Before you begin your integration development, decide which of these operations you will support.

Review the labor API specification when considering which employee fields you will create and update. The labor API supports updating existing employees’ jobs, wage overrides, names, external IDs, and passcodes.

Employees in the Toast platform receive permissions based on their assigned jobs. Jobs have default wages, though a restaurant administrator can choose to override a particular employee's wage. Restaurant administrators can also modify employees’ permissions in the Toast platform after your integration submits the employee information. See this Toast Central article for more information about editing employees in the Toast platform.

The Employee object contains an externalEmployeeId value that you can use to map employees in your system to employees in the Toast platform. Consider using this field to make it easier for restaurant administrators to understand this mapping of employees between the two systems.

You should not use the externalEmployeeId field for sensitive information such as Social Security numbers. This field is for general employee identification and mapping.

If a restaurant begins to use your integration after they are already live on the Toast platform, you need to map the existing employees and jobs in the Toast platform to employees and jobs in your system.

Consider loading initial employee information when a restaurant first connects to your platform. You can match employees based on identifying information such as names and email addresses. If you will use the externalEmployeeId field, you can also use this field to map employees in the Toast platform to employees in your system.

Use the /jobs endpoint of the labor API to load initial job information. See the labor API information for the jobs endpoint specification.

Given the sensitivity of employee information, it is important for restaurants to understand the employee updates that your system generated and why these employee updates occurred.

Before you build new functionality, consider the audit trail information you will expose to restaurants so that they understand how employee updates in your system affect employee information in the Toast platform.

Build functionality in which restaurant administrators can create an employee in your system and your integration submits this employee's information to Toast. See Adding an employee for more information. When applicable, assign jobs, wage overrides, and an externalEmployeeId.

If the employee will log into a point-of-sale device, include a passcode on the Employee object. If you do not include a passcode, the employee can log into Toast Web, but cannot log into a Toast POS device unless an administrator updates their permissions in the Toast platform.

After you build the initial employee creation functionality, build and test the employee update and deletion functionality if your integration supports those functions.

Build an initial employee and job load based on the functionality you planned earlier.

Test that employees and jobs in the Toast platform match employees and jobs in your system in the way that you expect.

Your integration should include an audit trail of the updates in your system that prompted employee updates in the Toast platform.

It is important for restaurant administrators to understand the updates in your system that triggered corresponding updates in the Toast platform, so that they do not need to contact your support team or Toast's support team to understand why an employee update occurred.

If you attempt to make multiple updates to the same employee at the same time, one of the requests may receive an error and the Toast platform will not reflect the update. For example, you cannot simultaneously update the first name of an employee through one PUT request and the last name of an employee in a different PUT request.

To avoid this error, it is best to either batch the changes to a single employee into a single request, or wait for a response from the Toast API between changes to a single employee.

If an employee is clocked in, attempting to delete the employee returns a 400 HTTP response status code.

To prevent this problem, send a GET request to the /timeEntries endpoint of the labor API to see if there are any time entries for this employee that have a populated inDate and a null outDate.

In this situation, your integration should either prevent restaurant administrators from deleting employees who are clocked in or display a user-friendly error message.

Employee email addresses are the primary key that denote employee uniqueness.

If you attempt to create an employee whose email address matches that of another employee at the same restaurant location, you receive a 400 HTTP response status code.

You need to track the employee email addresses that already exist at a location in the Toast platform so that you do not create duplicate employees.

Passcodes must be unique among all employees at a single restaurant location. They also must must also contain 1 to 8 numeric characters.

If you attempt to create or update an employee with the same passcode as another employee at the same location, or you submit a passcode that is anything other than 1-8 numeric characters, the labor API returns a 400 HTTP response status code.

Employee names and external identifiers cannot contain any of the following special characters: ({}<>$=\;%).

Ensure that your platform does not allow employee names to contain any of these characters, so that you do not submit these characters in the firstName, lastName, or externalEmployeeId values.

Toast platform restaurant administrators may update employee information directly from Toast Web. You should periodically retrieve information from the /employees endpoint of the labor API to sync any updates made in the Toast platform.

If updates from the Toast platform differ from updates in your system, your system should ask restaurant administrators to determine whether the Toast platform or your system is correct.