This section provides reference information about the endpoints and data types of the Toast customer relations management (CRM) API. For more information about using the crm API and code examples, see Working with guests (deprecated). For general information about working with Toast APIs, see API overview.

Important

The CRM API is deprecated and will be replaced by future Toast API functionality. Before beginning development work using the CRM API, contact the Toast technical partnership team to make sure your integration plans are coordinated with upcoming API changes.

Toast CRM API

Base URL: /crm/v1, Version: 1.0.0

Overview

The Toast CRM (customer relations management) API provides access to information about restaurant customers and the customer credits that your restaurant gives to customers for future purchases.

You can use the Toast CRM API to:

• Get information about restaurant customers.
• Add customer information for a restaurant.
• Add customer credits for a customer.
• Redeem customer credits for a customer.
• Get information about the customer credits your restaurants have given to a customer.
• Get information about the customer credit transactions your restaurants have processed for a customer.

Default request content-types: application/json

Default response content-types: application/json

Schemes: https

Summary

Path	Operation	Description
/creditTransactions	GET	Gets information about customer credit transactions for a specific restaurant.
/creditTransactions/{transactionId}	GET	Gets information about a specific customer credit transaction.
/customers	POST	Creates a new restaurant customer record.
/customers/search	POST	Accepts a search query and retrieves information about restaurant guests who match the query value.
/customers/{customerId}	GET	Gets information about a specific restaurant customer.
/customers/{customerId}/creditSummary	GET	Gets information about the customer credits available to a restaurant customer.
/customers/{customerId}/creditTransactions	GET	Gets information about customer credit transactions for a specific restaurant customer.
	POST	Creates a customer credit transaction for a specific restaurant customer.

Paths

Gets information about customer credit transactions for a specific restaurant.

GET /creditTransactions

Gets an array of CustomerTransaction objects containing information about customer credit transactions at a restaurant during a period of time. The objects in the array are ordered from newest to oldest.

Toast-Restaurant-External-ID	The Toast POS GUID of the restaurant.	header	string (string)
startDate	Returns customer credit transactions that occurred at or after the date and time you specify. Use ISO-8601 format.	query	integer (timestamp)
endDate	Returns customer credit transactions that occurred at or before the date and time you specify. Use ISO-8601 format.	query	integer (timestamp)
pageSize	The number of objects to return in the array. The default number is 20. The maximum number is 50.	query	integer
page	The result set sequence number (or offset) of the first object in the response array. By default, the endpoint returns the first object in the result set as the first object in the response array.	query	integer

application/json

200 OK

Returns an array of CustomerCreditTransaction objects.

CustomerCreditTransaction

204 No Content

The request did not match any customer credit transactions and the response does not include a message body.

400 Bad Request

The client did not format the request properly. Check the error response message for details.

500 Internal Server Error

An unexpected server error occurred. Toast support staff can use the requestId value in the error message to help troubleshoot the problem.

Gets information about a specific customer credit transaction.

GET /creditTransactions/{transactionId}

Returns a CustomerCreditTransaction object containing information about a specific customer credit transaction.

Toast-Restaurant-External-ID	The Toast POS GUID of the restaurant.	header	string (string)
transactionId	The Toast POS GUID for the transaction.	path	string (string)

application/json

200 OK

Returns the credit transaction.

CustomerCreditTransaction

400 Bad Request

The client did not format the request properly. Check the error response message for details.

404 Not Found

The specified transaction was not found.

500 Internal Server Error

An unexpected server error occurred. Toast support staff can use the requestId value in the error message to help troubleshoot the problem.

Creates a new restaurant customer record.

POST /customers

Creates a new restaurant customer record in the Toast POS. A new customer record must include a firstName and a lastName value. It must include at least one of the phone and email values. You must include a unique identifier (GUID) in the Customer object.

Uses default content-types: application/json

A JSON Customer object containing information about the restaurant customer.

Customer

Toast-Restaurant-External-ID	The Toast POS GUID of the restaurant.	header	string (string)

application/json

200 OK

Returns the new customer record.

Customer

202 Accepted

The request has passed validation and is in progress. When the Toast POS processes the request, you can GET the customer from the /customers/{customerId} endpoint. You can also send another POST request to the /customers endpoint until you receive an HTTP 200 status response.

400 Bad Request

The client did not format the request properly. Check the error response message for details.

500 Internal Server Error

An unexpected server error occurred. Toast support staff can use the requestId value in the error message to help troubleshoot the problem.

