Gimbal 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

Export analytics with filters


Description.

This call allows you to retrieve analytics in CSV format for your organization.

Note: if no geofence_ids is passed in then geofences will not be used as filtering

Export Analytics Attributes

Attribute (* is required) Description
*start_date Start date for the filter
*end_date End date for the filter
geofence_ids Geofences to be filtered on

HTTP Method

POST

URL

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

Sample Request JSON


    {
        "start_date" : "2013-01-01",
        "end_date" : "2013-01-30",
        "geofence_ids" : [1,2]
    }
                

Export content analytics with filters


Description.

This call allows you to retrieve content related analytics in CSV format for your organization.

Note: if no geofence_ids is passed in then geofences will not be used as filtering

Export Content Analytics Attributes

Attribute (* is required) Description
start_date Start date for the filter
end_date End date for the filter
geofence_ids Geofences to be filtered on
communication_ids Communications to be filtered on
event_type Could be "CONTENT_CLICKED", "CONTENT_NOTIFIED", "CONTENT_DELIVERED", "CONTENT_DISPLAYED"

HTTP Method

POST

URL

https://manager.gimbal.com/api/content_analytics/contents

Sample Request JSON


    {
        "start_date" : "2013-01-01",
        "end_date" : "2013-01-30",
        "geofence_ids" : [1,2],
        "communication_ids" : [2, 3],
        "event_type" : ["CONTENT_CLICKED", "CONTENT_DELIVERED"]

    }
                

Export content geofence analytics with filters


Description.

This call allows you to retrieve analytics in CSV format for your organization. Information regarding a geofence and its associated communications will be displayed.

Note: if no geofence_ids is passed in then geofences will not be used as filtering

Export Content Geofence Analytics Attributes

Attribute (* is required) Description
start_date Start date for the filter
end_date End date for the filter
geofence_ids Geofences to be filtered on
communication_ids Communications to be filtered on

HTTP Method

POST

URL

https://manager.gimbal.com/api/content_analytics/geofences

Sample Request JSON


    {
        "start_date" : "2013-01-01",
        "end_date" : "2013-01-30",
        "geofence_ids" : [1,2],
        "communication_ids" : [2, 3]
    }
                

Application Attributes

Attribute (* is required) Description
platform Platform on which the application will run
name The bundle id or package name of the application
id API key of the application

Get all Applications


Description.

This call allows you to retrieve all applications for your organization.

Application Attributes

Attribute (* is required) Description
platform Platform on which the application will run
name The bundle id or package name of the application
id API key of the application

HTTP Method

GET

URL

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

Sample Response JSON


    [
        {
            "platform" : "android",
            "name" : "com.myapp.one",
            "id" : "9CB94702B43111E295888476C475FD93"
        },
        {
            "platform" : "ios",
            "name" : "com.myapp.two",
            "id" : "9CB94702B43111E295888476C475FD55"
        }
    ]
                

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

Geofence Attributes


Description

The following is the list of attributes supported by the Geofences API calls. The placeAttributes field is a metadata field of key value pairs. An unlimited number of these key value pairs is permitted. These key value pairs can contain whatever information is desired about a geofence. Ex: [k,v] = ["place_type", "mall"]

*name The name for the geofence.
addressLineOne The standard street address.
placeAttributes
*key Value for the key value pair.
... Unlimited amount of key value pairing

and either

*geoFenceCircle
*radius The radius of the circle in meters.
*location
*latitude The latitude of the center point.
*longitude The longitude of the center point.

or

*geoFencePolygon
*locations
*latitude The latitude of the first point in the polygon.
*longitude The longitude of the first point in the polygon.
*latitude The latitude of the second point in the polygon.
*longitude The longitude of the second point in the polygon.
*latitude The latitude of the nth point in the polygon.
*longitude The longitude of the nth point in the polygon.

(*) denotes the the field is required.

