Introduction
This specification defines the version one (V1) Representational State Transfer (REST) Web service Application Programming Interface (API) that provides system access to core operational and administrative functions of the Benbria Loop® hosted software platform.
Note: This V1 API is targeted at specific integration stories.
The Loop V1 API is inbound only as depicted in the diagram below:
Loop v1 REST API
Authentication
All endpoints in this API require the client to be authenticated. An authentication token will be provided to you by Benbria. This token must be passed from client to server in each HTTP request as a query parameter, for example, a GET to:
https://sunnyclear.blazeloop.net/api/v1/locations?authToken=OldtbksdhMus2qgApdnb
would return a list of locations for the sunnyclear account.
Create a Loop
Create a loop for a given location. The result of the call will be JSON containing a unique identifier for the loop, and a URL to view the loop within a browser client.
The request body shall be a JSON object containing the following fields (except for version which is in the URL):
version - API version, currently v1
source - A type description of the origin of the Loop (e.g., “kiosk”, “mobile”, “smart-clock”, etc.). For example, a Loop originating from an in-hotel kiosk should be marked as “kiosk”, or Loops created from a customer’s smartphone (or other user-owned devices) as “mobile”.
deviceId - (optional) A unique identifier (ID) or a human-friendly name of the current device (originates from your system).
Note: Useful, primarily, for troubleshooting misconfigured devices, but could be used as a fallback when other information is missing (e.g., location or room).
location - The unique identifier (ID) for the (e.g., hotel, store, restaurant) location from our system.
Use the GET /locations API to retrieve a list of locations, or GET /locations/<shortcode> to lookup based on the human-friendly shortcode configured for the location (e.g., 1234, 1125).
Note: We store both short code and ID for each location. Short codes are used for convenience mainly during registration and as a URL parameter (e.g., to give customers a link with the location pre-selected). It is often a value assigned by the account organization (e.g., a store number identifying the location), as a result, the value can potentially change (be assigned a different number). However, the ID of a Location is immutable. Ideally, you will look up the location ID once when registering/configuring the device, and store it on the device.
loopType - The unique identifier for the type of loop being created.
Use GET /looptypes for a listing of loop types configured for the account. You will have to decide the type for each loop based on the semantics.
Note: Loop types are shared across all locations, and are unlikely to change once an account is configured.
customFields - (optional) An array of additional fields stored as key-value pairs ({<key>:<value>}). These are fields customized to a particular account. For example, the room number.
The key is the ID of the custom field. Use GET /customfields or GET /customfields/<shortcode> to lookup configured fields, where shortcode is a human-friendly string used to identify the specific custom field configured for the account. Value is a free-form string value.
Note: Ideally, a device, used to generate loops, that is a fixture in a room, should be configured to store a room number value, and its corresponding custom field ID, such that it can submit this field during creation of a Loop.
title - (optional) A short descriptive summary of the Loop.
description - The Loop message text contents.
timestamp - (optional; Loop assigns the timestamp if not provided) A RFC2822 or ISO 8601 date string representing the time the Loop was created.
user - (optional) A {name, email, sms} object with information about the user. This will be used to create a new guest user, or will link this loop to an existing guest user account if a guest already exists with the specified email address or sms number. All values are strings, and all are optional. This value will be ignored if customer is provided.
customer - (optional) The id of the user that will be set as the creator of this loop. An anonymous user will be set as the creator if not provided.
Create a Loop: Example
Sample Response
Lookup Loops Created by a Customer
Lookup all loops for a given user account, returns JSON containing list of a customer’s loops:
Loop Lookup: Example
$ curl -i -X GET https://sunnyclear.blazeloop.com/api/v1/loops?customer=57276b281bb438711ab4f1e4&authToken=xxxx
Sample Response:
{
"loops": [
{
"id": "57276b281bb438711ab4f1e5",
"description": "I've run out of towels! Please help!",
"summary": "300 Earl Grey Dr",
"state": "open",
"creatorId": "57276b281bb438711ab4f1e4",
"creatorLoopCount": 1,
"contactable": true,
"unread": false,
"activities": [
{
"id": "57276b281bb438711ab4f1e6",
"type": "open",
"date": 1462201128650,
"data": {
"date": 1462201128649,
"sms": "+16135551234",
"description": "I've run out of towels! Please help!"
},
"loop": "57276b281bb438711ab4f1e5",
"system": false,
"automated": false,
"confirmed": true,
"person": {
"name": "Jason",
"type": "customer",
"id": "57276b281bb438711ab4f1e4"
}
}
],
"loopMedium": "sms",
"createDevice": "browser:Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/50.0.2661.86 Safari\/537.36",
"created_on": 1462201128558,
"updated_on": 1462201128650,
"lastViewed": 1462201136577,
"location": {
"id": "571a2c54dffdba13dec03713",
"title": "300 Earl Grey Dr",
"timezone": "America\/Toronto",
"geo": [
-75.9154844,
45.311854
],
"country": "CA",
"state": "ON",
"city": "Kanata",
"zipCode": "K2T 1B8",
"street_name": "Earl Grey Dr",
"street_number": "300"
}
}
]
}Locations
Retrieve listing of configured locations for the account.
Retrieve a specific location by its shortcode.
Locations: Example
Sample Response
{
"locations": [
{
"id":"529652b0121d5fa206011a97",
"shortcode":"1300",
"title":{
"en":"Andros Island Bahamas"
},
"coords": {
"latitude": 45.349429,
"longitude": -75.9248028
}
},
{
"id":"529652b0121d5fa206011a98",
"shortcode":"1200",
"title":{
"en":"Costa Rica Salinas Bay"
}
}
]
}Retrieving Specific Location: Example
Sample Response
<> Loop Types
Retrieve listing of configured loop types for the account.
Loop Types: Example
Sample Response
Custom Fields
Retrieve listing of configured custom fields for the account.
Retrieve a specific custom field by shortcode.
Custom Fields: Example
Sample Response
{
"id":"529652b0121d5fa206011a97",
"shortcode":"room",
"title":{"en":"Room Number"},
"required":true
}Create Employee User Account
Create a user account for an employee providing username, contact information, permissions and locations this user is subscribed to. The result of the call will be JSON containing a unique identifier for the user account:
Lookup User
Look up an employee or guest user account, the result of the call will be JSON containing a list of user account objects matching the query parameter ( usually one, but could be multiple, if multiple user accounts have the same email or cell phone number):
GET /api/<version>/users/?username=<username>
GET /api/<version>/users/?email=<email>
GET /api/<version>/users/?sms=<sms>
Use query parameters “username”, “email” and “sms” to lookup by username, email address and cell phone number, respectively.
Users Lookup: Example
$ curl -i -X GET \
https://benbria.blazeloop.net/api/v1/users/?authToken=xxxx&sms=”5556135555”
Sample Response
{
"users": [
{
"username":"benria",
"name":"Benbria Admin",
"id":"4fc7769576ca50ce2c000012",
"permissions":["create", "comment", "close"],
"locations":[],
"sms":"5556135555",
"email":"admin@benbria.com"
},
{
"username":"benria2",
"name":"Benbria Admin",
"id":"5c87769576ca50ce2c987659",
"permissions":[],
"locations":[],
"sms":"5556135555",
"email":""
}
]
}Generate Invite URL
Generates a guest profile in Loop and a personalized URL to be used to invite that guest to Loop. Behind the scenes, this either recycles an existing user object (guest profile) or creates a new one with the updated guest information. This API call will not trigger an invitation email or SMS to the user automatically.
If none of name, email, or sms are provided, no user will be created, but a generic invite URL will still be created.
Note that if a user already exists in the system with the specified email or sms, the existing user object will be used instead of creating a new user object. In this case, any custom field values supplied will overwrite existing values in the user object.
Generate Invite URL: Example
$ curl -i -X POST -HContent-type:application/json --data '{
"locationId":"529652b0121d5fa206011a79",
"name":"John Smith",
"email":"johnsmith@benbria.com"
}' https://sunnyclear.blazeloop.net/api/v1/invite/url?authToken=xxxxSample Response
{
"guestId": "4fc7769576ca50ce2c000012",
"url": "https://sunnyclear.blazeloop.net/loop/create/1234?_uid=4fc7769576ca50ce2c000012"
}Surveys
Retrieve listing of configured surveys for the account.
Note that “description” is only returned for ops and superadmin users.
Retrieve a specific survey by its shortcode.
Retrieve the specific survey for a location.
Surveys: Example
$ curl -i -X GET \
https://sunnyclear.blazeloop.net/api/v1/surveys?authToken=xxxx
Sample Response
{
"surveys": [
{
"id":"529652b0131d5fa206011a98",
"shortCode":"restaurant",
"questions":[
{
"categoryId": "529652b0131d5fa206011a99",
"type": "bool",
"text": {"en": "Was the service swift?"}
},
{
"categoryId": "529652b0131d5fa206011a9a",
"type": "bool",
"text": {"en": "Was the food fantastic?"}
},
{
"categoryId": "529652b0131d5fa206011a9b",
"type": "bool",
"text": {"en": "Was the counter clean?"}
},
{
"categoryId": "529652b0131d5fa206011a9c",
"type": "text",
"text": {"en": "What else should we know?"},
"placeholder": {"en": "Type here!"}
}
],
"questionOrderRandomization": true
}
]
}Retrieving By Location: Example
$ curl -v -i -X GET \
"https://sunnyclear.blazeloop.net/api/v1/surveys"\
"?location=1300&authToken=xxxx"
Sample Response
{
surveys: [{
"id":"529652b0131d5fa206011a98",
"shortcode":"restaurant",
"description":"Survey for sit-down restaurant locations",
"questions":[...],
"questionOrderRandomized": true
}]
}Create a Response
Create a response for a given location and survey. The result of the call will be JSON containing a unique identifier for the response. Depending on account settings, creating a Response may implicitly create a Loop as well; in this case a “loopId” and “loopUrl” will be returned.
The request body shall be a JSON object containing the following fields (except for version which is in the URL):
Create a Response: Example
$ curl -i -X POST -HContent-type:application/json --data '{
"source":"kiosk",
"deviceId":"Front Desk Station 2",
"location":"529652b0121d5fa206011a79",
"responses": [
{"categoryId": "529652b0131d5fa206011a99", "value": true},
{"categoryId": "529652b0131d5fa206011a9a", "value": false},
{"categoryId": "529652b0131d5fa206011a9b", "value": true},
{"categoryId": "529652b0131d5fa206011a9c", "value": "Your bacon is the best!"}
],
"timestamp":"2015-04-14T22:33:36.164Z"
}' https://sunnyclear.blazeloop.net/api/v1/responses?authToken=xxxxSample Response
{
"id":"4f1927a407caf1f050000275",
"loopId":"4f1927a407caf1f050000274"
}