Accepts a search query and retrieves information about restaurant guests who match the query value.

POST /customers/search

Returns an array of Customer objects containing information about restaurant guests who match the set of information that you provide in a search query.

Uses default content-types: application/json

A CustomerSearchRequest object containing information used to search for guests.

CustomerSearchRequest

Toast-Restaurant-External-ID	The Toast POS GUID of the restaurant.	header	string (string)
pageSize	The number of objects to return in the array. The default number is 20. The maximum number is 50.	query	integer
page	The result set sequence number (or offset) of the first object in the response array. By default, the endpoint returns the first object in the result set as the first object in the response array.	query	integer

application/json

200 OK

Returns an array of Customer objects that have information matching a search query.

Customer

204 No Content

The request did not match any guest records and the response does not include a message body.

400 Bad Request

The client did not format the request properly. Check the error response message for details.

500 Internal Server Error

An unexpected server error occurred. Toast support staff can use the requestId value in the error message to help troubleshoot the problem.

Gets information about a specific restaurant customer.

GET /customers/{customerId}

Returns a Customer object containing information about a specific restaurant customer.

Toast-Restaurant-External-ID	The Toast POS GUID of the restaurant.	header	string (string)
customerId	The Toast POS GUID of the restaurant customer.	path	string

application/json

200 OK

Returns information about the customer.

Customer

400 Bad Request

The client did not format the request properly. Check the error response message for details.

404 Not Found

The specified customer was not found.

500 Internal Server Error

An unexpected server error occurred. Toast support staff can use the requestId value in the error message to help troubleshoot the problem.

Gets information about the customer credits available to a restaurant customer.

GET /customers/{customerId}/creditSummary

Returns a CustomerCreditSummary object containing information about the customer credits available to a specific restaurant customer.

Toast-Restaurant-External-ID	The Toast POS GUID of the restaurant.	header	string (string)
customerId	The Toast POS GUID of the restaurant customer.	path	string

application/json

200 OK

Returns the CustomerCreditSummary.

CustomerCreditSummary

400 Bad Request

The client did not format the request properly. Check the error response message for details.

404 Not Found

The specified customer was not found.

500 Internal Server Error

An unexpected server error occurred. Toast support staff can use the requestId value in the error message to help troubleshoot the problem.

Gets information about customer credit transactions for a specific restaurant customer.

GET /customers/{customerId}/creditTransactions

Returns an array of CustomerTransaction objects for a specific restaurant customer. The array includes transactions for the customer at all restaurants in the loyalty set of restaurants that includes the restaurant you specify in the Toast-Restaurant-External-ID header parameter. The transactions in the response are ordered from newest to oldest.

Toast-Restaurant-External-ID	The Toast POS GUID of the restaurant.	header	string (string)
customerId	The Toast POS GUID for the customer that owns the transaction.	path	string
pageSize	The number of objects to return in the array. The default number is 20. The maximum number is 50.	query	integer
page	The result set sequence number (or offset) of the first object in the response array. By default, the endpoint returns the first object in the result set as the first object in the response array.	query	integer

application/json

200 OK

Returns an array of CustomerCreditTransaction objects that match all of the fields specified in the query.

CustomerCreditTransaction

204 No Content

The request did not match any customer credit transactions and the response does not include a message body.

400 Bad Request

The client did not format the request properly. Check the error response message for details.

404 Not Found

The specified customer was not found.

500 Internal Server Error

An unexpected server error occurred. Toast support staff can use the requestId value in the error message to help troubleshoot the problem.

Creates a customer credit transaction for a specific restaurant customer.

POST /customers/{customerId}/creditTransactions

Creates an ADD_VALUE type customer credit transaction for a specified customer.
The transactionType value in the CustomerCreditTransaction object that you include in the message body of the POST request must be ADD_VALUE. You must include a unique identifier (GUID) in the CustomerCreditTransaction object.

Uses default content-types: application/json

A CustomerCreditTransaction including information about the customer credit transaction.

CustomerCreditTransaction

Toast-Restaurant-External-ID	The Toast POS GUID of the restaurant.	header	string (string)
customerId	The Toast POS GUID for the customer.	path	string

application/json

200 OK

The customer credit transaction was created. Returns a CustomerCreditTransaction object.

CustomerCreditTransaction

400 Bad Request

The client did not format the request properly. Check the error response message for details.

404 Not Found

The specified customer was not found.

