Manager REST API

This document describes a Restful server API for interacting with the Gimbal service.

Authorization


Description

The Gimbal APIs require your organization's server API key in the AUTHORIZATION HTTP header. You can find your organization's server API Key under Organizations.

AUTHORIZATION: Token token=my_organization_server_api_key

Important Some Proximity APIs require OAuth access tokens. See below for more information about OAuth.

Content Type


Description

The Gimbal API's support JSON content type and should be specified in the Content-Type HTTP header as "application/json"

Content-Type: application/json

Response Status


Description

The following is the generic list of response status codes used by the API.

Response Status

HTTP Response Status Description
200 Success
401 Unauthorized
422 Unprocessable Entity
404 Resource Not Found
500 Unexpected Error

Error Codes


Description

The following is the list of error codes used by the API.

Error Codes

Error Code Message
6000 Not Found
6001 Invalid
6002 Beacon belongs to another user
6003 Beacon belongs to another organization
9000 Unknown Error

Application Resources


The following is the list of resources used by the API.

Application Resources


Attribute Data Type Description
id String Unique identifier for an Application
name String Name of the Application
platform String The application's platform, only ios or android is supported
category String The application's category. The following are the available categories:
Books & Reference, Business, Comics, Communication,
Education, Demo, Entertainment,Finance, Games, Health & Fitness,
Lifestyle, Media & Video, Medical, Music & Audio, News & Magazines, Personalization,
Photography, Productivity, Shopping, Social, Sports, Tools, Travel & Local, Weather
identifier String The application's bundle identifier (iOS) or package name (Android)
api_key String Gimbal's client API Key for application

Configuration

All configuration parameters have default values that you may edit

Note: Application configuration settings are only available to version 2.x of the Gimbal SDK.

Attribute Data Type Description Possible Values Current Default
arrival_rssi Integer The 'Arrival RSSI' setting allows you to specify a specific RSSI (signal strength) to be used in determining if a beacon sighting should be processed as an arrival to a beacon. Signals weaker than 'Arrival RSSI' will be ignored. -120 through -35, null (resets to default) -90 dBm
departure_rssi Integer The 'Departure RSSI' setting allows you to specify a specific RSSI (signal strength) to be used in determining if a beacon sighting should be processed as a departure. Signals weaker than 'Departure RSSI' will be ignored. Note that the Departure RSSI must be at least 10dBm lower than the 'Arrival RSSI'. This is done to avoid excessive bouncing (where arrival and departures events are triggered repeatedly, even when both the mobile device and beacon are standing still). -120 through -35, null (resets to default) -120 dBm
departure_interval_in_seconds Integer The number of seconds that must elapse where the SDK does not see a beacon RSSI level stronger than the Departure RSSI before processing the departure. Integer of seconds, null (resets to default) 30 seconds
smoothing_window String The smoothing algorithm processes RSSI signal strengths from sightings to make them less jumpy. The larger the smoothing window the more steady the output RSSI readings will be. none, small, medium, large, null (resets to default) small
allow_kitkat Boolean For Android apps only, This setting allows you to enable beacon support on Android 4.4.3 and 4.4.4 devices. Please note, these versions of Android have known performance issues. Learn more true, false, null (resets to default) false
geofence_monitoring Boolean Allows you to turn on/off geofencing monitoring. This may be desired if your application only uses beacon-based places. true, false, null (resets to default) true
established_locations Boolean Allows you to turn on/off the Established Locations feature. If this is also enabled on the SDK, Gimbal will passively monitor for locations commonly visited by the user. true, false, null (resets to default) true
beacon_monitoring Boolean Allows you to turn off beacon monitoring. This will affect both beacon-based Place detection and beacon detection. This may be useful if your application only uses geofence-based places. true, false, null (resets to default) true
communicate_delivery Boolean Allows you to turn on/off Communicate delivery. This may be useful if your application does not use the Communicate feature. true, false, null (resets to default) true
manage_device_id_for_advertising Boolean iOS: Allows you to turn on/off whether Gimbal records the device advertising identifier and limit ad tracking state for devices. Turning this on is necessary if you wish to correlate your advertising data with the data collected by the Gimbal SDK. This functionality is off by default. Your application must include the AdSupport framework to use this feature.

Important Apple may reject your app if you include the AdSupport Framework without including ad functionality. Be sure to remove the AdSupport Framework if your app does not serve advertising.

Note For privacy reasons, when a device's advertising identifier is reset, the device is re-registered with Gimbal and receives a new application instance identifier.


Android: Allows you to turn on/off whether Gimbal records the device advertising identifier and limit ad tracking state for devices. Turning this on is necessary if you wish to correlate your advertising data with the data collected by the Gimbal SDK. This functionality is off by default. Your application must include the Google Play Services to use this feature.

Note For privacy reasons, when a device's advertising identifier is reset, the device is re-registered with Gimbal and receives a new application instance identifier.

true, false, null (resets to default) false

Get All Applications

Description

Get all applications for a specific organization.

  • In order to retrieve the full details of an application use the get single application API

HTTP Method

GET

URL

https://manager.gimbal.com/api/v2/applications

Sample Response

An array of Application Objects


  [
      {
          "id": "APPLICATION_ID_1",
          "name": "Application 1",
          "category": "Demo",
          "identifier": "com.application.one",
      },
      {
          "id": "APPLICATION_ID_2",
          "name": "Application 2",
          "category": "Media & Video",
          "identifier": "com.application.two",
      }
  ]
                

Get Application

Description

Get a single application with configuration details

HTTP Method

GET

URL

https://manager.gimbal.com/api/v2/applications/APPLICATION_ID_1

Sample Response

Application Detail


  {
      "id": "APPLICATION_ID_1",
      "name": "Application 1",
      "platform": "Android",
      "category": "Demo",
      "identifier": "com.application.one",
      "api_key": "application-one-api-key",
      "configuration": {
          "arrival_rssi": -90,
          "departure_rssi": -120,
          "departure_interval_in_seconds": 30,
          "smoothing_window": "small",
          "allow_kitkat": false,
          "geofence_monitoring": true,
          "established_locations": true,
          "beacon_monitoring": true,
          "communicate_delivery": true,
          "manage_device_id_for_advertising": false
      }
  }
            

Create Application

Description

This call allows you to create a new Application for your organization.

  • If no configuration is specified defaults are used
  • The API Key returned is necessary to set up the Gimbal SDK in your mobile application
  • Note: Application configuration settings are only available to version 2.x of the Gimbal SDK

HTTP Method

POST

URL

https://manager.gimbal.com/api/v2/applications

Sample Request JSON


  {
      "name": "Application 1",
      "platform": "Android",
      "category": "Demo",
      "identifier": "com.application.one",
      "configuration": {
          "departure_interval_in_seconds": 60,
          "smoothing_window": "large",
          "allow_kitkat": true,
          "manage_device_id_for_advertising": true
      }
  }
    

Sample Response


  {
      "id": "APPLICATION_ID_1",
      "name": "Application 1",
      "platform": "Android",
      "category": "Demo",
      "identifier": "com.application.one",
      "api_key": "application-one-api-key",
      "configuration": {
          "arrival_rssi": -90,
          "departure_rssi": -120,
          "departure_interval_in_seconds": 60,
          "smoothing_window": "large",
          "allow_kitkat": true,
          "geofence_monitoring": true,
          "established_locations": true,
          "beacon_monitoring": true,
          "communicate_delivery": true,
          "manage_device_id_for_advertising": true
      }
  }
            

Update Application

This call allows you to update the values and configuration settings of your application.

  • To reset any configuration, pass in the configuration name and the value null
  • To retain a previously saved configuration setting, omit that configuration setting in the update request.
  • Application identifier and Platform cannot be updated once it is set.

HTTP Method

PUT

URL

https://manager.gimbal.com/api/v2/applications/APPLICATION_ID_1

Sample Request JSON


  {
      "name": "Application 1",
      "configuration": {
          "arrival_rssi": -75,
          "departure_rssi": -100,
          "departure_interval_in_seconds": null,
          "smoothing_window": "none",
          "geofence_monitoring": null,
          "beacon_monitoring": null,
          "communicate_delivery": null,
          "manage_device_id_for_advertising": null
      }
  }
      

Sample Response


  {
      "id": "APPLICATION_ID_1",
      "name": "Application 1",
      "platform": "Android",
      "category": "Demo",
      "identifier": "com.application.one",
      "api_key": "application-one-api-key",
      "configuration": {
          "arrival_rssi": -75,
          "departure_rssi": -100,
          "departure_interval_in_seconds": 30,
          "smoothing_window": "none",
          "allow_kitkat": false,
          "geofence_monitoring": true,
          "established_locations": true,
          "beacon_monitoring": true,
          "communicate_delivery": true,
          "manage_device_id_for_advertising": false
      }
  }
            

Delete Application

Please contact support if you wish to have your application deleted. Gimbal Manager Support.



Place Resources


The following is the list of resources used by the API.

  • Note: Beacon support for places is only available to version 2.x of the Gimbal SDK

Place Resources

Attribute Data Type Description
id String Unique identifier for a Place
name String Name of the Place

Place Detail

