Restaurant connections

The partners webhook and partners API both provide information about the restaurants you can access. With the partners webhook, the Toast platform pushes updates to your system when a restaurant adds your integration, removes your integration, or edits your integration's settings in the Toast platform. This is the preferred method for getting information about the restaurants you can access.

If you need to retrieve information about the restaurants you can access independently of an event that triggers a webhook update, you can use the /restaurants endpoint of the partners API.

The payload returned by both the partners webhook and the partners API includes location and group identifiers. You can use these identifiers to map restaurants in your system to Toast's restaurants and GUIDs.

This information only applies if you use a partner API account. Integrations that use restaurant management group API accounts cannot use the partners webhook or partners API.

Getting the restaurants you can access

Restaurant employees who have the Account Admin > Manage Integrations access permission can select the integration partners that have access to their restaurants.

When a restaurant employee selects your partner organization and gives you access to integrate with that restaurant:

  • Information about the restaurant is added to the JSON array that you get from the /restaurants endpoint of the partners API.

  • A webhook update is sent to your webhook endpoint, if you have one configured.

For more information about how restaurant employees select integration partners and enable integration access, see Managing and using integrations and Toast Partner Connect.

Getting restaurant access updates from the partners webhook

To use the partners webhook, you must create a webhook endpoint. This is the URL of a webhook consumer service that is capable of receiving webhook events from the Toast platform.

Once you have a webhook endpoint, Toast support can create a webhook subscription for your integration that associates your webhook endpoint with the webhook updates that are triggered by restaurants adding, removing, or reconfiguring your integration.

For general information on setting up and using Toast webhooks, see Using webhooks.

For detailed information on the specific updates provided by the partners webhook, including example payloads, see Partners webhook.

Using the partners API to get restaurant information

To get information about the Toast platform restaurants that your partner API client account can access, you can use the /restaurants endpoint of the Toast partners API.

Only partner API accounts can use the /restaurants endpoint. If you have a restaurant management group API account, you can use the restaurants API to get information about the restaurants in your group. For more information about account types, see Toast API accounts. For more information about the restaurants API, see the restaurants API reference documentation.

The /restaurants endpoint returns an array of JSON objects containing information about each restaurant that you have access to. For more information, see the partners API reference documentation.

Note

The partners API updates the list of restaurants that you have access to immediately after a restaurant employee selects your integration.

For other Toast APIs, such as the orders API or the labor API, it can take up to 15 minutes from the time a restaurant employee gives your integration access before they update their access lists and allow your integration to perform operations at a restaurant.

If a restaurant removes a partner's integration, this restaurant is no longer present in the /restaurants endpoint return data. Consider restaurant additions and removals when you review the results of this endpoint.

How to make the request

You send a GET request to the /restaurants endpoint of the Toast partners API.

https://[toast-api-hostname]/partners/v1/restaurants

Note

The /restaurants endpoint uses the same rate limiting functionality as other Toast API endpoints. For more information, see Rate limiting.

To get information about the restaurants you have access to

  1. Authenticate with the Toast user management service using a partner API account. For more information, see Authentication and restaurant access.

  2. Send a GET request to the /restaurants endpoint of the partners API.

    Optionally, include the lastModified parameter to limit the return data to restaurants created or modified after a specific date and time. The date and time must be a UTC timestamp in ISO 8601 format, for example: 2020-03-01T00:00:00.000-0000.

    You must URL encode the timestamp before sending it in a request. For example, 2020-03-01T00%3A00%3A00.000%2B0000.

  3. Review the information about each restaurant that you have access to in the JSON data that the /restaurants endpoint returns.

    The GUID for a restaurant is in the restaurantGuid value of the return data. The GUID is a unique identifier. You use the Toast platform GUID for a restaurant when you make Toast API requests for that restaurant.

Information in the return data

For each restaurant, the /restaurants return JSON data contains the following values:

Value Description

restaurantGuid

The unique Toast platform identifier for the restaurant.

managementGroupGuid

The unique Toast platform identifier for a group of restaurants. The management group GUID is the same for all restaurants in the same group.

If a restaurant location does not belong to a restaurant management group, then the management group GUID is null.

restaurantName

The human-readable name of the restaurant location.

locationName

The identifier of a specific restaurant location, set on the Restaurant Info screen of the Toast administration back-end.

For example, a restaurant group might assign a location code such as #1234 to a specific location.

createdByEmailAddress

The email address of the restaurant employee who connected the restaurant to the partner or who edited the connection details.

externalGroupRef

