Introduction
The Fresh Technology Integrations API allows for outside parties to send and pull data from the Fresh Technology systems.
Setup
To integrate with Fresh KDS please contact partnerships@freshtechnology.com to discuss your integration and next steps.
Getting Started
Contact Fresh and request access to our sandbox environment.Login using the provided credentials.From the home page click Settings > Integration tokensGenerate a new token
Production
If you are creating an integration for your own use, the above steps will need to be repeated on the Fresh production environment. If your integration is intended to be used by your customers, the customer will need to follow the steps above on their Fresh account and supply you with the integration token. Tokens are assigned at the account level and will be unique per customer.
The Integration token will be required for all calls to the Integrations API, if the token is not valid, or has been revoked, the request will fail with a 401 (Unauthorized).
Overview
Be sure to check the HTTP syntax to see what headers are required to be sent. Some routes require different headers, however all requests will require the integration token to be sent.
| Environment | URL |
|---|---|
| sandbox | https://sandbox-integrations-api.ftservices.cloud |
| production | https://integrations-api.ftservices.cloud |
Authorization
Every request on the Integrations API requires 1 header sent.
x-integration-token: {token}
KDS Cloud Overview
KDS Cloud allows for outside integrations to send orders to be displayed on FreshKDS screens. Through the use of KDS Cloud, orders can be sent from any third party system whether on premise or cloud based with the granular control over which screen(s) will receive the orders.
KDS Cloud Information
Get KDS Information
GET /integrators/kds-information HTTP/1.1
https://sandbox-integrations-api.ftservices.cloud
x-integration-token: pUiVhtLDbqmYG312IEJ0UDcjhWXhivXKiZxwoNWBJPeFTDCaZHs7UQgoVKtFLeCt6sJ572WD0Xnh10l2baOiph
HTTP/1.1 200 OK
content-type: application/json
[
{
"id": "81db5db1-b5af-4e45-8767-71fb78e29bdb",
"number": "123456",
"name": "Test Location Fresh",
"address": {
"zip": "12345",
"city": "Any Town",
"line1": "123 Test Lane",
"line2": null,
"state": "NV"
},
"timezone": "US/Pacific",
"devices": [
{
"id": "ef837416-c674-40ab-9aa3-eb0f202e8646",
"name": "Device 1"
}
]
}
]
GET /integrators/kds-information
Get KDS Locations
GET /integrators/kds-information/locations HTTP/1.1
https://sandbox-integrations-api.ftservices.cloud
x-integration-token: pUiVhtLDbqmYG312IEJ0UDcjhWXhivXKiZxwoNWBJPeFTDCaZHs7UQgoVKtFLeCt6sJ572WD0Xnh10l2baOiph
HTTP/1.1 200 OK
content-type: application/json
[
{
"id": "81db5db1-b5af-4e45-8767-71fb78e29bdb",
"number": "123456",
"name": "Test Location Fresh",
"address": {
"zip": "12345",
"city": "Any Town",
"line1": "123 Test Lane",
"line2": null,
"state": "NV"
},
"timezone": "US/Pacific"
}
]
GET /integrators/kds-information/locations
Get KDS Location Devices
GET /integrators/kds-information/locations/81db5db1-b5af-4e45-8767-71fb78e29bdb/devices HTTP/1.1
https://sandbox-integrations-api.ftservices.cloud
x-integration-token: pUiVhtLDbqmYG312IEJ0UDcjhWXhivXKiZxwoNWBJPeFTDCaZHs7UQgoVKtFLeCt6sJ572WD0Xnh10l2baOiph
HTTP/1.1 200 OK
content-type: application/json
[
{
"id": "ef837416-c674-40ab-9aa3-eb0f202e8646",
"name": "Device 1"
}
]
GET /integrators/kds-information/locations/{locationId}/devices
KDS Cloud Orders
Get KDS Active Orders
GET /integrators/kds-orders/active HTTP/1.1
host: https://sandbox-integrations-api.ftservices.cloud
x-integration-token: 1234567890
x-location-id: 5fcbcc8c-d637-4d91-a576-9de31ffe7a3d
x-device-ids: 319fb5bc-6189-4dc6-a1e0-42dbf36177e9 (Comma delimited for multiple devices, value of 'all' for all active devices at location)
HTTP/1.1 200 OK
content-type: application/json
[
{
"deviceId": "49d0d0a9-e7a8-438c-9e14-e26198e637df",
"deviceName": "Device 2",
"orderCount": 2,
"orders": [
{
"orderId": "223456789",
"orderName": "2 Test Order"
},
{
"orderId": "323456789",
"orderName": "2 Test Order 2"
}
]
},
{
"deviceId": "74b6041f-c095-47b9-ba4f-340b89142935",
"deviceName": "Device 3",
"orderCount": 1,
"orders": [
{
"orderId": "423456789",
"orderName": "3 Test Order"
}
]
}
]
Returns array of requested (all) devices with the orders active and on screen for those devices
GET /integrators/kds-orders/active
Send KDS Order
POST /integrators/kds-orders HTTP/1.1
host: https://sandbox-integrations-api.ftservices.cloud
x-integration-token: 1234567890
x-location-id: 5fcbcc8c-d637-4d91-a576-9de31ffe7a3d
x-device-ids: 319fb5bc-6189-4dc6-a1e0-42dbf36177e9 (Comma delimited for multiple devices, value of 'all' for all active devices at location)
HTTP/1.1 200 OK
content-type: application/json
{
"orderId" : "d2874775-34e2-4829-8b59-1260e40eca4e",
"deliveryStatuses": [
{
"device": "e1675528-aba9-4b97-8482-a72380870fd5",
"status": "success"
}
]
}
POST /integrators/kds-orders
Additional Headers
x-location-id: {locationId}x-device-ids: {Comma delimited for multiple devices, value of 'all' for all active devices at location}
Body Parameters
KDS Order
| Property | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Integration order id |
| name | yes | string | Order Name/Number |
| time | yes | date | Order Date/Time, ISO 8601 Format |
| pickupTime | no | date | Pickup Date/Time, ISO 8601 Format |
| phoneNumber | no | string | Phone number to contact regarding order |
| optInForSms | no | bool | If a phone number is supplied and KDS is configured to send SMS messages, provides an option to send a SMS or not for this order. NOTE: If this property is not sent, default is true |
| deliveryAddress | no | string | If order is for delivery, can supply and address for display |
| mode | yes | string | Order Mode (For Here, ToGo, Pickup, DriveThru, Delivery, CurbSide) note: if invalid order mode, mode will be added to order name |
| server | no | string | Server Name |
| source | no | string | Identifier of Integrator. This is for partner integrations with KDS and value to send must be supplied by Fresh Technology. Current accepted values are null or togotechnology. |
| items | yes | KdsItem[] | Items |
| terminal | yes | string | Pos Terminal |
| specialInstructions | no | string | Text based special instructions that will be displayed on the order. Newlines can be inserted with '\n' |
| customerArrivedUrl | no | url | If SMS Bolt-On enabled and this value is supplied. This link will be included with the SMS for Order Received and Order Ready for Pickup. This URL should route to integrators system to send the Customer Arrived Notification to KDS |
| vehicleModel | no | string | Car Model |
| vehicleColor | no | string | Car Color |
| retry | no | object | If specified devices are not connected when the order is sent. Values in this object are used for notification and expiration |
| costs | no | Costs | Object that contains costs associated with the order |
| deliveryService | no | DeliveryService | Object contains information regarding the order if a delivery service is being used |
| accessibility | no | Accessibility | Object contains information regarding accessibility (ADA) neededs |
| originSource | no | string | If the order is coming from certain third parties, this can be reflected with this option. Current accepted values: (UBEREATS, GRUBHUB, DOORDASH). Note: Invalid sources will be ignored. |
KDS Item
| Property | Required | Type | Description |
|---|---|---|---|
| id | no | string | Item Id |
| lineId | no | string | Id of item on order, used to update a particular order item |
| name | yes | string | Item Name |
| qty | yes | int | Quantity |
| price | no | string | Cost of item, value should be a string and can include the currency symbol or not |
| mods | yes | Modifier[] | Item Modifiers, empty array if none |
| components | no | Components[] | Array of Components that make up the item, will be leveraged in the KDS All Day View |
| specialInstructions | no | string | Text based special instructions that will be displayed on the item |
Modifier
| Property | Required | Type | Description |
|---|---|---|---|
| id | no | string | Id of modifier |
| name | yes | string | Name of the modifier |
| components | no | Components[] | Array of Components that make up the item, will be leveraged in the KDS All Day View |
NOTE: Previously Mods was a string[], still supported for backwards compatibility
Retry
| Property | Required | Type | Description |
|---|---|---|---|
| notificationUrl | no | string | URL to POST final success or failure either upon success or expiration |
| expiration | no | date | ISO 8601 Format date when retrys should no longer be attempted. If not supplied, value of 2 minutes from submission time will be used |
NOTE: Order responds will include an array of device id's and status of delivery to the device. If a retry object is specified, KDS Cloud will attempt to deliver until the expiration time. If no expiration time is specified, retry will attempt for 2 minutes.
Notification POST Data
If a notificationUrl is provided, when either all deliveries are successful, or the order delivery has expired, a POST will be made to the supplied url
HTTP/1.1 200 OK
content-type: application/json
{
"orderId": "3cd27748-741e-4784-9cb8-abcd01285670",
"finalStatus": "all-delivered",
"deliveryStatuses": [
{
"device": "e1675528-aba9-4b97-8482-a72380870fd5",
"status": "success"
}
]
}
HTTP/1.1 200 OK
content-type: application/json
{
"orderId": "3cd27748-741e-4784-9cb8-abcd01285670",
"finalStatus": "order-retry-expired",
"deliveryStatuses": [
{
"device": "e1675528-aba9-4b97-8482-a72380870fd5",
"status": "kds-not-connected"
}
]
}
Costs
| Property | Required | Type | Description |
|---|---|---|---|
| subtotal | no | string | Sub total of the order |
| tax | no | string | Tax on the order |
| deliveryFee | no | string | Delivery Fee for the order |
| surcharge | no | string | Surcharge for the order |
| convenienceFee | no | string | Convenience Fee for the order |
| tip | no | string | Tip on the order |
| additionalFees | no | additionalFees[] | Additional / Custom Fees |
| total | no | string | Total for the order |
| promoCodes | no | promoCodes[] | Promo codes for the order |
Additional Fees
| Property | Required | Type | Description |
|---|---|---|---|
| name | yes | string | Name of the fee |
| amount | yes | string | Amount of the fee |
Promo Codes
| Property | Required | Type | Description |
|---|---|---|---|
| name | no | string | Name of the promo code |
| amount | yes | string | Amount of Promo Code, value should be a string and can include the currenty symbol or not |
Components
| Property | Required | Type | Description |
|---|---|---|---|
| name | yes | string | Name of the component |
| count | yes | int | Count of the component on the item |
Delivery Service
| Property | Required | Type | Description |
|---|---|---|---|
| name | yes | string | Name of the delivery service |
| orderId | yes | string | Delivery Service order Id |
| driverPhone | no | string | Phone number of the delivery driver |
Accessibility
| Property | Required | Type | Description |
|---|---|---|---|
| wheelChairAccess | yes | bool | This value will be sent along to supported integrations (Apex Lockers) |
Update KDS Order
PUT /integrators/kds-orders HTTP/1.1
host: https://sandbox-integrations-api.ftservices.cloud
x-integration-token: 1234567890
x-location-id: 5fcbcc8c-d637-4d91-a576-9de31ffe7a3d
x-device-ids: 319fb5bc-6189-4dc6-a1e0-42dbf36177e9 (Comma delimited for multiple devices, value of 'all' for all active devices at location)
HTTP/1.1 200 OK
content-type: application/json
{
"orderId" : "d2874775-34e2-4829-8b59-1260e40eca4e",
"deliveryStatuses": [
{
"device": "e1675528-aba9-4b97-8482-a72380870fd5",
"status": "success"
}
]
}
PUT /integrators/kds-orders
Additional Headers
x-location-id: {locationId}x-device-ids: {Comma delimited for multiple devices, value of 'all' for all active devices at location}
Body Parameters
All properties are optional other than the ID. Null or unsupplied properties will be ignored.
KDS Order
| Property | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Integration order id |
| source | no | string | Identifier of Integrator. This is for partner integrations with KDS and value to send must be supplied by Fresh Technology. Current accepted values are null or togotechnology. |
| name | no | string | Order Name/Number |
| pickupTime | no | date | Pickup Date/Time, ISO 8601 Format |
| phoneNumber | no | string | Phone number to contact regarding order |
| optInForSms | no | bool | If a phone number is supplied and KDS is configured to send SMS messages, provides an option to send a SMS or not for this order. NOTE: If this property is not sent, default is true |
| deliveryAddress | no | string | If order is for delivery, can supply and address for display |
| mode | no | string | Order Mode (For Here, ToGo, Pickup, DriveThru, Delivery, CurbSide) note: if invalid order mode, mode will be added to order name |
| server | no | string | Server Name |
| items | no | KdsItem[] | Items. Note, items added to this will be added to the order sent to update |
| specialInstructions | no | string | Text based special instructions that will be displayed on the order. Newlines can be inserted with '\n' |
| customerArrivedUrl | no | url | If SMS Bolt-On enabled and this value is supplied. This link will be included with the SMS for Order Received and Order Ready for Pickup. This URL should route to integrators system to send the Customer Arrived Notification to KDS |
| vehicleModel | no | string | Car Model |
| vehicleColor | no | string | Car Color |
| retry | no | object | If specified devices are not connected when the order is sent. Values in this object are used for notification and expiration |
| costs | no | Costs | Object that contains costs associated with the order |
| deliveryService | no | DeliveryService | Object contains information regarding the order if a delivery service is being used |
| accessibility | no | Accessibility | Object contains information regarding accessibility (ADA) neededs |
KDS Item
| Property | Required | Type | Description |
|---|---|---|---|
| id | no | string | Item Id |
| lineId | no | string | Id of item on order, used to update a particular order item |
| name | yes | string | Item Name |
| qty | yes | int | Quantity |
| price | no | string | Cost of item, value should be a string and can include the currency symbol or not |
| mods | yes | string[] | Item Modifiers, empty array if none |
| components | no | Components[] | Array of Components that make up the item, will be leveraged in the KDS All Day View |
| specialInstructions | no | string | Text based special instructions that will be displayed on the item |
Retry
| Property | Required | Type | Description |
|---|---|---|---|
| notificationUrl | no | string | URL to POST final success or failure either upon success or expiration |
| expiration | no | date | ISO 8601 Format date when retrys should no longer be attempted. If not supplied, value of 2 minutes from submission time will be used |
NOTE: Order responds will include an array of device id's and status of delivery to the device. If a retry object is specified, KDS Cloud will attempt to deliver until the expiration time. If no expiration time is specified, retry will attempt for 2 minutes.
Notification POST Data
If a notificationUrl is provided, when either all deliveries are successful, or the order delivery has expired, a POST will be made to the supplied url
HTTP/1.1 200 OK
content-type: application/json
{
"orderId": "3cd27748-741e-4784-9cb8-abcd01285670",
"finalStatus": "all-delivered",
"deliveryStatuses": [
{
"device": "e1675528-aba9-4b97-8482-a72380870fd5",
"status": "success"
}
]
}
HTTP/1.1 200 OK
content-type: application/json
{
"orderId": "3cd27748-741e-4784-9cb8-abcd01285670",
"finalStatus": "order-retry-expired",
"deliveryStatuses": [
{
"device": "e1675528-aba9-4b97-8482-a72380870fd5",
"status": "kds-not-connected"
}
]
}
Costs
| Property | Required | Type | Description |
|---|---|---|---|
| subtotal | no | string | Sub total of the order |
| tax | no | string | Tax on the order |
| deliveryFee | no | string | Delivery Fee for the order |
| surcharge | no | string | Surcharge for the order |
| convenienceFee | no | string | Convenience Fee for the order |
| tip | no | string | Tip on the order |
| additionalFees | no | additionalFees[] | Additional / Custom Fees |
| total | no | string | Total for the order |
| promoCodes | no | promoCodes[] | Promo codes for the order |
Additional Fees
| Property | Required | Type | Description |
|---|---|---|---|
| name | yes | string | Name of the fee |
| amount | yes | string | Amount of the fee |
Promo Codes
| Property | Required | Type | Description |
|---|---|---|---|
| name | no | string | Name of the promo code |
| amount | yes | string | Amount of Promo Code, value should be a string and can include the currenty symbol or not |
Components
| Property | Required | Type | Description |
|---|---|---|---|
| name | yes | string | Name of the component |
| count | yes | int | Count of the component on the item |
Delivery Service
| Property | Required | Type | Description |
|---|---|---|---|
| name | yes | string | Name of the delivery service |
| orderId | yes | string | Delivery Service order Id |
| driverPhone | no | string | Phone number of the delivery driver |
Accessibility
| Property | Required | Type | Description |
|---|---|---|---|
| wheelChairAccess | yes | bool | This value will be sent along to supported integrations (Apex Lockers) |
KDS Cloud Notifications
Send KDS Customer Arrived Notification
KDS has a robust Takeout Management section as well as the standard Kitchen Display. If a customer has enabled that view, any order type they have configured to display there will for fulfillment. Through KDS Cloud, a signal can be sent to the KDS to notify the Takeout Management screen that a customer has arrived.
POST /integrators/kds-notifications/customer-arrived HTTP/1.1
host: https://sandbox-integrations-api.ftservices.cloud
x-integration-token: 1234567890
x-location-id: 5fcbcc8c-d637-4d91-a576-9de31ffe7a3d
x-device-ids: 319fb5bc-6189-4dc6-a1e0-42dbf36177e9 (Comma delimited for multiple devices, value of 'all' for all active devices at location)
HTTP/1.1 200 OK
content-type: application/json
{
"orderId" : "d2874775-34e2-4829-8b59-1260e40eca4e",
"deliveryStatuses": [
{
"device": "e1675528-aba9-4b97-8482-a72380870fd5",
"status": "success"
}
]
}
POST /integrators/kds-notifications/customer-arrived
Additional Headers
x-location-id: {locationId}x-device-ids: {Comma delimited for multiple devices, value of 'all' for all active devices at location}
Body Parameters
| Property | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Integration order id. This is the orderId that was returned when submitting the order through KDS Cloud |
| source | no | string | Identifier of Integrator. This is for partner integrations with KDS and value to send must be supplied by Fresh Technology. Should not be supplied in most cases. |
| retry | no | object | If specified devices are not connected when the order is sent. Values in this object are used for notification and expiration |
Retry
| Property | Required | Type | Description |
|---|---|---|---|
| notificationUrl | no | string | URL to POST final success or failure either upon success or expiration |
| expiration | no | date | ISO 8601 Format date when retrys should no longer be attempted. If not supplied, value of 2 minutes from submission time will be used |
NOTE: Order responds will include an array of device id's and status of delivery to the device. If a retry object is specified, KDS Cloud will attempt to deliver until the expiration time. If no expiration time is specified, retry will attempt for 2 minutes.
Notification POST Data
If a notificationUrl is provided, when either all deliveries are successful, or the order delivery has expired, a POST will be made to the supplied url
HTTP/1.1 200 OK
content-type: application/json
{
"orderId": "3cd27748-741e-4784-9cb8-abcd01285670",
"finalStatus": "all-delivered",
"deliveryStatuses": [
{
"device": "e1675528-aba9-4b97-8482-a72380870fd5",
"status": "success"
}
]
}
HTTP/1.1 200 OK
content-type: application/json
{
"orderId": "3cd27748-741e-4784-9cb8-abcd01285670",
"finalStatus": "order-retry-expired",
"deliveryStatuses": [
{
"device": "e1675528-aba9-4b97-8482-a72380870fd5",
"status": "kds-not-connected"
}
]
}
Send KDS Estimated Arrival Update
KDS has a robust Takeout Management section as well as the standard Kitchen Display. If a customer has enabled that view, any order type they have configured to display there will for fulfillment. Through KDS Cloud, you are able to send an update of estimated arrival time for an order displayed on the Takeout Management section. An example being tracking a delivery driver or customer coming into the restaurant to get the order and allowing the kitchen staff visibility into when the order needs to be ready.
POST /integrators/kds-notifications/estimated-arrival-update' HTTP/1.1
host: https://sandbox-integrations-api.ftservices.cloud
x-integration-token: 1234567890
x-location-id: 5fcbcc8c-d637-4d91-a576-9de31ffe7a3d
x-device-ids: 319fb5bc-6189-4dc6-a1e0-42dbf36177e9 (Comma delimited for multiple devices, value of 'all' for all active devices at location)
HTTP/1.1 200 OK
content-type: application/json
{
"orderId" : "d2874775-34e2-4829-8b59-1260e40eca4e",
"deliveryStatuses": [
{
"device": "e1675528-aba9-4b97-8482-a72380870fd5",
"status": "success"
}
]
}
POST /integrators/kds-notifications/estimated-arrival-update
Additional Headers
x-location-id: {locationId}x-device-ids: {Comma delimited for multiple devices, value of 'all' for all active devices at location}
Body Parameters
| Property | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Integration order id. This is the orderId that was returned when submitting the order through KDS Cloud |
| minutes | yes | int | Minutes estimated till arrival |
| source | no | string | Identifier of Integrator. This is for partner integrations with KDS and value to send must be supplied by Fresh Technology. Should not be supplied in most cases. |
| retry | no | object | If specified devices are not connected when the order is sent. Values in this object are used for notification and expiration |
Retry
| Property | Required | Type | Description |
|---|---|---|---|
| notificationUrl | no | string | URL to POST final success or failure either upon success or expiration |
| expiration | no | date | ISO 8601 Format date when retrys should no longer be attempted. If not supplied, value of 2 minutes from submission time will be used |
NOTE: Order responds will include an array of device id's and status of delivery to the device. If a retry object is specified, KDS Cloud will attempt to deliver until the expiration time. If no expiration time is specified, retry will attempt for 2 minutes.
Notification POST Data
If a notificationUrl is provided, when either all deliveries are successful, or the order delivery has expired, a POST will be made to the supplied url
HTTP/1.1 200 OK
content-type: application/json
{
"orderId": "3cd27748-741e-4784-9cb8-abcd01285670",
"finalStatus": "all-delivered",
"deliveryStatuses": [
{
"device": "e1675528-aba9-4b97-8482-a72380870fd5",
"status": "success"
}
]
}
HTTP/1.1 200 OK
content-type: application/json
{
"orderId": "3cd27748-741e-4784-9cb8-abcd01285670",
"finalStatus": "order-retry-expired",
"deliveryStatuses": [
{
"device": "e1675528-aba9-4b97-8482-a72380870fd5",
"status": "kds-not-connected"
}
]
}
Send Message to KDS
Will send a message that will be displayed on the KDS screen.
POST /integrators/kds-notifications/send-message HTTP/1.1
host: https://sandbox-integrations-api.ftservices.cloud
x-integration-token: 1234567890
x-location-id: 5fcbcc8c-d637-4d91-a576-9de31ffe7a3d
x-device-ids: 319fb5bc-6189-4dc6-a1e0-42dbf36177e9 (Comma delimited for multiple devices, value of 'all' for all active devices at location)
HTTP/1.1 200 OK
content-type: application/json
{}
POST /integrators/kds-notifications/send-message
Additional Headers
x-location-id: {locationId}x-device-ids: {Comma delimited for multiple devices, value of 'all' for all active devices at location}
Body Parameters
| Property | Required | Type | Description |
|---|---|---|---|
| message | yes | string | Message to send |