Attribute Data Type Description Optional
id String Unique identifier for a Place false
name String Name of the Place false
attributes Object Series of key and value fields true
geofence Object Geofence object related to this Place true
beacons SDK Version 2.X Array Array of Beacon objects related to this place true
arrivalRssi SDK Version 2.X Number Rssi required to enter place true, both arrival and departure RSSI must be included when used
departureRssi SDK Version 2.X Number Rssi required to exit place

Geofence

Attribute Data Type Description Optional
shape String CIRCLE or POLYGON false
radius Number The radius in meters of a Circle geofence true
center Point A Point object defining the center of a Circle geofence true
points Array Array of Points objects defining Polygonal geofences true
source String "1" for public geofence, null otherwise true
sourceId String public geofence id true
sourceVersion String Version for public geofence source true
sourceIdType String Type of the public geofence source(example "shopping") true

Beacon SDK Version 2.X

Attribute Data Type Description Optional
id String Unique identifier for the beacon At least one required
factoryId String Unique factory identifier for the beacon
name String Name of the beacon false
attributes Object Series of key and value fields true

Point

Attribute Data Type Description Optional
Latitude Number Latitude of this Point false
Longitude Number Longitude of this Point false

Get All Places

Description

Get all places for a specific organization.

HTTP Method

GET

URL

https://manager.gimbal.com/api/v2/places

Optional Query Parameters

Parameter Description
name

Only return places which have a name containing this string.

attribute_key[N]

[N] is a number greater than or equal to 1.
Only return places which have an attribute key containing this string.
You can pass multiple attribute keys, each one must end with a number.

Example: https://manager.gimbal.com/api/v2/places?attribute_key1=hello&attribute_key2=aloha&attribute_key3=island
This will return places having attributes with keys "hello", "aloha", and "island". The attribute values are ignored.

attribute_value[N]

[N] is a number greater than or equal to 1.
Only return places which have an attribute value containing this string.
You can pass multiple attribute values, each one must end with a number.

Example:
https://manager.gimbal.com/api/v2/places?attribute_value1=world&attribute_value2=hawaii&attribute_value3=volcano
This will return places having attributes with values "world", hawaii", and "volcano". The attribute keys are ignored.

If both an attribute key and value ending with the same number are given both the attribute key and value must match.

Example:
https://manager.gimbal.com/api/v2/places?attribute_key1=hello&attribute_value1=world
This would only match attributes which have both the key "hello" and the value "world".
Place attributes which have key "hello" but do not have value "world" will not match.

per_page

Sets the number of items per page.

page

Return the results in the given page after filtering by name and attribute keys and values.
The number of items per page is determined by the per_page parameter.

if either the page or per_page parameter is given pagination will be performed.
If neither the page or per_page parameter are given no pagination will be performed.

If the page parameter is not given but the per_page parameter is given then page = 1.
If the page parameter is given but the per_page parameter is not given then per_page = 50.

If page or per_page is sent the following pagination headers will be sent in the response

Total-Places

The total number of places found matching the filters.
If no places are found this will be zero.

Total-Pages

The total number of pages (total number of places / per_page).
If no places are found this will not be sent.

Current-Page

The current page. Should be the same as the page query parameter.
If no places are found this will not be sent.

Example:

Request:

  curl -H "Authorization: Token token=your_server_api_key" https://manager.gimbal.com/api/v2/places?name=hello&page=2&per_page=3
                    
Response:
  HTTP/1.1 200 OK
  Total-Pages: 10
  Current-Page: 2
  Total-Places: 30
  Content-Type: application/json; charset=utf-8

  [
      {
          "id": "BF65596C4CC4476E8D2CA3941784AF74",
          "name": "Hello World"
      },
      {
          "id": "642A26912FD44680B2F7E0331C189DDE",
          "name": "Hello There"
      },
      {
          "id": "F3420820C6FC4885B704EFA46DA5A18A",
          "name": "Say Hello"
      }
  ]
                    
This will return rows 4, 5, and 6 after selecting only places with name containing the word "hello".

Sample Response

An array of Place Objects


  [
      {
          "id": "MY-PLACE-ID-1",
          "name": "My First Place"
      },
      {
          "id": "MY-PLACE-ID-2",
          "name": "My Second Place"
      }
  ]
                

Using Filters

Request

https://manager.gimbal.com/api/v2/places?name=John&attribute_key1=location&attribute_value1=new

Response

Here the response will return all places with name containing "John" and at least one attribute which has key containing "location" and value containing "new".

Example of matching attributes:

Place Name Place Attribute Key Place Attribute Value
Johnny location New york
Johnston us-location new jersey
Mr John location-country Papua New Guinea


  [
      {
          "id": "MY-PLACE-ID-1",
          "name": "Johnny"
      },
      {
          "id": "MY-PLACE-ID-2",
          "name": "Johnston"
      }
      {
          "id": "MY-PLACE-ID-2",
          "name": "Mr John"
      }
  ]
        

Get Place

Description

Get Place Detail object for a specific place

HTTP Method

GET

URL

https://manager.gimbal.com/api/v2/places/MY-PLACE-ID

Sample Response

Place Detail


    {
        "id": "MY-PLACE-ID",
        "name": "My Place",
        "geofence": {
            "shape": "POLYGON",
            "radius": null,
            "center": null,
            "points": [
                {
                    "latitude": 32.904217,
                    "longitude": -117.228185
                },
                {
                    "latitude": 32.903909,
                    "longitude": -117.228629
                },
                {
                    "latitude": 32.903324,
                    "longitude": -117.228054
                },
                {
                    "latitude": 32.903555,
                    "longitude": -117.227508
                }
            ],
            "source": null,
            "sourceId": null,
            "sourceVersion": null,
            "sourceIdType": null
        },
        "beacons": [
            {
                "id": "MY-BEACON-ID",
                "factoryId": "MY-BEACON-FACTORY-ID",
                "name": "My Beacon",
                "attributes": {
                    "beacon key1": "value1",
                    "beacon key2": "value2"
                }
            }
        ],
        "arrivalRssi": -90,
        "departureRssi": -120,
        "attributes": {
            "key1": "value1",
            "key2": "value2"
        }
    }
            

Create Place

Description

This call allows you to create a new Place for your organization.

  • The beacon(s) must already be activated and the ID is used to create the relationship
  • Note: Beacon support for places are only available to version Gimbal SDK 2.x

HTTP Method

POST

URL

https://manager.gimbal.com/api/v2/places

Sample Request JSON to Create a Place with a Polygonal Geofence


     {
        "name": "My Place",
        "geofence": {
            "shape": "POLYGON",
            "radius": null,
            "center": null,
            "points": [
                {
                    "latitude": 32.904217,
                    "longitude": -117.228185
                },
                {
                    "latitude": 32.903909,
                    "longitude": -117.228629
                },
                {
                    "latitude": 32.903324,
                    "longitude": -117.228054
                },
                {
                    "latitude": 32.903555,
                    "longitude": -117.227508
                }
            ]
        },
        "beacons": [
            {
                "id": "MY-BEACON-ID-ONE"
            },
            {
                "factoryId": "MY-BEACON-FACTORY-ID-TWO"
            }
        ],
        "arrivalRssi": -90,
        "departureRssi": -120,
        "attributes": {
            "key1": "value1",
            "key2": "value2"
        }
    }

    

Sample Response


  {
      "id": "MY-PLACE-ID",
      "name": "My Place",
      "geofence": {
          "shape": "POLYGON",
          "radius": null,
          "center": null,
          "points": [
              {
                  "latitude": 32.904217,
                  "longitude": -117.228185
              },
              {
                  "latitude": 32.903909,
                  "longitude": -117.228629
              },
              {
                  "latitude": 32.903324,
                  "longitude": -117.228054
              },
              {
                  "latitude": 32.903555,
                  "longitude": -117.227508
              }
          ],
          "source": null,
          "sourceId": null,
          "sourceVersion": null,
          "sourceIdType": null
      },
      "beacons": [
          {
              "id": "MY-BEACON-ID-ONE",
              "factoryId": "MY-BEACON-FACTORY-ID-ONE",
              "name": "My First Beacon"
          },
          {
              "id": "MY-BEACON-ID-TWO",
              "factoryId": "MY-BEACON-FACTORY-ID-TWO",
              "name": "My Second Beacon"
          }
      ],
      "arrivalRssi": -90,
      "departureRssi": -120,
      "attributes": {
          "key1": "value1",
          "key2": "value2"
      }
  }
            

Sample Request JSON to Create a Place with a Round Geofence

  {
    "name": "My Place",
    "geofence": {
        "shape": "CIRCLE",
        "radius": 50,
        "center": {
            "latitude": 32.903757,
            "longitude": -117.228159
        },
        "points": null
     },
     "beacons": [
         {
            "id": "MY-BEACON-ID-ONE"
         },
         {
             "factoryId": "MY-BEACON-FACTORY-ID-TWO"
         }
      ],
      "arrivalRssi": -90,
      "departureRssi": -120,    
      "attributes": {
         "key1": "value1",
         "key2": "value2"
      }
  }
        