An identifier for the restaurant group that is recognized by the partner that made the request to the /restaurants endpoint.

This information is entered by the restaurant administrator. If you need information about the restaurant group in this data string, you instruct the restaurant administrator to enter it in the Toast platform configuration for the integration partner connection.

For more information, see Using location and group identifiers.

externalRestaurantRef

An identifier for the restaurant location that is recognized by the partner that made the request to the /restaurants endpoint.

This information is entered by the restaurant administrator. If you need information about the restaurant location in this data string, you instruct the restaurant administrator to enter it in the Toast platform configuration for the integration partner connection.

For more information, see Using location and group identifiers.

isoCreatedDate

The date and time that the partner connection was created, expressed in ISO 8601 format.

isoModifiedDate

The most recent date and time that the partner connection was edited, expressed in ISO 8601 format.

createdDate

The date and time that the partner connection was created, expressed in milliseconds from the UNIX epoch, January 1, 1970 00:00:00 UTC.

modifiedDate

The most recent date and time that the partner connection was edited, expressed in milliseconds from the UNIX epoch, January 1, 1970 00:00:00 UTC.

Example return data

The following example shows the return data from the /restaurants endpoint of the partners API.

Return data from the /restaurants endpoint

[
   {
      "restaurantGuid":"0001ac81-423c-a426-0008-02426ac8423c",
      "managementGroupGuid":"88f3cca5-39d9-4acc-8627-3116c748f344",
      "restaurantName":"The Good Restaurant",
      "locationName":null, 
      "createdByEmailAddress":"hester@goodrestaurant.com",
      "externalGroupRef":"goodRestaurant",
      "externalRestaurantRef":"East 25th Street",
      "modifiedDate": 1544022583582,
      "createdDate": 1544022583582,
      "isoModifiedDate": "2018-12-05T15:09:43.582Z",
      "isoCreatedDate": "2018-12-05T15:09:43.582Z"
   },
   {
      "restaurantGuid":"00034778-423c-a426-0008-02561ac81ce6",
      "managementGroupGuid":null,
      "restaurantName":"The Better Restaurant",
      "locationName":null,
      "createdByEmailAddress":"werner@betterrestaurant.com",
      "externalGroupRef": null,
      "externalRestaurantRef": null,
      "modifiedDate": 1544136793429,
      "createdDate": 1544136793429,
      "isoModifiedDate": "2018-12-06T22:53:13.429Z",
      "isoCreatedDate": "2018-12-06T22:53:13.429Z"
   },
   {
      "restaurantGuid":"00013478-1ce6-a426-0008-02561ac81ce6",
      "managementGroupGuid":"88f3cca5-39d9-4acc-8627-3116c748f344",
      "restaurantName":"The Best Restaurant",
      "locationName":null,
      "createdByEmailAddress":"berthoud@bestrestaurant.com",
      "externalGroupRef":"BEST_RESTAURANT",
      "externalRestaurantRef":"Sheffield_008",
      "modifiedDate": 1544626611217,
      "createdDate": 1544626611217,
      "isoModifiedDate": "2018-12-12T14:56:51.217Z",
      "isoCreatedDate": "2018-12-12T14:56:51.217Z"
   }
]

Using location and group identifiers

The My Integrations page contains optional free-text Group ID and Location ID fields, which you can use to map restaurants in your system to Toast's restaurants.

For example, if a restaurant location has a numeric account number in your system, they can add their account identifier to the Location ID field. If a restaurant group has an alphanumeric group identifier in your system, they can add their group identifier to the Group ID field.

Group ID and Location ID fields for a restaurant location

Location ID and group ID values are available in the partners API in the externalGroupRef and externalRestaurantRef fields.

[
   {
      "restaurantGuid":"00034778-423c-a426-0008-02561ac81ce6",
      "managementGroupGuid":"88f3cca5-39d9-4acc-8627-3116c748f344",
      "restaurantName":"Toast Grill & Tap",
      "locationName":"MA",
      "createdByEmailAddress":"werner@toasttrattoria.com",
      "externalGroupRef": "123#",
      "externalRestaurantRef": "ABC",
      "modifiedDate": 1544136793429,
      "createdDate": 1544136793429,
      "isoModifiedDate": "2019-12-06T22:53:13.429Z",
      "isoCreatedDate": "2019-12-06T22:53:13.429Z"
   }
]

If you use a partner API account, Toast support recommends that you include information in your onboarding documentation instructing users on how to fill out these fields.

Integrations that use restaurant management group API accounts cannot use these fields.