This document describes a Restful server API for interacting with the Gimbal service.
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
The following is the generic list of response status codes used by the API.
HTTP Response Status | Description |
---|---|
200 | Success |
401 | Unauthorized |
422 | Unprocessable Entity |
404 | Resource Not Found |
500 | Unexpected Error |
The following is the list of error codes used by the API.
Error Code | Message |
---|---|
6000 | Not Found |
6001 | Invalid |
6002 | Beacon belongs to another user |
6003 | Beacon belongs to another organization |
9000 | Unknown Error |
This call allows you to retrieve analytics in CSV format for your organization.
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 |
POST
https://manager.gimbal.com/api/export_analytics
{ "start_date" : "2013-01-01", "end_date" : "2013-01-30", "geofence_ids" : [1,2] }
This call allows you to retrieve content related analytics in CSV format for your organization.
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" |
POST
https://manager.gimbal.com/api/content_analytics/contents
{ "start_date" : "2013-01-01", "end_date" : "2013-01-30", "geofence_ids" : [1,2], "communication_ids" : [2, 3], "event_type" : ["CONTENT_CLICKED", "CONTENT_DELIVERED"] }
This call allows you to retrieve analytics in CSV format for your organization. Information regarding a geofence and its associated communications will be displayed.
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 |
POST
https://manager.gimbal.com/api/content_analytics/geofences
{ "start_date" : "2013-01-01", "end_date" : "2013-01-30", "geofence_ids" : [1,2], "communication_ids" : [2, 3] }
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 |
This call allows you to retrieve all applications for your organization.
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
https://manager.gimbal.com/api/applications
[ { "platform" : "android", "name" : "com.myapp.one", "id" : "9CB94702B43111E295888476C475FD93" }, { "platform" : "ios", "name" : "com.myapp.two", "id" : "9CB94702B43111E295888476C475FD55" } ]
Attribute (* is required) | Description |
---|---|
*limit | The frequency control for the maximum number of push notifications an end user can receive in 24 hours. |
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.
GET
https://manager.gimbal.com/api/applications/9CB94702B43111E295888476C475FD93/daily_push_limit
{ "limit" : 55 }
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.
POST
https://manager.gimbal.com/api/applications/9CB94702B43111E295888476C475FD93/daily_push_limit
{ "limit" : 55 }
{ "limit" : 55 }
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.
DELETE
https://manager.gimbal.com/api/applications/9CB94702B43111E295888476C475FD93/daily_push_limit
200 on success
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.
This call allows you to retrieve all the Geofences your organization has defined in the Gimbal Manager.
GET
https://manager.gimbal.com/api/geofences
[{ "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" } }]
This call allows you to retrieve a single Geofence based on the identifier.
GET
https://manager.gimbal.com/api/geofences/1
{ "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" } }
This call allows you to create a new Geofence for your organization.
POST
https://manager.gimbal.com/api/geofences
{ "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": 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" } }
{ "error": { "type": "Unprocessable", "message": "Name is required." } }
This call allows you to update a Geofence for your organization.
PUT
https://manager.gimbal.com/api/geofences/1
{ "name": "Gimbal Headquarters", "placeAttributes": { "key3": "value3" } }
{ "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" } }
{ "error": { "type": "Unprocessable", "message": "Name is required." } }
This call allows you to delete a single Geofence based on the identifier.
DELETE
https://manager.gimbal.com/api/geofences/1
{ "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" } }
*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.
This call allows you to create multiple geofences.
POST
https://manager.gimbal.com/api/bulk_geofences
[{ "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 } ] } }]
[{ "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 } ] } }]
This call allows you to update multiple geofences.
POST
https://manager.gimbal.com/api/bulk_geofences/update
[{ "id": 1, "name": "Gimbal Headquarters" }]
[{ "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" } }]
This call allows you to delete multiple geofences.
POST
https://manager.gimbal.com/api/bulk_geofences/destroy
{ "geofence_ids": [1, 2] }
200 on success
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 interchangeableThis API allows a developer to activate a new beacon for their organization. This beacon must not belong to any other organization in the system.
POST
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
{ "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
{ "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" }
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.
DELETE
Example: DELETE
https://manager.gimbal.com/api/beacons/{factory_id}
RESPONSE You will receive a 200 OK with an empty body
Call this API to retrieve the metadata of a beacon by the given factory identifier.
GET
Example: GET
https://manager.gimbal.com/api/beacons/{factory_id}
{ "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" }
Call this API to retrieve all beacons associated to a specific organization. The organization is the owner of the API key.
GET
Example: GET https://manager.gimbal.com/api/beacons
[ { "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" } ]
This API allows a developer to updated the metadata of a beacon.
PUT
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}
{ "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
{ "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" }
Call this API to retrieve the cuurent configuration of a beacon by the given factory identifier.
GET
Example: GET
https://manager.gimbal.com/api/beacons/{factory_id}/configuration
{ "assigned_configuration": "Configuration assigned to the beacon", "applied_configuration": "Configuration applied to the beacon" }
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 |
https://manager.gimbal.com/api/beacon_configurations
This API allows a developer to get all beacon configurations owned by developer's organization.
GET
[ { "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 } ]
https://manager.gimbal.com/api/beacon_configurations/1/
This API allows a developer to get the beacon configuration specified in the url.
GET
{ "id": 1, "name": "TestGimbal", "beacon_type": "Gimbal", "optimized_for_background": "Foreground or Background", "transmission_power": "Recommended", "antenna_type": "Recommended" }
{ "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 }
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.
POST
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 |
{ "receiver_identifier":"auuid", "receiver_name":"Johns Receiver", "receiver_owner_id":"auuid", "transmitter_identifier":"auuid", "transmitter_name":"Johns Transmitter", "transmitter_owner_id":"auuid" ... }
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.
Property | Value |
---|---|
Client ID | my-client-id |
Client Secret | my-client-secret |
Redirect URI | http://www.myapp.com/callback |
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
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.
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" }
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 ServiceTo 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
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 |
This call allows you to retrieve all the Communications your organization has defined in the Gimbal Manager.
GET
https://manager.gimbal.com/api/communications
[ { "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" } ]
This call allows you to retrieve a single Communication based on the identifier.
GET
https://manager.gimbal.com/api/communications/1
{ "published" : false, "id" : 1, "start_date" : "2013-04-10", "end_date" : "2013-04-17", "name" : "My First Communication" }
This call allows you to update a Communication based on id.
PUT
https://manager.gimbal.com/api/communications/1
{ "start_date" : "2013-04-18", "end_date" : "2013-04-19", "name" : "My New Communicate" }
{ "published" : false, "id" : 9, "start_date" : "2013-04-18", "end_date" : "2013-04-19", "name" : "My New Communicate" }
This call allows you to create a new Communication for your organization.
POST
https://manager.gimbal.com/api/communications
{ "start_date" : "2013-04-18", "end_date" : "2013-04-19", "name" : "My New Communicate" }
{ "published" : false, "id" : 9, "start_date" : "2013-04-18", "end_date" : "2013-04-19", "name" : "My New Communicate" }
This call allows you to delete a single Communication based on the identifier.
DELETE
https://manager.gimbal.com/api/communications/1
200 on success
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.POST
https://manager.gimbal.com/api/communications/1/publish
200 on success
This call allows you to stop a single Communication based on the identifier.
POST
https://manager.gimbal.com/api/communications/1/stop
200 on success
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. |
This call allows you to retrieve the notification for a given communication.
GET
https://manager.gimbal.com/api/communications/1/notification
{ "title" : "myTitle", "description" : "myDescription", "url" : "protocol://exampleurl", "combine_title_description" : true }
This call allows you to create a notification for a given communication.
POST
https://manager.gimbal.com/api/communications/1/notification
{ "title" : "myTitle", "description" : "myDescription", "url" : "protocol://exampleurl", "combine_title_description" : true }
{ "title" : "myTitle", "description" : "myDescription", "url" : "protocol://exampleurl", "combine_title_description" : true }
This call allows you to delete the notification for a given communication.
DELETE
https://manager.gimbal.com/api/communications/1/notification
200 on success
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.
This call allows you to retrieve all the geofence targets for a given communication.
GET
https://manager.gimbal.com/api/communications/1/geofence_targets
{"target_ids": [33333333333667]}
This call allows you to create one or more geofence targets for a given communication.
POST
https://manager.gimbal.com/api/communications/1/geofence_targets
{"target_ids": [33333333333667]}
{"target_ids": [33333333333667]}
This call allows you to delete all geofence targets for a given communication.
DELETE
https://manager.gimbal.com/api/communications/1/geofence_targets
200 on success
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 |
This call allows you to retrieve the time trigger for a given communication.
GET
https://manager.gimbal.com/api/communications/1/time_trigger
{ "monday": "08:00", "tuesday": "13:00" }
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.POST
https://manager.gimbal.com/api/communications/1/time_trigger
{ "monday": "08:00", "tuesday": "13:00" }
{ "monday": "08:00", "tuesday": "13:00" }
This call allows you to delete the time trigger for a given communication.
DELETE
https://manager.gimbal.com/api/communications/1/time_trigger
200 on success
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 |
This call allows you to retrieve the geofence trigger for a given communication.
GET
https://manager.gimbal.com/api/communications/1/geofence_trigger
{ "event_type": "at", "locations": "all" }
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 locationsPOST
https://manager.gimbal.com/api/communications/1/geofence_trigger
{ "event_type": "at", "locations": [16144] }
{ "event_type": "at", "locations": [16144] }
This call allows you to delete the geofence trigger for a given communication.
DELETE
https://manager.gimbal.com/api/communications/1/geofence_trigger
200 on success
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 |
This call allows you to retrieve the time filter for a given communication.
GET
https://manager.gimbal.com/api/communications/1/geofence_trigger/time_filter
{ "monday": { "start": "08:00", "end": "13:00" }, "tuesday": { "start": "08:00", "end": "22:00" } }
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.POST
https://manager.gimbal.com/api/communications/1/geofence_trigger/time_filter
{ "monday": { "start": "08:00", "end": "13:00" }, "tuesday": { "start": "08:00", "end": "22:00" } }
{ "monday": { "start": "08:00", "end": "13:00" }, "tuesday": { "start": "08:00", "end": "22:00" } }
This call allows you to delete the time filter for a given communication.
DELETE
https://manager.gimbal.com/api/communications/1/geofence_trigger/time_filter
200 on success
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. |
This call allows you to retrieve the neighborhoods for a given communication.
GET
https://manager.gimbal.com/api/communications/1/neighborhoods
[ { "campaign_id" : 11, "id" : 2, "source_id" : null, "kind" : "home" }, { "campaign_id" : 11, "id" : 3, "source_id" : null, "kind" : "work" } ]
This call allows you to retrieve a neighborhood for a given communication by the identifier.
GET
https://manager.gimbal.com/api/communications/1/neighborhoods/1
{ "campaign_id" : 1, "id" : 1, "source_id" : null, "kind" : "home" }
This call allows you to create a neighborhood for a given communication.
POST
https://manager.gimbal.com/api/communications/1/neighborhoods
{ "kind" : "work", "source_id" : "1" }
{ "campaign_id" : 11, "id" : 4, "source_id" : 1, "kind" : "work" }
This call allows you to delete a neighborhood for a given communication.
DELETE
https://manager.gimbal.com/api/communications/1/neighborhood/1
200 on success
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"] |
This call allows you to retrieve all the Custom Profile Attributes for a given communication.
GET
https://manager.gimbal.com/api/communications/1/custom_attributes
{ "custom_attributes": [ { "value": "3", "key": "number_of_visits", "operator": "NUM_GREATER_THAN" }, { "value" : "mira_mesa", "key" : "neighborhood", "operator" : "STRING_EQUAL" } ] }
This call allows you to create one or more Custom Profile Attributes for a given communication.
POST
https://manager.gimbal.com/api/communications/1/custom_attributes
{ "custom_attributes": [ { "value": "3", "key": "number_of_visits", "operator": "NUM_GREATER_THAN" } ] }
{ "custom_attributes": [ { "value": "3", "key": "number_of_visits", "operator": "NUM_GREATER_THAN" } ] }
This call allows you to delete all Custom Profile Attributes for a given communication.
DELETE
https://manager.gimbal.com/api/communications/1/custom_attributes
200 on success
This call allows you to retrieve all the communication attributes for a given communication.
GET
https://manager.gimbal.com/api/communications/1/communication_attributes
{ "communication_attributes": { "store_type" : "retail", "product_type" : "clothing" } }
This call allows you to create one or more communication attributes for a given communication.
POST
https://manager.gimbal.com/api/communications/1/communication_attributes
{ "communication_attributes": { "store_type" : "retail", "product_type" : "clothing" } }
{ "communication_attributes": { "store_type" : "retail", "product_type" : "clothing" } }
This call allows you to delete all communication attributes for a given communication.
DELETE
https://manager.gimbal.com/api/communications/1/communication_attributes
200 on success
This call allows you to retrieve all the available profile attributes.
GET
https://manager.gimbal.com/api/profile_definitions
{ "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+"] } }
This call allows you to retrieve the audience filter for a given communication.
GET
https://manager.gimbal.com/api/communications/1/audience_filter
{ "profile_attributes": { "Gender": ["Female"], "Kids": ["Has Kids"] } }
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.POST
https://manager.gimbal.com/api/communications/1/audience_filter
{ "profile_attributes": { "Gender": ["Female"], "Kids": ["Has Kids"] } }
{ "profile_attributes": { "Gender": ["Female"], "Kids": ["Has Kids"] } }
This call allows you to delete the audience filter for a given communication.
DELETE
https://manager.gimbal.com/api/communications/1/audience_filter
200 on success