Sample JSON Response

  {
      "id": "MY-PLACE-ID",
      "name": "My Place",
      "geofence": {
          "shape": "CIRCLE",
          "radius": 50,
          "center": {
            "latitude": 32.903757,
            "longitude": -117.228159
          },
          "points": null,
          "source": null,
          "sourceId": null,
          "sourceVersion": null,
          "sourceIdType": null
      },
      "beacons": [
          {
              "id": "MY-BEACON-ID-ONE",
              "factoryId": "MY-BEACON-FACTORY-ID-ONE",
              "name": "My First Beacon"
          },
          {
              "id": "MY-BEACON-ID-TWO",
              "factoryId": "MY-BEACON-FACTORY-ID-TWO",
              "name": "My Second Beacon"
          }
      ],
      "arrivalRssi": -90,
      "departureRssi": -120,
      "attributes": {
          "key1": "value1",
          "key2": "value2"
      }
  }
          

Update Place

Update place request will replace all information with input submitted.

  • If geofence, attributes and beacons is not sent in as part of the PUT request it will remain untouched
  • To reset or remove beacons, geofence, and attributes, simply pass in null as the value.
  • No existing beacons are affected, just the relationship to the place
  • When updating a place with a geofence, attribute(s) and or beacon(s) would replace the old set of values assigned to it

HTTP Method

PUT

URL

https://manager.gimbal.com/api/v2/places/MY-PLACE-ID

Sample Request JSON


    {
        "name": "My Place Update",
        "geofence": {
            "shape": "POLYGON",
            "radius": null,
            "center": null,
            "points": [
                {
                    "latitude": 32.904217,
                    "longitude": -117.228185
                },
                {
                    "latitude": 32.903909,
                    "longitude": -117.228629
                },
                {
                    "latitude": 32.903324,
                    "longitude": -117.228054
                },
                {
                    "latitude": 32.903555,
                    "longitude": -117.227508
                }
            ]
        },
        "arrivalRssi": -90,
        "departureRssi": -120,
        "beacons": [
            {
                "id": "MY-BEACON-ID"
            }
        ],
        "attributes": {
            "key1": "value1"
        }
    }
            

Sample Response


  {
      "id": "MY-PLACE-ID",
      "name": "My Place Update",
      "geofence": {
          "shape": "POLYGON",
          "radius": null,
          "center": null,
          "points": [
              {
                  "latitude": 32.904217,
                  "longitude": -117.228185
              },
              {
                  "latitude": 32.903909,
                  "longitude": -117.228629
              },
              {
                  "latitude": 32.903324,
                  "longitude": -117.228054
              },
              {
                  "latitude": 32.903555,
                  "longitude": -117.227508
              }
          ],
          "source": null,
          "sourceId": null,
          "sourceVersion": null,
          "sourceIdType": null
      },
      "beacons": [
          {
              "id": "MY-BEACON-ID",
              "factoryId": "MY-BEACON-FACTORY-ID",
              "name": "My Beacon"
          }
      ],
      "arrivalRssi": -90,
      "departureRssi": -120,
      "attributes": {
          "key1": "value1"
      }
  }
            

Sample Partial Request JSON

*Note: Geofence and Beacon(s) are untouched. Only updating the name and setting the attributes for the place to null.


  {
      "name": "MY-PLACE-ID UPDATED",
      "attributes": null
  }
      

Sample Response


  {
      "id": "MY-PLACE-ID",
      "name": "My Place Update",
      "geofence": {
          "shape": "POLYGON",
          "radius": null,
          "center": null,
          "points": [
              {
                  "latitude": 32.904217,
                  "longitude": -117.228185
              },
              {
                  "latitude": 32.903909,
                  "longitude": -117.228629
              },
              {
                  "latitude": 32.903324,
                  "longitude": -117.228054
              },
              {
                  "latitude": 32.903555,
                  "longitude": -117.227508
              }
          ],
          "source": null,
          "sourceId": null,
          "sourceVersion": null
      },
      "beacons": [
          {
              "id": "MY-BEACON-ID",
              "name": "My Beacon"
          }
      ],
      "arrivalRssi": -90,
      "departureRssi": -120,
      "attributes": {}
  }
       

Delete Place

Delete place with specific ID

HTTP Method

DELETE

URL

https://manager.gimbal.com/api/v2/places/MY-PLACE-ID

Sample Request


  curl -X DELETE -H "AUTHORIZATION: Token token=MY-GIMBAL-SERVER-API-KEY" https://manager.gimbal.com/api/v2/places/MY-PLACE-ID
                

Sample Response


  {"message":"Success"}
                

Beacons


The Proximity Developer APIs allow a developer to manage beacons. These APIs are protected with API Key which means they must be accessed using organization's server API key. APIs are restricted to beacons owned by the organization associated with the authorization key.

Note Across all documentation and SDKs the terms 'Beacon' and 'Transmitter' are interchangeable

Activate Beacon

Description

This API allows a developer to activate a new beacon for their organization. This beacon must not belong to any other organization in the system.

HTTP Method

POST

Activate POST Attributes

Attribute Description
Factory Identifier Required The unique identifier of the beacon
Name Required The developer provided name for the beacon
Latitude The latitude of the place where beacon is located
Longitude The longitude of the place where beacon is located
Visibility The visibility of the beacon to other organization. Visibility can be private or public
Configuration Identifier The beacon configuration identifier that can be applied to configure the beacon
Contact Emails The contact emails will receive the low battery emails for this beacon
Beacon Attributes User defined key-value attribute pairs associated with the beacon.

Example: POST https://manager.gimbal.com/api/beacons

Important v2 introduces the concept of places. A Place can be represented by a single geofence and/or a series of beacons. When you activate a beacon, a corresponding place isn't created automatically. Please create a Place for your beacon as needed using the Places REST API.

Sample JSON


    {
        "factory_id": "XXXX-YYYYY",
        "name": "John's Beacon",
        "latitude": 32.7150,
        "longitude": 117.1625,
        "config_id": 100,
        "visibility": "private",
        "contact_emails": ["owner@gimbal.com", "developer@gimbal.com"],
        "beacon_attributes": {
            "key1": "value1",
            "key2": "value2"
        }
    }
                        

RESPONSE You will receive a 200 OK with a JSON response as shown below

Sample JSON Response


    {
        "id": "beacon_id",
        "factory_id": "XXXX-YYYYY",
        "icon_url": "https://api.getfyx.com/assets/fallback/default_icon.png",
        "name": "John's Beacon",
        "latitude": 32.7150,
        "longitude": 117.1625,
        "gimbal_latitude": null,
        "gimbal_longitude": null,
        "gimbal_location_last_updated_date": null,
        "visibility": "Private",
        "battery_level": "Battery Level of the Beacon",
        "battery_updated_date": "2016-05-28T15:54:11.000Z",
        "hardware": "Hardware type of the Beacon",
        "owner": "SELF",
        "contact_emails": ["owner@gimbal.com", "developer@gimbal.com"],
        "beacon_attributes": {
            "key1": "value1",
            "key2": "value2"
        }
    }
                        

Deactivate Beacon

Description

This API allows a developer to deactivate a beacon they have previously activated in their organization. After deactivating the beacon can be activated by another developer or re-activated by the same developer.

HTTP Method

DELETE

Example: DELETE https://manager.gimbal.com/api/beacons/{factory_id}

RESPONSE You will receive a 200 OK with an empty body

Get Beacon By Factory ID

Description

Call this API to retrieve the metadata of a beacon by the given factory identifier.

HTTP Method

GET

Example: GET https://manager.gimbal.com/api/beacons/{factory_id}

Sample JSON Response


    {
        "id": "beacon_id",
        "factory_id": "XXXX-YYYYY",
        "icon_url": "https://api.getfyx.com/assets/fallback/default_icon.png",
        "name": "John's Beacon",
        "latitude": 32.7150,
        "longitude": 117.1625,
        "gimbal_latitude": 33.889916,
        "gimbal_longitude": -117.351344,
        "gimbal_location_last_updated_date": "2016-07-22T09:32:02.000Z",
        "visibility": "Private",
        "battery_level": "Battery Level of the Beacon",
        "battery_updated_date": "2016-05-28T15:54:11.000Z",
        "hardware": "Hardware type of the Beacon",
        "owner": "SELF",
        "contact_emails": [],
        "beacon_attributes": {
            "key1": "value1",
            "key2": "value2"
        }
    }
                        

Get Beacon By Beacon UUID

Description

Call this API to retrieve the metadata of a beacon by the given beacon uuid.

HTTP Method

GET

Example: GET https://manager.gimbal.com/api/beacons/{beacon_id}

Sample JSON Response


    {
        "id": "beacon_id",
        "factory_id": "XXXX-YYYYY",
        "icon_url": "https://api.getfyx.com/assets/fallback/default_icon.png",
        "name": "John's Beacon",
        "latitude": 32.7150,
        "longitude": 117.1625,
        "gimbal_latitude": 33.889916,
        "gimbal_longitude": -117.351344,
        "gimbal_location_last_updated_date": "2016-07-22T09:32:02.000Z",
        "visibility": "Private",
        "battery_level": "Battery Level of the Beacon",
        "battery_updated_date": "2016-05-28T15:54:11.000Z",
        "hardware": "Hardware type of the Beacon",
        "owner": "SELF",
        "beacon_attributes": {
            "key1": "value1",
            "key2": "value2"
        }
    }
                        

Get All Beacons

Description