A Geofence represents a virtual boundary around a physical location. It may be either Radial or Polygonal. A radial geofence is simply a circle around a specific point on the globe, where the center is a latitude/longitude pair, and the size is determined by a radius in meters. A polygonal geofence is a shape drawn around a location, utilizing a set of points which are latitude/longitude pairs.

Get All Geofences


Description

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

HTTP Method

GET

URL

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

Sample Response JSON


    [{
        "id": 1
        "name": "Gimbal HQ",
        "addressLineOne": "5775 Morehouse Drive, San Diego CA 92121",
        "geoFenceCircle": {
            "radius": 100,
            "visibility": "ORGANIZATION",
            "location": {
                "latitude": 32.89494374592149,
                "longitude": -117.19603832579497
            }
        },
        "placeAttributes": {
            "key1": "value1",
            "key2": "value2"
        }
    },
    {
        "id": 3291
        "name": "Gimbal R&D",
        "addressLineOne": "5665 Morehouse Drive, San Diego CA 92121",
        "geoFencePolygon": {
            "visibility": "ORGANIZATION",
            "locations": [
                {
                    "latitude": 32.8953153522896,
                    "longitude": -117.19559844351653
                },
                {
                    "latitude": 32.8954009341414,
                    "longitude": -117.19516929007415
                },
                {
                    "latitude": 32.89564867061472,
                    "longitude": -117.1949815354431
                },
                {
                    "latitude": 32.89545949009762,
                    "longitude": -117.19463284827117
                },
                {
                    "latitude": 32.894986537037255,
                    "longitude": -117.19496544218902
                },
                {
                    "latitude": 32.894864920127866,
                    "longitude": -117.19554479933623
                }
            ]
        },
        "placeAttributes": {
            "key1": "value1",
            "key2": "value2"
        }
    }]
                

Note In case of imported PUBLIC geofences, this API will not return the location details for the geofence. A sample json response for imported PUBLIC geofences is shown below.


    [{
        "id": 1,
        "name": "Gimbal HQ",
        "geoFenceCircle": {
            "radius": 100,
            "visibility": "PUBLIC"
        },
        "placeAttributes": {
            "key1": "value1",
            "key2": "value2"
        }
    },
    {
        "id": 3291,
        "name": "Gimbal R&D",
        "geoFencePolygon": {
           "visibility": "PUBLIC" 
        },
        "placeAttributes": {
            "key1": "value1",
            "key2": "value2"
        }
    }]
    

Get a Geofence


Description.

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

HTTP Method

GET

URL

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

Sample Response JSON


    {
        "id": 1
        "name": "Gimbal HQ",
        "addressLineOne": "5775 Morehouse Drive, San Diego CA 92121",
        "geoFenceCircle": {
            "radius": 100,
            "visibility": "ORGANIZATION",
            "location": {
                "latitude": 32.89494374592149,
                "longitude": -117.19603832579497
            }
        },
        "placeAttributes": {
            "key1": "value1",
            "key2": "value2"
        }
    }
                

Note In case of imported PUBLIC geofences, this API will not return the location details for the geofence. A sample json response for imported PUBLIC geofence is shown below.


    {
        "id": 1,
        "name": "Gimbal HQ Public Fence",
        "geoFenceCircle": {
            "radius": 100,
            "visibility": "PUBLIC"
        },
        "placeAttributes": {
            "key1": "value1",
            "key2": "value2"
        }
    }
    

Create a Geofence


Description

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

HTTP Method

POST

URL

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

Sample Request JSON


    {
        "name": "Gimbal HQ",
        "addressLineOne": "5775 Morehouse Drive, San Diego CA 92121",
        "geoFenceCircle": {
            "radius": 100,
            "location": {
                "latitude": 32.89494374592149,
                "longitude": -117.19603832579497
            }
        },
        "placeAttributes": {
            "key1": "value1",
            "key2": "value2"
        }
    }
                

Sample Response JSON


    {
        "id": 1
        "name": "Gimbal HQ",
        "addressLineOne": "5775 Morehouse Drive, San Diego CA 92121",
        "geoFenceCircle": {
            "radius": 100,
            "location": {
                "latitude": 32.89494374592149,
                "longitude": -117.19603832579497
            }
        },
        "placeAttributes": {
            "key1": "value1",
            "key2": "value2"
        }
    }
                

