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.

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.

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.

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.

Toast-Restaurant-External-ID

The Toast POS GUID of the restaurant.

header string (string)

application/json

200 OK

Returns the new customer record.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.