Call this API to retrieve all beacons associated to a specific organization. The organization is the owner of the API key.

HTTP Method

GET

Example: GET https://manager.gimbal.com/api/beacons

Optional Query Parameters

Parameter Description
name

Only return beacons which have a name containing this string.

attribute_key[N]

[N] is a number greater than or equal to 1.
Only return beacons which have an attribute key containing this string.
You can pass multiple attribute keys, each one must end with a number.

Example: https://manager.gimbal.com/api/beacons?attribute_key1=hello&attribute_key2=aloha&attribute_key3=island
This will return beacons having attributes with keys "hello", "aloha", and "island". The attribute values are ignored.

attribute_value[N]

[N] is a number greater than or equal to 1.
Only return beacons which have an attribute value containing this string.
You can pass multiple attribute values, each one must end with a number.

Example:
https://manager.gimbal.com/api/beacons?attribute_value1=world&attribute_value2=hawaii&attribute_value3=volcano
This will return beacons having attributes with values "world", hawaii", and "volcano". The attribute keys are ignored.

If both an attribute key and value ending with the same number are given both the attribute key and value must match.

Example:
https://manager.gimbal.com/api/beacons?attribute_key1=hello&attribute_value1=world
This would only match attributes which have both the key "hello" and the value "world".
Beacon attributes which have key "hello" but do not have value "world" will not match.

per_page

Sets the number of items per page.

page

Return the results in the given page after filtering by name and attribute keys and values.
The number of items per page is determined by the per_page parameter.

if either the page or per_page parameter is given pagination will be performed.
If neither the page or per_page parameter are given no pagination will be performed.

If the page parameter is not given but the per_page parameter is given then page = 1.
If the page parameter is given but the per_page parameter is not given then per_page = 50.

If page or per_page is sent the following pagination headers will be sent in the response

Total-Beacons

The total number of beacons found matching the filters.
If no beacons are found this will be zero.

Total-Pages

The total number of pages (total number of beacons / per_page).
If no beacons are found this will not be sent.

Current-Page

The current page. Should be the same as the page query parameter.
If no beacons are found this will not be sent.

Example:

Request:

  curl -H "Authorization: Token token=your_server_api_key" https://manager.gimbal.com/api/beacons?name=hello&page=2&per_page=3
                    
Response:
  HTTP/1.1 200 OK
  Total-Pages: 10
  Current-Page: 2
  Total-Beacons: 30
  Content-Type: application/json; charset=utf-8

   [
        {
            "id": "beacon_id_one",
            "factory_id": "XXXX-ZZZZZ",
            "icon_url": "https://api.getfyx.com/assets/fallback/default_icon.png",
            "name": "Hello World",
            "latitude": 32.7150,
            "longitude": 117.1625,
            "gimbal_latitude": 33.889916,
            "gimbal_longitude": -117.351344,
            "gimbal_location_last_updated_date": "2016-07-22T09:32:02.000Z",
            "visibility": "Private",
            "battery_level": "Battery Level of the Beacon",
            "battery_updated_date": "2016-05-28T15:54:11.000Z",
            "hardware": "Hardware type of the Beacon",
            "owner": "SELF",
            "beacon_attributes": {
                "key1": "value1",
                "key2": "value2"
            }
        },

        {
            "id": "shared_beacon_one",
            "name": "Hello There",
            "latitude": 32.7150,
            "longitude": 117.1625,
            "gimbal_latitude": 33.889916,
            "gimbal_longitude": -117.351344,
            "gimbal_location_last_updated_date": "2016-07-22T09:32:02.000Z",
            "beacon_attributes": {
                "key1": "value1",
                "key2": "value2"
            },
            "owner": "OTHER",
            "imported_sharing_keys": [
                "sharing-key-one",
                "sharing-key-two"
            ]
        },
        {
            "id": "public_beacon_one",
            "name": "Say Hello",
            "latitude": 32.7150,
            "longitude": 117.1625,
            "gimbal_latitude": 33.889916,
            "gimbal_longitude": -117.351344,
            "gimbal_location_last_updated_date": "2016-07-22T09:32:02.000Z",
            "beacon_attributes": {
                "key1": "value1",
                "key2": "value2"
            },
            "owner": "OTHER",
            "imported_sharing_keys": [
                "sharing-key-one",
                "sharing-key-two"
            ]
        }
     ]
                    
This will return rows 4, 5, and 6 after selecting only beacons with name containing the word "hello".

Sample JSON Response


    [
        {
            "id": "beacon_id_one",
            "factory_id": "XXXX-ZZZZZ",
            "icon_url": "https://api.getfyx.com/assets/fallback/default_icon.png",
            "name": "John's Beacon one",
            "latitude": 32.7150,
            "longitude": 117.1625,
            "gimbal_latitude": 33.889916,
            "gimbal_longitude": -117.351344,
            "gimbal_location_last_updated_date": "2016-07-22T09:32:02.000Z",
            "visibility": "Private",
            "battery_level": "Battery Level of the Beacon",
            "battery_updated_date": "2016-05-28T15:54:11.000Z",
            "hardware": "Hardware type of the Beacon",
            "owner": "SELF",
            "beacon_attributes": {
                "key1": "value1",
                "key2": "value2"
            }
        },
        {
            "id": "beacon_id_two",
            "factory_id": "XXXX-YYYYY",
            "icon_url": "https://api.getfyx.com/assets/fallback/default_icon.png",
            "name": "John's Beacon two",
            "latitude": 32.7150,
            "longitude": 117.1625,
            "gimbal_latitude": 33.889916,
            "gimbal_longitude": -117.351344,
            "gimbal_location_last_updated_date": "2016-07-22T09:32:02.000Z",
            "visibility": "Public",
            "battery_level": "Battery Level of the Beacon",
            "battery_updated_date": "2016-05-28T15:54:11.000Z",
            "hardware": "Hardware type of the Beacon",
            "owner": "SELF",
            "beacon_attributes": {
                "key1": "value1",
                "key2": "value2"
            }
        },
        {
            "id": "shared_beacon_one",
            "name": "Shared Beacon",
            "latitude": 32.7150,
            "longitude": 117.1625,
            "gimbal_latitude": 33.889916,
            "gimbal_longitude": -117.351344,
            "gimbal_location_last_updated_date": "2016-07-22T09:32:02.000Z",
            "beacon_attributes": {
                "key1": "value1",
                "key2": "value2"
            },
            "owner": "OTHER",
            "imported_sharing_keys": [
                "sharing-key-one",
                "sharing-key-two"
            ]
        },
        {
            "id": "public_beacon_one",
            "name": "Imported Public Beacon",
            "latitude": 32.7150,
            "longitude": 117.1625,
            "gimbal_latitude": 33.889916,
            "gimbal_longitude": -117.351344,
            "gimbal_location_last_updated_date": "2016-07-22T09:32:02.000Z",
            "beacon_attributes": {
                "key1": "value1",
                "key2": "value2"
            },
            "owner": "OTHER",
            "imported_sharing_keys": [
                "sharing-key-one",
                "sharing-key-two"
            ]
        }
     ]
                        

Using Filters

Request

https://manager.gimbal.com/api/beacons?name=John&attribute_key1=location&attribute_value1=new

Response

Here the response will return all beacons with name containing "John" and at least one attribute which has key containing "location" and value containing "new".

Example of matching attributes:

Beacon Name Beacon Attribute Key Beacon Attribute Value
Johnny location New york
Johnston us-location new jersey
Mr John location-country Papua New Guinea


   [
        {
            "id": "beacon_id_one",
            "factory_id": "XXXX-ZZZZZ",
            "icon_url": "https://api.getfyx.com/assets/fallback/default_icon.png",
            "name": "Johnny",
            "latitude": 32.7150,
            "longitude": 117.1625,
            "gimbal_latitude": 33.889916,
            "gimbal_longitude": -117.351344,
            "gimbal_location_last_updated_date": "2016-07-22T09:32:02.000Z",
            "visibility": "Private",
            "battery_level": "Battery Level of the Beacon",
            "battery_updated_date": "2016-05-28T15:54:11.000Z",
            "hardware": "Hardware type of the Beacon",
            "owner": "SELF",
            "beacon_attributes": {
                "location": "New York",
            }
        },

        {
            "id": "shared_beacon_one",
            "name": "Johnston",
            "latitude": 32.7150,
            "longitude": 117.1625,
            "gimbal_latitude": 33.889916,
            "gimbal_longitude": -117.351344,
            "gimbal_location_last_updated_date": "2016-07-22T09:32:02.000Z",
            "beacon_attributes": {
                "us-location": "new jersey",
                "key2": "new jersey"
            },
            "owner": "OTHER",
            "imported_sharing_keys": [
                "sharing-key-one",
                "sharing-key-two"
            ]
        },
        {
            "id": "public_beacon_one",
            "name": "Mr John",
            "latitude": 32.7150,
            "longitude": 117.1625,
            "gimbal_latitude": 33.889916,
            "gimbal_longitude": -117.351344,
            "gimbal_location_last_updated_date": "2016-07-22T09:32:02.000Z",
            "beacon_attributes": {
                "location-country": "Papua New Guinea",
            },
            "owner": "OTHER",
            "imported_sharing_keys": [
                "sharing-key-one",
                "sharing-key-two"
            ]
        }
     ]
        

