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.
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
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.
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.
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
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 anotherPOST
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.
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.
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.
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.
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.
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
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)
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
oremail
for aPOST
request. You can set bothphone
andemail
. - email: string
-
An email address for the customer. You must set either
phone
oremail
for aPOST
request. You can set bothphone
andemail
.
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.
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 isVOID_REDEMPTION
. Response only for all other transaction types.
For internal use only.
- emailAddresses: string[]
-
For internal use only.
string
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.
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.