Articles in this section

See more

Loop Rest API (V1)

Avatar
Development Team
  • Updated
Follow

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. For a more general-purpose Loop API please see the V2 API.

 

The Loop V1 API is inbound only as depicted in the diagram below:

API functions include:

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.

POST /api/<version>/loops

The request body shall be a JSON object containing the following fields (except for version which is in the URL):

Parameter

Description

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

$ curl -i -X POST -HContent-type:application/json --data '{
    "location":"529652b0121d5fa206011a79",
    "loopType":"529652b0121d5fa206011a09",
    "customFields":{
      "529652b0121d5fa206011a98":"201"
    },
    "description":"Can I please have an extra towel?",
    "title":"Towel Requested",
    "source":"Request System",
    "deviceId":"Front Desk Station 2",
    "timestamp":"2015-04-14T22:33:36.164Z"
}' https://sunnyclear.blazeloop.net/api/v1/loops?authToken=xxxx

Sample Response

{
    "id":"4f1927a407caf1f050000274",
    "url":"https://sunnyclear.blazeloop.net/loop/552d99902e57ea634188569d"
}

 

<> Lookup Loops Created by a Customer

Lookup all loops for a given user account, returns JSON containing list of a customer’s loops:

GET /api/<version>/loops?customer=<userId>

 

Parameter

Description

version

API version, currently v1

userId

Unique identifier (ID) for the customer user account.

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.

GET /api/<version>/locations

 

Parameter

Description

version

API version, currently v1

Retrieve a specific location by its shortcode.

GET /api/<version>/locations/<shortcode>

 

Parameter

Description

version

API version, currently v1

shortcode

An alphanumeric value unique to a location. This value is assigned to a location during configuration of the account.

 

Note: This value typically originates from the account organization and has been known to change if the organization assigns a different value for the location.

Locations: Example

$ curl -i -X GET https://sunnyclear.blazeloop.net/api/v1/locations?authToken=xxxx

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

$ curl -i -X GET https://sunnyclear.blazeloop.net/api/v1/locations/1300?authToken=xxxx

Sample Response

{ 
  "id":"529652b0121d5fa206011a97",
  "shortcode":"1300",
  "title":{
      "en":"Andros Island Bahamas"
  }
}

 

<> Loop Types

Retrieve listing of configured loop types for the account.

GET /api/<version>/looptypes

 

Parameter

Description

version

API version, currently v1

Loop Types: Example

$ curl -i -X GET https://sunnyclear.blazeloop.net/api/v1/looptypes?authToken=xxxx

Sample Response

{ 
  "loopTypes":[
    {
        "id":"529652b0121d5fa206011a97",
        "type":"request",
        "title":{"en":"Request"}
    },
    {
         "id":"529652b0121d5fa206011a98",
         "type":"negative",
         "title":{"en":"Complaint"}
    }
  ]
}

 

<> Custom Fields

Retrieve listing of configured custom fields for the account.

GET /api/<version>/customfields

 

Parameter

Description

version

API version, currently v1

Retrieve a specific custom field by shortcode.

GET /api/<version>/customfields/<shortcode>

 

Parameter

Description

version

API version, currently v1

shortcode

An alphanumeric value unique to a custom field. This value is assigned to a custom field during configuration of the account.

Custom Fields: Example

$ curl -i -X GET \
https://sunnyclear.blazeloop.net/api/v1/customfields/room?authToken=xxxx

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:

POST /api/<version>/users

 

Parameter

Description

version

API version, currently v1

username

Username for the new account. Alphanumeric, first character should be a letter.

name

(optional) Display name for the new user account, e.g. “Leoni Snicket”

sms

(optional) Cell phone number, will be used to send notifications and lookup this user account. Number should be specified in e.164 (e.g. “+16135551234”)

email

(optional) Email address, will be used to send notifications and lookup this account.

locations

(optional) List of location IDs this user is subscribed to receive loops for. Use the Locations API endpoints to lookup the location IDs.

permissions

List of permissions for this user account. Accepted values:

 

create, comment, internal, tag, report

 

<> 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>

 

Parameter

Description

version

API version, currently v1

 

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.

POST /api/<version>/invite/url

 

Parameter

Description

version

API version, currently v1

locationId

The ID or short code of the location to invite the user to. This field is required.

area

(optional) The ID or short code of the internal location to invite the user to.

name

(optional) Name of the user (e.g. “John Smith”)

email

(optional) Email address of the user.

sms

(optional) SMS number of the user.

[custom field]

Any user custom field short code can be supplied here, and these will be used to fill in user custom fields on the created user.

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=xxxx

Sample 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.

GET /api/<version>/surveys

 

Parameter

Description

version

API version, currently v1

 

Retrieve a specific survey by its shortcode.

GET /api/<version>/surveys/<shortcode>

 

Parameter

Description

version

API version, currently v1

shortcode

An alphanumeric value unique to a survey. This value is assigned to a location during configuration of the account.

 

Retrieve the specific survey for a location.

GET /api/<version>/surveys?location=XXX&internalLocation=XXX

 

Parameter

Description

version

API version, currently v1

location

The ID or shortcode for the Location.

area

(Optional) The ID or shortcode for the Internal 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.

 

POST /api/<version>/responses

 

The request body shall be a JSON object containing the following fields (except for version which is in the URL):

Parameter

Description

version

API version, currently v1

source

A type description of the origin of the Response (“kiosk” or “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.

internalLocation

The unique identifier (ID) for the internal location.

survey

The ID or shortcode of the survey being answered.

responses

An array of `{categoryId, value}` objects, where `categoryId` is taken from the question being answered, and `value` is a free-form text field for “text” questions, and true or false for “bool” questions.

timestamp

(optional; Loop assigns the timestamp if not provided)  An RFC2822 or ISO 8601 date string representing the time the Response was created.

bufferReleaseTime

(optional) An RFC2822 or ISO 8601 date string representing the time the Response was sent to the server.

loopId

(optional) The ID of an existing Loop to associate this response with.  To create a Loop at the same time as a Response, pass the `response` parameter to the Loop Create API.

user

(optional) A `{name, email, sms, language}` object with information about the user.  Depending on account settings, if this field is present a Loop may be created along with the Response.  Ignored if `loopId` is provieded.

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.

 

Ignored if `loopId` is provieded.

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=xxxx

Sample Response

{
     "id":"4f1927a407caf1f050000275",
     "loopId":"4f1927a407caf1f050000274"
 }

 

Related articles

Comments

0 comments

Article is closed for comments.