Update Beacon

Description

This API allows a developer to updated the metadata of a beacon.

HTTP Method

PUT

Update PUT Attributes

Attribute Description
Factory Identifier Required The unique identifier of the beacon
Name The developer provided name for the beacon
Latitude The latitude of the place where beacon is located
Longitude The longitude of the place where beacon is located
Visibility The visibility of the beacon to other organization. Visibility can be private or public
Configuration Identifier The beacon configuration identifier that can be applied to configure the beacon
Contact Emails The contact emails will receive the low battery emails for this beacon
Beacon Attributes User defined key-value attribute pairs associated with the beacon.

Example: PUT https://manager.gimbal.com/api/beacons/{factory_id}

Sample JSON


    {
        "name": "John's Beacon",
        "latitude": 32.7150,
        "longitude": 117.1625,
        "config_id": 100,
        "visibility": "private",
        "contact_emails": ["owner@gimbal.com", "developer@gimbal.com"],
        "beacon_attributes": {
            "key1": "value1",
            "key2": "value2"
        }
    }
                        

RESPONSE You will receive a 200 OK with a JSON response as shown below

Sample JSON Response


    {
        "id": "beacon_id",
        "factory_id": "XXXX-YYYYY",
        "icon_url": "https://api.getfyx.com/assets/fallback/default_icon.png",
        "name": "John's Beacon",
        "latitude": 32.7150,
        "longitude": 117.1625,
        "gimbal_latitude": 33.889916,
        "gimbal_longitude": -117.351344,
        "gimbal_location_last_updated_date": "2016-07-22T09:32:02.000Z",
        "visibility": "Private",
        "battery_level": "Battery Level of the Beacon",
        "battery_updated_date": "2016-05-28T15:54:11.000Z",
        "hardware": "Hardware type of the Beacon",
        "owner": "SELF",
        "contact_emails": ["owner@gimbal.com", "developer@gimbal.com"],
        "beacon_attributes": {
            "key1": "value1",
            "key2": "value2"
        }
    }
    

Get Beacon Configuration By Factory Id

Description

Call this API to retrieve the current configuration of a beacon by the given factory identifier.

HTTP Method

GET

Example: GET https://manager.gimbal.com/api/beacons/{factory_id}/configuration

Sample JSON Response


    {
        "assigned_configuration": "Configuration assigned to the beacon",
        "applied_configuration": "Configuration applied to the beacon"
    }
            

Beacon Configurations


Create Beacon Configuration

Description

This API allows a developer to create a new beacon configuration for their organization.

HTTP Method

POST

Create Configuration POST Attributes

Attribute JSON Key Needed For Beacon Type Description
Name name Required for All The developer provided name for the beacon configuration
Beacon Type beacon_type Required for All The beacon type for wich the configuration is created. Supported beacon types are Gimbal, iBeacon, Eddystone, and Eddystone and iBeacon.
Note Only beacons with firmware version 1.6.1 and above support iBeacon configurations
Optimized For Background optimized_for_background Gimbal Beacon Only Optimization flag for beacon detection in background mode. Supported optimization flags are Foreground or Background and Foreground-only
Transmission Power transmission_power All The transmission power (measured in decibels) at which the beacon antenna will transmit once configuration is applied.
Antenna Type antenna_type All The transmission mode in which the beacon antenna will transmit once configuration is applied. Supported antenna types are Omnidirectional and Directional
Proximity UUID proximity_uuid Required for iBeacon Required for 'Eddystone and iBeacon' Proximity UUID is value specific to iBeacon. Please refer to the Apple iOS Dev Center for additional information
Major major Required for iBeacon Required for 'Eddystone and iBeacon' Major is value specific to iBeacon. Please refer to the Apple iOS Dev Center for additional information
Minor minor Required for iBeacon Required for 'Eddystone and iBeacon' Minor is value specific to iBeacon. Please refer to the Apple iOS Dev Center for additional information
Measured Power measured_power iBeacon Eddystone and iBeacon Measured power is value specific to iBeacon. Please refer to the Apple iOS Dev Center for additional information
Transmission Interval transmission_interval or ibeacon_transmission_interval iBeacon Eddystone and iBeacon Transmission Interval is value specific to iBeacon. You can change the transmission interval between 100 and 10,000ms. Please note, altering the transmission interval may make this configuration non-compliant with the iBeacon specification
Calibrated Power calibrated_power Eddystone Eddystone and iBeacon Calibrated Power is value specific to 'Eddystone' and 'Eddystone and iBeacon'.
Eddystone Transmission Interval eddystone_transmission_interval Eddystone Eddystone and iBeacon Eddystone Transmission Interval is value specific to 'Eddystone' and 'Eddystone and iBeacon'. This is the value in milliseconds at which the Eddystone frames are transmitted
UID Namespace ID uid_namespace_id Eddystone Eddystone and iBeacon UID Namespace ID is value specific to 'Eddystone' and 'Eddystone and iBeacon'. If this field is present the UID frame will be sent and you will have to provide the uid_instance_id parameter as well
UID Instance ID uid_instance_id Eddystone Eddystone and iBeacon UID Instance ID is value specific to 'Eddystone' and 'Eddystone and iBeacon'. If this field is present the UID frame will be sent and you will have to provide the uid_namespace_id parameter as well
Transmit UID Frequency transmit_uid_frequency Eddystone Eddystone and iBeacon UID Frequency is value specific to 'Eddystone' and 'Eddystone and iBeacon'. The frequency must have one of the values of low, medium, or high which means the frame will be sent every 12th, 5th, or every transmission interval respectfully.
Transmit URL Scheme url_scheme Eddystone Eddystone and iBeacon URL Scheme is value specific to 'Eddystone' and 'Eddystone and iBeacon'. If this field is present the URL frame will be sent and you will have to provide the url parameter as well. URL Scheme will take the values of http://www., https://www., http://, or https://
URL url Eddystone Eddystone and iBeacon URL is value specific to 'Eddystone' and 'Eddystone and iBeacon'. Please note that the URL only allows 17 bytes and follows the encoding guidelines at Eddystone-URL HTTP URL Encoding
Transmit URL Frequency transmit_url_frequency Eddystone Eddystone and iBeacon URL Frequency is value specific to 'Eddystone' and 'Eddystone and iBeacon'. The frequency must have one of the values of low, medium, or high which means the frame will be sent every 12th, 5th, or every transmission interval respectfully.
TLM tlm Eddystone Eddystone and iBeacon TLM is value specific to 'Eddystone' and 'Eddystone and iBeacon'. If present and set to true the TLM frame will be sent. TLM can only take values of true and false
Transmit TLM Frequency transmit_tlm_frequency Eddystone Eddystone and iBeacon TLM Frequency is value specific to 'Eddystone' and 'Eddystone and iBeacon'. The frequency must have one of the values of low, medium, or high which means the frame will be sent every 12th, 5th, or every transmission interval respectfully.

Example: POST https://manager.gimbal.com/api/beacon_configurations

Sample JSON for Gimbal Beacon


      {
          "name":"Beacon Config Name",
          "beacon_type":"Gimbal",
          "optimized_for_background" : "Foreground-only",
          "transmission_power": xx,
          "antenna_type":"Omnidirectional"
      }
                        

RESPONSE You will receive a 200 OK with a JSON response as shown below

Sample JSON Response for Gimbal Beacon


      {
          "id": XXX,
          "name": "Beacon Config Name",
          "beacon_type": "Gimbal",
          "transmission_power": xx,
          "antenna_type": "Omnidirectional",
          "optimized_for_background": "Foreground-only"
      }
        

Sample JSON for iBeacon


      {
          "name":"Beacon Config Name",
          "beacon_type":"iBeacon",
          "optimized_for_background" : "Foreground-only",
          "transmission_power": xx,
          "antenna_type":"Omnidirectional"
          "transmission_interval": "5000"
      }
                        

RESPONSE You will receive a 200 OK with a JSON response as shown below

Sample JSON Response for iBeacon


      {
          "id": XXX,
          "name": "Beacon Config Name",
          "beacon_type": "iBeacon",
          "transmission_power": xx,
          "antenna_type": "Omnidirectional",
          "optimized_for_background": "Foreground-only"
          "transmission_interval": 5000
      }
        

Sample JSON for 'Eddystone and iBeacon'


                 {
                  "name":"Sample Eddystone and iBeacon",
                  "beacon_type":"Eddystone and iBeacon",
                  "optimized_for_background" : "Foreground or Background",
                  "transmission_power": "Recommended",
                  "antenna_type":"Omnidirectional",
                  "uid_namespace_id": "01020304050607080900",
                  "uid_instance_id": "010203040506",
                  "transmit_uid_frequency" : "high",

                  "url_scheme" : "https://www.",
                  "url" : "gimbal.com",
                  "transmit_url_frequency" : "medium",

                  "tlm" : true,
                  "transmit_tlm_frequency" : "low",

                  "calibrated_power" : 44,
                  "eddystone_transmission_interval" : 200,

                  "proximity_uuid" : "adfadfad-fadf-aadf-aadf-adfadfadfadf",
                  "major": 100,
                  "minor" : 62000,
                  "ibeacon_transmission_interval" : 100

                }
                                