500 Internal Server Error

An unexpected server error occurred. Toast support staff can use the requestId value in the error message to help troubleshoot the problem.

Schema definitions

Campaign: object

Information on a specific marketing campaign to reach customers. Internal use only.

status: string , x ∈ { ACTIVE , INACTIVE }

Status of the campaign

name: string

Name of the campaign

guid: string (uuid)

A unique identifier of this campaign

managementSetGuid: string (uuid)

The UUID of the management set that this restaurant belongs to. If the restaurant has no management set, this is the UUID of the restaurant set leaf.

restaurantGuid: string (uuid)

The UUID of the restaurant from which the campaign originates.

lastActivatedDate: string (date-time)

The last time this campaign was executed

unsubscribeLink: string

URI that the guest has to go to in order to unsubscribe from receiving future emails from a given restaurant group. e.g. https://www.toasttab.com/toast-tab-grill/unsubscribe

promoCode: string

The promo code associated with the campaign, that the guest can use to receive a discount or other promotional item (Optional)

Customer:

Information about a restaurant customer. For a POST request, you must include a unique identifier (GUID) in the Customer object.

ToastReference

firstName: string

The first or given name of the customer.

lastName: string

The last or family name of the customer.

phone: string

A telephone number for the customer. You must set either phone or email for a POST request. You can set both phone and email.

email: string

An email address for the customer. You must set either phone or email for a POST request. You can set both phone and email.

CustomerCreditSummary: object

Information about the customer credits that restaurants have given to a customer.

amount: number (double)

The total currency amount of the credits available to a customer.

earliestExpirationDate: string (date-time)

The earliest expiration date of the customer credits available to a customer. This value is null if the customer has no unexpired credits.

CustomerCreditTransaction:

Information about transactions that add value to, redeem value, or update the customer credits for a customer. For a POST request, you must include a unique identifier (GUID) in the guid value of the CustomerCreditTransaction object.

ToastReference

amount: number (double)

The currency amount of a customer credit transaction.

transactionType: string , x ∈ { ADD_VALUE , VOID_ADD_VALUE , EXPIRATION , REDEMPTION , VOID_REDEMPTION }

The type of transaction. The EXPIRATION transaction type is response only.

transactionDate: string (date-time)

The original date of the transaction at the time it was created in the Toast POS. Response only.

localCreatedDate: string (date-time)

The local date and time of the transaction. If the transaction occurred on a Toast POS device, this is the local date and time for the device. Required.

expirationDate: string (date-time)

The date and time that a new customer credit amount will expire. Present only when the transaction type is ADD_VALUE. Response only.

note: string

The reason that a restaurant employee entered to explain the transaction.

server: ToastReference

The Toast POS GUID or external identifier of the restaurant employee who created the transaction. Response only.

approver: ToastReference

The Toast POS GUID or external identifier of the restaurant employee who approved this transaction. For example, a restaurant manager might approve a customer credit transaction for an employee who does not have the permission to add customer credit value for a customer. Response only.

restaurant: ToastReference

The Toast POS GUID or external identifier of the restaurant where this transaction occurred. For a POST request, the GUID must match the restaurant guid in the Toast-Restaurant-External-ID header parameter. Response only.

device: ToastReference

The Toast POS GUID or external identifier of the POS device that was used to create this transaction.

customer: ToastReference

The Toast POS GUID or external identifier of the customer associated with this transaction. Response only.

familyGuid: string (uuid)

For void transactions, this is the Toast POS GUID of the transaction to be voided. Required if the transactionType value is VOID_REDEMPTION. Response only for all other transaction types.

CustomerEmailSearchQuery: object

For internal use only.

emailAddresses: string[]

For internal use only.

string

CustomerSearchQuery: object

Information about a customer that the CRM API uses to search for matching customer records.

firstName: string

The first or given name of the customer.

lastName: string

The last or family name of the customer.

email: string

An email address for the customer.

phone: string

A telephone number for the customer.

CustomerSearchRequest: object

Information about an attempt to search for restaurant customer records. This information includes a CustomerSearchQuery object containing information about the customer who is the object of the search.

query: CustomerSearchQuery

A CustomerSearchQuery object containing information about a customer that the Toast POS uses to match against existing customer records.

ToastReference: object

A wrapper object with fields that allow reference to a Toast POS entity by Toast GUID.

guid: string (uuid)

The GUID maintained by the Toast POS.

entityType: string

The type of object.