Sample Error Response JSON


    {
        "error": {
            "type": "Unprocessable",
            "message": "Name is required."
        }
    }
                

Update a Geofence


Description

This call allows you to update a Geofence for your organization.

HTTP Method

PUT

URL

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

Sample Request JSON


    {
        "name": "Gimbal Headquarters",
        "placeAttributes": {
            "key3": "value3"
        }
    }
                

Sample Response JSON


    {
        "id": 1
        "name": "Gimbal Headquarters",
        "addressLineOne": "5775 Morehouse Drive, San Diego CA 92121",
        "geoFenceCircle": {
            "radius": 100,
            "location": {
                "latitude": 32.89494374592149,
                "longitude": -117.19603832579497
            }
        },
        "placeAttributes": {
            "key3": "value3"
        }
    }
                

Sample Error Response JSON


    {
        "error": {
            "type": "Unprocessable",
            "message": "Name is required."
        }
    }
                

Delete a Geofence


Description.

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

HTTP Method

DELETE

URL

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

Sample Response JSON


    {
        "id": 1
        "name": "Gimbal Headquarters",
        "addressLineOne": "5775 Morehouse Drive, San Diego CA 92121",
        "geoFenceCircle": {
            "radius": 100,
            "location": {
                "latitude": 32.89494374592149,
                "longitude": -117.19603832579497
            }
        },
        "placeAttributes": {
            "key3": "value3"
        }
    }
                

Bulk Geofences Attributes

*name The name for the geofence.
addressLineOne The standard street address.
placeAttributes
*key Value for the key value pair.
... Unlimited amount of key value pairing

and either

*geoFenceCircle
*radius The radius of the circle in meters.
*location
*latitude The latitude of the center point.
*longitude The longitude of the center point.

or

*geoFencePolygon
*locations
*latitude The latitude of the first point in the polygon.
*longitude The longitude of the first point in the polygon.
*latitude The latitude of the second point in the polygon.
*longitude The longitude of the second point in the polygon.
*latitude The latitude of the nth point in the polygon.
*longitude The longitude of the nth point in the polygon.

(*) denotes the the field is required.

Create Bulk Geofences


Description.

This call allows you to create multiple geofences.

HTTP Method

POST

URL

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

Sample Request JSON


    [{
        "name": "Gimbal HQ",
        "addressLineOne": "5775 Morehouse Drive, San Diego CA 92121",
        "geoFenceCircle": {
            "radius": 100,
            "location": {
                "latitude": 32.89494374592149,
                "longitude": -117.19603832579497
            }
        },
        "placeAttributes": {
            "key1": "value1",
            "key2": "value2"
        }
    },
    {
        "name": "Gimbal R&D",
        "addressLineOne": "5665 Morehouse Drive, San Diego CA 92121",
        "geoFencePolygon": {
            "locations": [
                {
                    "latitude": 32.8953153522896,
                    "longitude": -117.19559844351653
                },
                {
                    "latitude": 32.8954009341414,
                    "longitude": -117.19516929007415
                },
                {
                    "latitude": 32.89564867061472,
                    "longitude": -117.1949815354431
                },
                {
                    "latitude": 32.89545949009762,
                    "longitude": -117.19463284827117
                },
                {
                    "latitude": 32.894986537037255,
                    "longitude": -117.19496544218902
                },
                {
                    "latitude": 32.894864920127866,
                    "longitude": -117.19554479933623
                }
            ]
        }
    }]
                