RESPONSE You will receive a 200 OK with a JSON response as shown below

Sample JSON Response for 'Eddystone and iBeacon'


                {
                  "id": XXX,
                  "name": "Sample Eddystone and iBeacon",
                  "beacon_type": "Eddystone and iBeacon",
                  "transmission_power": "Recommended",
                  "antenna_type": "Omnidirectional",
                  "proximity_uuid": "ADFADFAD-FADF-AADF-AADF-ADFADFADFADF",
                  "major": 100,
                  "minor": 62000,
                  "measured_power": "Recommended",
                  "transmission_interval": 100,
                  "ibeacon_transmission_interval": 100,
                  "calibrated_power": 44,
                  "eddystone_transmission_power": 200,
                  "uid_instance_id": "010203040506",
                  "uid_namespace_id": "01020304050607080900",
                  "transmit_uid_frequency": "high",
                  "url_scheme": "https://www.",
                  "url": "gimbal.com",
                  "transmit_url_frequency": "medium",
                  "transmit_tlm_frequency": "low"
                }
                

Delete Beacon Configuration

Description

This API allows a developer to delete a beacon configuration they have previously created in their organization.
Note If the beacon configuration is already assigned to any beacon in their organization then beacon configuration can not be deleted.

HTTP Method

DELETE

Example: DELETE https://manager.gimbal.com/api/beacon_configurations/{configuration_id}

RESPONSE You will receive a 200 OK with an empty body

Get All Beacon Configurations

Description

This API allows a developer to get all beacon configurations owned by developer's organization.

HTTP Method

GET

Example: GET https://manager.gimbal.com/api/beacon_configurations

Sample Response JSON


      [
          {
              "id": 1,
              "name": "TestGimbal",
              "beacon_type": "Gimbal",
              "optimized_for_background": "Foreground or Background",
              "transmission_power": "Recommended",
              "antenna_type": "Recommended"
          },
          {
              "id": 2,
              "name": "testIbeacon",
              "beacon_type": "iBeacon",
              "proximity_uuid": "12456789-1234-5689-5454-645646546544",
              "major": 20,
              "minor": 10,
              "measured_power": "Recommended",
              "antenna_type": "Recommended",
              "transmission_power": -2
          }
      ]
      

Get A Beacon Configuration

Description

This API allows a developer to get the beacon configuration specified in the url.

HTTP Method

GET

Example: GET https://manager.gimbal.com/api/beacon_configurations/{configuration_id}

Sample Response JSON for Gimbal Beacon



        {
            "id": 1,
            "name": "TestGimbal",
            "beacon_type": "Gimbal",
            "optimized_for_background": "Foreground or Background",
            "transmission_power": "Recommended",
            "antenna_type": "Recommended"
        }
      

Sample Response JSON for iBeacon


        {
            "id": 1,
            "name": "testIbeacon",
            "beacon_type": "iBeacon",
            "proximity_uuid": "12456789-1234-5689-5454-645646546544",
            "major": 20,
            "minor": 10,
            "measured_power": "Recommended",
            "antenna_type": "Recommended",
            "transmission_power": -2
        }
      

Update Beacon Configuration

Description

This API allows a developer to update metadata of a beacon configuration.

HTTP Method

PUT

Create Configuration PUT Attributes

Attribute Description
Name Required The developer provided name for the beacon configuration
Beacon Type Required The beacon type for wich the configuration is created. Supported beacon types are Gimbal and iBeacon.
Note Only beacons with firmware version 1.6.1 and above support iBeacon configurations
Optimized For Background Gimbal Beacon Only Optimization flag for beacon detection in background mode. Supported optimization flags are Foreground or Background and Foreground-only
Transmission Power The transmission power (measured in decibels) at which the beacon antenna will transmit once configuration is applied.
Antenna Type The transmission mode in which the beacon antenna will transmit once configuration is applied. Supported antenna types are Omnidirectional and Directional
Proximity UUID Required for iBeacon Proximity UUID is value specific to iBeacon. Please refer to the Apple iOS Dev Center for additional information
Major Required for iBeacon Major is value specific to iBeacon. Please refer to the Apple iOS Dev Center for additional information
Minor Required for iBeacon Minor is value specific to iBeacon. Please refer to the Apple iOS Dev Center for additional information
Measured Power iBeacon Only Measured power is value specific to iBeacon. Please refer to the Apple iOS Dev Center for additional information
Transmission Interval iBeacon Only Transmission Interval is value specific to iBeacon. You can change the transmission interval between 100 and 10,000ms. Please note, altering the transmission interval may make this configuration non-compliant with the iBeacon specification

Example: PUT https://manager.gimbal.com/api/beacon_configurations/{configuration_id}

Sample JSON


      {
          "name":"Beacon Config Name",
          "beacon_type":"iBeacon",
          "transmission_power": xx,
          "antenna_type":"Omnidirectional",
          "proximity_uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "major":x,
          "minor":y,
          "measured_power":yy
      }
                        

RESPONSE You will receive a 200 OK with a JSON response as shown below

Sample JSON Response


      {
          "id":xx,
          "name":"Beacon Config Name",
          "beacon_type":"iBeacon",
          "transmission_power": xx,
          "antenna_type":"Omnidirectional",
          "proximity_uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "major":x,
          "minor":y,
          "measured_power":yy
      }
        

Get All Tags For a Beacon


URL

https://manager.gimbal.com/api/beacons/{factory_id}/tags

Description

This API allows a user to get all tags belonging to a given beacon.

HTTP Method

GET

Sample Response JSON


	{
	    "tags": [
	        "NEW TAG3",
	        "NEW TAG4"
	    ]
	}
      

Create Tags For a Beacon


URL

https://manager.gimbal.com/api/beacons/{factory_id}/tags

Description

This API allows a user to create tags for a given beacon. It will delete all old tags, then create new tags.

HTTP Method

POST

Sample JSON


	{
	    "tags": [
	        "NEW TAG3",
	        "NEW TAG4"
	    ]
	}
	        

Sample Response JSON


	{
	    "tags": [
	        "NEW TAG3",
	        "NEW TAG4"
	    ]
	}
      

Delete All Tags For a Beacon


URL

https://manager.gimbal.com/api/beacons/{factory_id}/tags

Description

This API allows a user to delete all tags belonging to a given beacon.

HTTP Method

DELETE

Sightings Callback


Description

As an application developer you can create rules that trigger the Gimbal Proximity service to inform you of the occurrence of certain sightings. This information is delivered as an HTTP POST originating from the Gimbal Proximity service to the action URL provided in the rule. Below is a description of the attributes you will receive in the sightings callback.

On first sighting of a beacon and a receiver (MBR or PBR) that match your configured rule, we send an arrival and sighted event. When another sighting is received after the configured sighting interval (based on server arrival time of both events), we send out another sighted event. We continue to send sighted events until we do not see sightings for the exit interval duration. We then send a departed event.

Arrival and Sighted events contain sighting information from the first sighting in the sighting packet with the exception of RSSI, which is averaged across all sightings in the packet.

Departure events contain sighting information for the most recent sighting for the beacon and receiver pair.

Dwell time is calculated from the start of the visit until the current sighted event or departure event. It is based on server time when the visit is started and when the event is generated.

RSSI is calculated as an average of the values for the same receiver and transmitter within a short period of time.
Invalid RSSI values are excluded from the average. If all the sightings in the average are invalid the RSSI returned will be zero.

Important This endpoint is tested upon Serve Rule creation. The test is a POST with "Content-Type: application/json" that contains "{}" as the body of the request. For more information about "Rules" please sign into the Gimbal Manager.

HTTP Method

POST
Content-Type: application/json

Sighting POST Attributes

Attribute Description
Receiver Id The unique identifier of the receiver of the sighting
Receiver Name The name of the receiver of the sighting
Receiver Owner Identifier Deprecated The unique identifier of the owner of the receiver of the sighting
Receiver Owner Organization The unique identifier of the organization that owns the receiver of the sighting
Transmitter Id The unique identifier of the sighted transmitter
Transmitter Name The name of the receiver of the sighted transmitter
Transmitter Owner Identifier Deprecated The unique identifier of the owner of the sighted transmitter
Transmitter Owner Organization The unique identifier of the organization that owns the sighted transmitter
Triggering Event The event triggered by the sighting (one of Arrived, Departed, Sighted)
Dwell Time Time in seconds since the Arrived event
Signal Strength The received signal strength indication
Time The date and time of the sighting
Latitude The latitude of the receiver at the time of the sighting if known Important Not published for 'Departed' events
Longitude The longitude of the receiver at the time of the sighting if known Important Not published for 'Departed' events
Accuracy The accuracy of the receiver latitude/longitude at the time of the sighting if known
Location Fix Time The date and time the receiver fixed its latitude/longitude if known
Battery Level The battery level of the transmitter at the time of the sighting if known Important Not published for 'Departed' events
Temperature The temperature of the transmitter at the time of the sighting if known Important Not published for 'Departed' events

