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.

External identifiers

You can assign external identifiers to track Toast POS configuration and order objects using identifier strings that match your other information systems. For example, if your organization maintains employee identifiers in a system other than the Toast POS, you can store the employee identifier in the Toast POS record for an employee as an external identifier. Custom external identifiers are optional. The preferred identifier is the Toast Globally Unique Identifier (GUID). Toast APIs are optimized for use with GUIDs.

An external identifier is a bundle of information that uniquely identifies a particular domain object in an external system according to some naming authority, across space and time.

The standard string representation of external identifiers is as follows:

{authority-name}:{identifier}
  • authority-name: the unique name assigned by Toast for the naming authority for this domain object. (required for clients, <= 16 characters)

  • identifier: a string, number or combination thereof, that uniquely identifies a domain object in an external system (required, <= 256 characters)

For example, a partner named MyCompany might schedule shifts for a restaurant in its own systems that are then added to the Toast POS system through an integration process. Some shifts might come from an older system that uses integer keys for such shifts, while a newer web service might assign Globally Unique Identifiers (GUIDs) to objects it creates.

In the above case, there would be three naming authorities:

  • MYCOMPANY-OLD-SYSTEM

  • MYCOMPANY-NEW-SYSTEM

  • TOAST (implied for GUIDs)

and potentially three external identifiers assigned for a particular shift:

  • "MYCOMPANY-OLD-SYSTEM:1234”

  • "MYCOMPANY-NEW-SYSTEM:1234”

  • shift GUID: “3F2504E0-4F89-41D3-9A0C-0305E82C3301” (“TOAST” implied)

Note that the identifier part of both external identifiers from MyCompany use the exact same database identifiers, but that the external identifiers are still unique by naming authority.

Toast assigns the naming authority names and Toast GUIDs.

Client-assigned external identifiers are private. A particular domain object may be created by one partner, updated by Toast, and read by another partner. Toast APIs will always expose the Toast GUID and this GUID can be used in any context, at any time, even in back channel communications between partners. The client-assigned external identifiers, however, will not be exposed to partners who did not create that binding.

In addition to using the Toast labor API to set an externalId for an employee and then GET the employee with the externalId, another frequent use of external Ids is in the orders API: you can POST an order with an externalID, and then GET the order with that externalId.