Sample Response JSON


    [{
        "id": 1
        "name": "Gimbal HQ",
        "addressLineOne": "5775 Morehouse Drive, San Diego CA 92121",
        "geoFenceCircle": {
            "radius": 100,
            "location": {
                "latitude": 32.89494374592149,
                "longitude": -117.19603832579497
            }
        },
        "placeAttributes": {
            "key1": "value1",
            "key2": "value2"
        }
    },
    {
        "id": 2
        "name": "Gimbal R&D",
        "addressLineOne": "5665 Morehouse Drive, San Diego CA 92121",
        "geoFencePolygon": {
            "locations": [
                {
                    "latitude": 32.8953153522896,
                    "longitude": -117.19559844351653
                },
                {
                    "latitude": 32.8954009341414,
                    "longitude": -117.19516929007415
                },
                {
                    "latitude": 32.89564867061472,
                    "longitude": -117.1949815354431
                },
                {
                    "latitude": 32.89545949009762,
                    "longitude": -117.19463284827117
                },
                {
                    "latitude": 32.894986537037255,
                    "longitude": -117.19496544218902
                },
                {
                    "latitude": 32.894864920127866,
                    "longitude": -117.19554479933623
                }
            ]
        }
    }]
                

Update Bulk Geofences


Description.

This call allows you to update multiple geofences.

HTTP Method

POST

URL

https://manager.gimbal.com/api/bulk_geofences/update

Sample Request JSON


    [{
        "id": 1,
        "name": "Gimbal Headquarters"
    }]
                

Sample Response JSON


    [{
        "id": 1
        "name": "Gimbal Headquarters",
        "addressLineOne": "5775 Morehouse Drive, San Diego CA 92121",
        "geoFenceCircle": {
            "radius": 100,
            "location": {
                "latitude": 32.89494374592149,
                "longitude": -117.19603832579497
            }
        },
        "placeAttributes": {
            "key1": "value1",
            "key2": "value2"
        }
    }]
                

Delete Bulk Geofences


Description.

This call allows you to delete multiple geofences.

HTTP Method

POST

URL

https://manager.gimbal.com/api/bulk_geofences/destroy

Sample Request JSON


    {
        "geofence_ids":
            [1, 2]
    }
                

Response

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

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

Sample JSON


    {
        "factory_id":"XXXX-YYYYY",
        "name":"John's Beacon",
        "latitude":XX.XXXXXX,
        "longitude":YY.YYYYYY,
        "config_id":abcd,
        "visibility": "private"
    }
                        

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

Sample JSON Response

    
    {
        "factory_id": "XXXX-YYYYY",
        "icon_url": "http://localhost/assets/fallback/default_icon.png",
        "name": "John's Beacon",
        "latitude": XX.XXXXXX,
        "longitude": YY.YYYYYY,
        "visibility": "Private",
        "battery_level": "Battery Level of the Beacon",
        "hardware": "Hardware type of the Beacon"
    }
                        

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


    {
        "factory_id": "XXXX-YYYYY",
        "icon_url": "http://localhost/assets/fallback/default_icon.png",
        "name": "John's Beacon",
        "latitude": XX.XXXXXX,
        "longitude": YY.YYYYYY,
        "visibility": "Private",
        "battery_level": "Battery Level of the Beacon",
        "hardware": "Hardware type of the Beacon"
    }
                        

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

Sample JSON Response


    [
        {
            "factory_id": "XXXX-ZZZZZ",
            "icon_url": "http://localhost/assets/fallback/default_icon.png",
            "name": "John's Beacon one",
            "latitude": XX.XXXXXX,
            "longitude": YY.YYYYYY,
            "visibility": "Private",
            "battery_level": "Battery Level of the Beacon",
            "hardware": "Hardware type of the Beacon"
        },
        {
            "factory_id": "XXXX-YYYYY",
            "icon_url": "http://localhost/assets/fallback/default_icon.png",
            "name": "John's Beacon two",
            "latitude": XX.XXXXXX,
            "longitude": YY.YYYYYY,
            "visibility": "Public",
            "battery_level": "Battery Level of the Beacon",
             "hardware": "Hardware type of the Beacon"
        }
     ]   
                        

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

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

Sample JSON


    {
        "name":"John's Beacon",
        "latitude":XX.XXXXXX,
        "longitude":YY.YYYYYY,
        "config_id":abcd,
        "visibility": "private"
    }
                        

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