Sample JSON


        {
            "receiver_name":"Johns Receiver",
            "receiver_id":"auuid",
            "transmitter_name":"Johns Transmitter",
            "transmitter_id":"auuid",
            "triggering_event": "Sighted",
            "dwell_time": "3818",
            "signal_strength": "-54",
            "time": "2015-06-30 17:49:16",
            "latitude": "32.000000",
            "longitude": "-117.000000",
            "location_accuracy": "65.000000",
            "location_fix_time": "2015-06-30 17:35:40",
            "battery_level": "3",
            "temperature": "72",
            "receiver_owner_organization":"Johns Org",
            "transmitter_owner_organization": "Johns Org"
        }
                        

Push Limit Attributes

Attribute (* is required) Description
*limit The frequency control for the maximum number of push notifications an end user can receive in 24 hours.

Get Push Limit


Description.

This call allows you to retrieve the push limit for a specified application. In this example, "9CB94702B43111E295888476C475FD93" is the ID of the application for which we are getting the daily push limit.

HTTP Method

GET

URL

https://manager.gimbal.com/api/applications/9CB94702B43111E295888476C475FD93/daily_push_limit

Sample Response JSON


    {
        "limit" : 55
    }
                

Create a Push Limit


Description.

This call allows you to create a push limit for a given application. In this example, "9CB94702B43111E295888476C475FD93" is the ID of the application for which we are creating the daily push limit.

HTTP Method

POST

URL

https://manager.gimbal.com/api/applications/9CB94702B43111E295888476C475FD93/daily_push_limit

Sample Request JSON


    {
        "limit" : 55
    }
                

Sample Response JSON


    {
        "limit" : 55
    }
                

Delete a Push Limit


Description.

This call allows you to delete a push limit for a given application. In this example, "9CB94702B43111E295888476C475FD93" is the ID of the application for which we are deleting the daily push limit.

HTTP Method

DELETE

URL

https://manager.gimbal.com/api/applications/9CB94702B43111E295888476C475FD93/daily_push_limit

Response

200 on success

Cleanup Push Tokens


Cleanup APNS push tokens when you have elected to DISABLE the APNS feedback service in the Gimbal Manager Application Push Certificate settings.

Attributes

Attribute (* is required) Data Type Description
*token String The APNS push token
*timestamp Number Unix time the token expired

HTTP Method

DELETE

URL

https://api.gimbal.com/service/push/tokens

Sample Request

curl -X DELETE -H "AUTHORIZATION: Token token=MY-GIMBAL-SERVER-API-KEY" https://api.gimbal.com/service/push/tokens
[{"token":"my_token_1", "timestamp":"1427401595"},{"token":"my_token_2", "timestamp":"1427401595"}]
                

Response

OK (200) HTTP status code if no errors.

Communication Attributes

Attribute (* is required) Description
*name A Communicate Name
*start_date Date a communication starts
*end_date Date a communication ends
id The id of the communication
published A boolean value indicating if the communication has been published

Get All Communications

Description

This call allows you to retrieve all the Communications your organization has defined in the Gimbal Manager.

HTTP Method

GET

URL

https://manager.gimbal.com/api/communications

Sample Response JSON


    [
      {
        "published" : false,
        "id" : 1,
        "start_date" : "2013-04-10",
        "end_date" : "2013-04-17",
        "name" : "My First Communication"
      },
      {
        "published" : true,
        "id" : 2,
        "start_date" : "2013-04-10",
        "end_date" : "2013-04-17",
        "name" : "My Second Communication"
      }
    ]
                                    

Get a Communication


Description.

This call allows you to retrieve a single Communication based on the identifier.

HTTP Method

GET

URL

https://manager.gimbal.com/api/communications/1

Sample Response JSON


    {
        "published" : false,
        "id" : 1,
        "start_date" : "2013-04-10",
        "end_date" : "2013-04-17",
        "name" : "My First Communication"
    }
                                    

Update a Communication


Description

This call allows you to update a Communication based on id.

HTTP Method

PUT

URL

https://manager.gimbal.com/api/communications/1

Sample Request JSON


    {
      "start_date" : "2013-04-18",
      "end_date" : "2013-04-19",
      "name" : "My New Communicate"
    }
                                    

Sample Response JSON


    {
      "published" : false,
      "id" : 9,
      "start_date" : "2013-04-18",
      "end_date" : "2013-04-19",
      "name" : "My New Communicate"
    }
                                    

Create a Communication


Description

This call allows you to create a new Communication for your organization.

HTTP Method

POST

URL

https://manager.gimbal.com/api/communications

Sample Request JSON


    {
      "start_date" : "2013-04-18",
      "end_date" : "2013-04-19",
      "name" : "My New Communicate"
    }
                                    

Sample Response JSON


    {
      "published" : false,
      "id" : 9,
      "start_date" : "2013-04-18",
      "end_date" : "2013-04-19",
      "name" : "My New Communicate"
    }
                                    

Delete a Communication


Description.

This call allows you to delete a single Communication based on the identifier.

HTTP Method

DELETE

URL

https://manager.gimbal.com/api/communications/1

Response

200 on success

Publish a Communication


Description.

This call allows you to publish a single Communication based on the identifier. The communication becomes active once published. A communication can be stopped at anytime by calling the stop method.

* Important: To publish a Communication, a Trigger (Time or Geofence) or an attribute is required. A Notification is also required.

HTTP Method

POST

URL

https://manager.gimbal.com/api/communications/1/publish

Response

200 on success

Stop a Communication


Description.

This call allows you to stop a single Communication based on the identifier.

HTTP Method

POST

URL

https://manager.gimbal.com/api/communications/1/stop

Response

200 on success

Notification Attributes

Attribute (* is required) Description
* android_title The title of the notification that will be sent to Android devices.
* android_description The description of the notification that will be sent to Android devices. Limit to 250 characters.
android_url The url of the content that will be sent to Android devices.
ios_title The title of the notification that will be sent to iOS devices.
* ios_description The description of the notification that will be sent to iOS devices. Limit to 250 characters.
ios_url The url of the content that will be sent to iOS devices.
Deprecated title The title of the notification.
Deprecated description The description of the notification.
Deprecated combine_title_description If set to true, title and description will be concatenated with ":" for time triggered iOS Push Notification.
Otherwise, only description will be used for time triggered iOS Push Notification.
Deprecated url The url of the content.

Get the Notification


Description.

This call allows you to retrieve the notification for a given communication.

HTTP Method

GET

URL

https://manager.gimbal.com/api/communications/1/notification

Sample Response JSON


    {
      "android_title" : "myAndroidTitle",
      "android_description" : "myAndroidDescription",
      "android_url" : "protocol://exampleAndroidUrl",
      "ios_title" : "myiOSTitle",
      "ios_description" : "myiOSDescription",
      "ios_url" : "protocol://exampleiOSUrl",
      "title" : "myAndroidTitle",
      "description" : "myAndroidDescription",
      "url" : "protocol://exampleAndroidUrl",
      "combine_title_description" : false
    }
                                    

Create a Notification


Description.

This call allows you to create a notification for a given communication.
Important Please note that the fields have been updated for this request and you cannot use both deprecated and new parameters in a request.

HTTP Method

POST

URL

https://manager.gimbal.com/api/communications/1/notification

Deprecated Sample Request JSON


    {
      "title" : "myTitle",
      "description" : "myDescription",
      "url" : "protocol://exampleurl",
      "combine_title_description" : true
    }
                

Sample Response JSON


    {
      "android_title" : "myTitle",
      "android_description" : "myDescription",
      "android_url" : "protocol://exampleurl",
      "ios_title" : "myTitle",
      "ios_description" : "myDescription",
      "ios_url" : "protocol://exampleurl",
      "title" : "myTitle",
      "description" : "myDescription",
      "url" : "protocol://exampleurl",
      "combine_title_description" : false
    }
                

New Sample Request JSON


    {
      "android_title" : "myAndroidTitle",
      "android_description" : "myAndroidDescription",
      "android_url" : "protocol://exampleAndroidUrl",
      "ios_title" : "myiOSTitle",
      "ios_description" : "myiOSDescription",
      "ios_url" : "protocol://exampleiOSurl"
    }
                

Sample Response JSON


    {
      "android_title" : "myAndroidTitle",
      "android_description" : "myAndroidDescription",
      "android_url" : "protocol://exampleAndroidUrl",
      "ios_title" : "myiOSTitle",
      "ios_description" : "myiOSDescription",
      "ios_url" : "protocol://exampleiOSUrl",
      "title" : "myAndroidTitle",
      "description" : "myAndroidDescription",
      "url" : "protocol://exampleAndroidUrl",
      "combine_title_description" : false
    }
                

Delete the Notification


Description.

This call allows you to delete the notification for a given communication.

HTTP Method

DELETE

URL

https://manager.gimbal.com/api/communications/1/notification

Response

200 on success

Geofence Target Attributes

Attribute (* is required) Description
*target_ids An array of valid geofence ids. Only numeric values are permitted. Strings such as "All" are not permitted.

For example: you can have a geofence around a shopping mall to trigger a Communicate that tells the end-user to visit a few stores and then get analytics that end-users breached geofences around any of those stores.

Get All Geofence Targets


Description.

This call allows you to retrieve all the geofence targets for a given communication.

HTTP Method

GET

URL

https://manager.gimbal.com/api/communications/1/geofence_targets

Sample Response JSON


    {"target_ids": [33333333333667]}
                

Create Geofence Targets


Description.

This call allows you to create one or more geofence targets for a given communication.

HTTP Method

POST

URL

https://manager.gimbal.com/api/communications/1/geofence_targets

Sample Request JSON


    {"target_ids": [33333333333667]}
                

Sample Response JSON


    {"target_ids": [33333333333667]}

                

Delete All Geofence Targets


Description.

This call allows you to delete all geofence targets for a given communication.

HTTP Method

DELETE

URL

https://manager.gimbal.com/api/communications/1/geofence_targets

Response

200 on success

Time Trigger Attributes

Attribute (* is required) Description
*day of week One of monday tuesday wednesday thursday friday saturday sunday
*time Hour and minute of day in 24 hour format ie 13:00
placeFilter 'anyPlace' or [place-id-1, place-id-2]
Note: In order to create a time trigger, any previous geofence trigger must be removed first.

Get the Time Trigger


Description.

This call allows you to retrieve the time trigger for a given communication.

HTTP Method

GET

URL

https://manager.gimbal.com/api/communications/1/time_trigger

Sample Response JSON with only time triggers


    {
        "monday": "08:00",
        "tuesday": "13:00"
    }
                

Sample Response JSON that triggers time based event only when users are 'AT' any of your places.


    {
        "monday": "08:00",
        "tuesday": "13:00",
        "placeFilter": "anyPlace"
    }
                

Sample Response JSON that triggers time based event only when users are 'AT' one or more of your places with id [1,2,3]


    {
        "monday": "08:00",
        "tuesday": "13:00",
        "placeFilter": [1,2,3]
    }
                

Create a Time Trigger


Description.

This call allows you to create a time trigger for a given communication.

Note In order to create a time trigger, any previous geofence trigger must be removed first.

Important Gimbal Time Trigger Communications may not be Published for up to 15 minutes.

HTTP Method

POST

URL

https://manager.gimbal.com/api/communications/1/time_trigger

Sample Request JSON


    {
        "monday": "08:00",
        "tuesday": "13:00",
        "placeFilter": "anyPlace"
    }
                                    

Sample Response JSON


    {
        "monday": "08:00",
        "tuesday": "13:00",
        "placeFilter": "anyPlace"
    }
                                    

Delete the Time Trigger


Description.

This call allows you to delete the time trigger for a given communication.

HTTP Method

DELETE

URL

https://manager.gimbal.com/api/communications/1/time_trigger

Response

200 on success

Geofence Trigger Attributes

Attribute (* is required) Description
*event_type An Event Type. One of at or left
*locations One or all or an array of valid geofence IDs
delay_in_minutes Allows you to set how long after entry or exit a communication is seen; defaults to null (no delay)
frequency_limit_in_hours Allows you to limit how often a communication is triggered, specified in hours; defaults to null (no limit)
Note: In order to create a geofence trigger, any previous time trigger must be removed first.

Get the Geofence Trigger


Description.

This call allows you to retrieve the geofence trigger for a given communication.

HTTP Method

GET

URL

https://manager.gimbal.com/api/communications/1/geofence_trigger

Sample Response JSON


    {
        "event_type": "at",
        "locations": "all",
        "delay_in_minutes": null,
        "frequency_limit_in_hours": 24
    }
                                    

Create a Geofence Trigger


Description.

This call allows you to create a geofence trigger for a given communication. To create a geofence trigger for a specific location(s), pass the locations as an array of geofence id's. Alternatively, you may pass an array of place UUIDs.

*Note: To set the trigger for all of your geofences, use the "all" option for locations or place

HTTP Method

POST

URL

https://manager.gimbal.com/api/communications/1/geofence_trigger

Sample Request JSON


    {
        "event_type": "at",
        "locations": [16144],
        "delay_in_minutes": 30,
        "frequency_limit_in_hours": null
    }
                                    

Sample Response JSON


    {
        "event_type": "at",
        "locations": [16144],
        "delay_in_minutes": 30,
        "frequency_limit_in_hours": null
    }
                                    

Alternative Sample Request JSON


    {
        "event_type": "at",
        "places": [
            "60992CEB11D64952B39BEAC538652A79", 
            "9A2F4CD50CA048BE9C208162454CDEBC"
        ]
    }
                                    

Alternative Sample Response JSON


    {
        "event_type": "at",
        "places": [
            "60992CEB11D64952B39BEAC538652A79", 
            "9A2F4CD50CA048BE9C208162454CDEBC"
        ],
        "delay_in_minutes": null,
        "frequency_limit_in_hours": null
    }
                                    

Delete the Geofence Trigger


Description.

This call allows you to delete the geofence trigger for a given communication.

HTTP Method

DELETE

URL

https://manager.gimbal.com/api/communications/1/geofence_trigger

Response

200 on success

Time Filter

Time Filter Attributes

Attribute (* is required) Description
*day of week One of monday tuesday wednesday thursday friday saturday sunday
*start time Hour and minute of day in 24 hour format ie 01:00
*end time Hour and minute of day in 24 hour format ie 13:00
Note: In order to create a time filter, a geofence trigger must be present.

Get the Time Filter


Description.

This call allows you to retrieve the time filter for a given communication.

HTTP Method

GET

URL

https://manager.gimbal.com/api/communications/1/geofence_trigger/time_filter

Sample Response JSON


    {
        "monday": {
            "start": "08:00",
            "end": "13:00"
        },
        "tuesday": {
            "start": "08:00",
            "end": "22:00"
        }
    }
                

Create a Time Filter


Description.

This call allows you to create a time trigger for a given communication.

Note: In order to create a time trigger, any previous geofence trigger must be removed first.

HTTP Method

POST

URL

https://manager.gimbal.com/api/communications/1/geofence_trigger/time_filter

Sample Request JSON


      {
          "monday": {
              "start": "08:00",
              "end": "13:00"
          },
          "tuesday": {
              "start": "08:00",
              "end": "22:00"
          }
      }
                                    

Sample Response JSON


      {
          "monday": {
              "start": "08:00",
              "end": "13:00"
          },
          "tuesday": {
              "start": "08:00",
              "end": "22:00"
          }
      }
                                    

Delete the Time Filter


Description.

This call allows you to delete the time filter for a given communication.

HTTP Method

DELETE

URL

https://manager.gimbal.com/api/communications/1/geofence_trigger/time_filter

Response

200 on success

Custom Profile Attributes

Attribute (* is required) Description
*value Value of the key value pair. Limited to 255 characters.
*key Key of the key value pair. Limited to 255 characters.
*operator The operator to compare the attributes. The valid operators are: ["NUM_GREATER_THAN", "NUM_GREATER_THAN_OR_EQUAL", "NUM_LESS_THAN", "NUM_LESS_THAN_OR_EQUAL", "NUM_EQUAL", "NUM_NOT_EQUAL", "STRING_EQUAL", "STRING_NOT_EQUAL"]

Get All Custom Profile Attributes


Description.

This call allows you to retrieve all the Custom Profile Attributes for a given communication.

HTTP Method

GET

URL

https://manager.gimbal.com/api/communications/1/custom_attributes

Sample Response JSON


    {
      "custom_attributes": [
       {
         "value": "3",
         "key": "number_of_visits",
         "operator": "NUM_GREATER_THAN"
       },
       {
         "value" : "mira_mesa",
         "key" : "neighborhood",
         "operator" : "STRING_EQUAL"
       }
      ]
    }
                

Create Custom Profile Attributes


Description.

This call allows you to create one or more Custom Profile Attributes for a given communication.

HTTP Method

POST

URL

https://manager.gimbal.com/api/communications/1/custom_attributes

Sample Request JSON


    {
      "custom_attributes": [
       {
         "value": "3",
         "key": "number_of_visits",
         "operator": "NUM_GREATER_THAN"
       }
      ]
    }
                

Sample Response JSON


    {
      "custom_attributes": [
       {
         "value": "3",
         "key": "number_of_visits",
         "operator": "NUM_GREATER_THAN"
       }
      ]
    }
                

Delete All Custom Profile Attributes


Description.

This call allows you to delete all Custom Profile Attributes for a given communication.

HTTP Method

DELETE

URL

https://manager.gimbal.com/api/communications/1/custom_attributes

Response

200 on success

Get All Communication Attributes


Description.

This call allows you to retrieve all the communication attributes for a given communication.

HTTP Method

GET

URL

https://manager.gimbal.com/api/communications/1/communication_attributes

Sample Response JSON


    {
      "communication_attributes":
       {
         "store_type" : "retail",
         "product_type" : "clothing"
       }
    }
                

Create Communication Attributes


Description.

This call allows you to create one or more communication attributes for a given communication.

HTTP Method

POST

URL

https://manager.gimbal.com/api/communications/1/communication_attributes

Sample Request JSON


    {
      "communication_attributes":
       {
         "store_type" : "retail",
         "product_type" : "clothing"
       }
    }
                

Sample Response JSON


    {
      "communication_attributes":
       {
         "store_type" : "retail",
         "product_type" : "clothing"
       }
    }
                

Delete All Communication Attributes


Description.

This call allows you to delete all communication attributes for a given communication.

HTTP Method

DELETE

URL

https://manager.gimbal.com/api/communications/1/communication_attributes

Response

200 on success