Sample JSON Response

    
    {
        "factory_id": "XXXX-YYYYY",
        "icon_url": "http://localhost/assets/fallback/default_icon.png",
        "name": "John's Beacon",
        "latitude": XX.XXXXXX,
        "longitude": YY.YYYYYY,
        "visibility": "Private",
        "battery_level": "Battery Level of the Beacon",
        "hardware": "Hardware type of the Beacon"
    }
    

Get Beacon Configuration By Factory Id

Description

Call this API to retrieve the cuurent 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


Beacon Configuration Attributes

Attribute Description
id The unique identifier of the beacon configuration
name The user provided name for the beacon configuration
beacon_type The beacon type for the beacon configuration. Either Gimbal or iBeacon
optimized for background Displays if the beacon configuration is optimized for background and foreground or foreground only
transmission power The transmission power for the beacon configuration
antenna type The antenna type for the beacon configuration

Get All Beacon Configurations


URL

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

Description

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

HTTP Method

GET

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


URL

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

Description

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

HTTP Method

GET

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
        }
      

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.

Important For more information about "Rules" please sign into the Gimbal Manager.

HTTP Method

POST

Sighting POST Attributes

Attribute Description
Receiver Identifier The unique identifier of the receiver of the sighting
Receiver Name The name of the receiver of the sighting
Receiver Owner Identifier The unique identifier of the owner of the receiver of the sighting
Transmitter Identifier The unique identifier of the sighted transmitter
Transmitter Name The name of the receiver of the sighted transmitter
Transmitter Owner Identifier The unique identifier of the owner of 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
Longitude The longitude of the receiver at the time of the sighting if known
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
Temperature The temperature of the transmitter at the time of the sighting if known

Sample JSON


        {
        "receiver_identifier":"auuid",
        "receiver_name":"Johns Receiver",
        "receiver_owner_id":"auuid",
        "transmitter_identifier":"auuid",
        "transmitter_name":"Johns Transmitter",
        "transmitter_owner_id":"auuid"
        ...
        }
                        

OAuth


OAuth Call Flow

Description

Gimbal Proximity implements OAuth 2.0 for API authorization with third party applications. The following is an example of a fictitious web application leveraging OAuth to integrate with Gimbal Proximity. To create an actual application use the Gimbal Manager.

For details about OAuth 2.0 please review the specification.

Sample Application Properties

Property Value
Client ID my-client-id
Client Secret my-client-secret
Redirect URI http://www.myapp.com/callback

Authorization Request

The first step is to initiate an Authorization Request with Gimbal Proximity.

GET https://getfyx.com/oauth/authorize?response_type=code&client_id=my-client-id&redirect_uri=http://www.myapp.com/callback

If the user authorizes your application you will get a callback that looks like this.

http://www.myapp.com/callback?code=an-oauth-code

Authorization Grant

The next step is to request the token with the code you received.

POST https://getfyx.com/oauth/token


        {
            "code": "an-oauth-code",
            "client_id": "my-client-id",
            "grant_type": "authorization_code",
            "client_secret": "my-client-secret",
            "redirect_uri": "http://www.myapp.com/callback"
        }
                            

RESPONSE


        {
            "token_type": "bearer",
            "refresh_token": "my-refresh-token",
            "access_token": "my-token",
            "expires_in": null
        }
                            

Given the authorization token, you can make calls to protected Gimbal Proximity APIs.

Token Information

The authorization token is associated with an Gimbal Proximity user account. You can use the token to query for the authorized user's information.

For example you can retrieve the User Identifier for a token.

GET https://getfyx.com/oauth/token/info?access_token=my-token

RESPONSE


            {
                "user_id": "a-user-id"
            }
                            

Revoke Token

You may also revoke a token which will de-authorize the application from the Gimbal Proximity service. Once the token is revoked the application will need to restart the OAuth flow to regain access to protected APIs.

Note Revoking a token only de-authorizes an application and leaves the user logged-in to the Gimbal Proximity Service

To revoke a token perform the following.

DELETE https://getfyx.com/oauth/token?access_token=my-token

RESPONSE You will receive a 200 OK with an empty JSON response

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
*title The title of the notification.
*description The description of the notification.
*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.
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


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

Create a Notification


Description.

This call allows you to create a notification for a given communication.

HTTP Method

POST

URL

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

Sample Request JSON


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

Sample Response JSON


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

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


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

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.

HTTP Method

POST

URL

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

Sample Request JSON


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

Sample Response JSON


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

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

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.

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

HTTP Method

POST

URL

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

Sample Request JSON


    {
        "event_type": "at",
        "locations": [16144]
    }
                                    

Sample Response JSON


    {
        "event_type": "at",
        "locations": [16144]
    }
                                    

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

Neighborhood Attributes

Attribute (* is required) Description
*kind The type of neighborhood. Either home or work.
*source_id This is the id of the neighborhood you wish to target. This id comes from the source of the neighborhood database.
id The id of the neighborhood attribute.
communication id The communication id for the neighborhood.

Get All Neighborhoods


Description.

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

HTTP Method

GET

URL

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

Sample Response JSON


    [
      {
        "campaign_id" : 11,
        "id" : 2,
        "source_id" : null,
        "kind" : "home"
      },
      {
        "campaign_id" : 11,
        "id" : 3,
        "source_id" : null,
        "kind" : "work"
      }
    ]
                

Get a Neighborhood


Description.

This call allows you to retrieve a neighborhood for a given communication by the identifier.

HTTP Method

GET

URL

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

Sample Response JSON


      {
        "campaign_id" : 1,
        "id" : 1,
        "source_id" : null,
        "kind" : "home"
      }
                

Create a Neighborhood


Description.

This call allows you to create a neighborhood for a given communication.

HTTP Method

POST

URL

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

Sample Request JSON


    {
      "kind" : "work",
      "source_id" : "1"
    }
                

Sample Response JSON


    {
      "campaign_id" : 11,
      "id" : 4,
      "source_id" : 1,
      "kind" : "work"
    }
                

Delete a Neighborhood


Description.

This call allows you to delete a neighborhood for a given communication.

HTTP Method

DELETE

URL

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

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

Audience Filter

Note: In order to create an audience filter, a communication id must be present.
You can call the following URL to get the list of all available profile attributes that you can create an audience filter against.

Get all the profile attributes


Description.

This call allows you to retrieve all the available profile attributes.

HTTP Method

GET

URL

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

Sample Response JSON

    {
        "profile_attributes": {
            "Education": ["No College", "College", "Grad School"],
            "Age": ["18 - 24", "25 - 34", "35 - 44", "45 - 55", "55+"],
            "Ethnicity": ["Caucasian", "African American", "Asian", "Hispanic", "Other"],
            "Kids": ["No Kids","Has Kids"],
            "Gender": ["Male", "Female"],
            "Interests": ["Getting from here to there", "Biking", "Automotive", "Automotive.Cars"],
            "Income": ["$0 - 30k", "$30 - 60k", "$60 - 100k", "100k+"]
        }
    }
                

Get the Audience Filter


Description.

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

HTTP Method

GET

URL

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

Sample Response JSON

    {   
        "profile_attributes": {
            "Gender": ["Female"],
            "Kids": ["Has Kids"]
        }
    }
                

Create an Audience Filter


Description.

This call allows you to create an audience filter for a given communication.

Note: In order to create an audience filter, you need a valid communication and the available profile attributes.

HTTP Method

POST

URL

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

Sample Request JSON

    {
        "profile_attributes": {
            "Gender": ["Female"],
            "Kids": ["Has Kids"]
        }
    }                                    

Sample Response JSON

    {
        "profile_attributes": {
            "Gender": ["Female"],
            "Kids": ["Has Kids"]
        }
    }                                    

Delete the Audience Filter


Description.

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

HTTP Method

DELETE

URL

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

Response

200 on success