RESTful API

Create Beacon

Overview

A Beacon it's a small device that constantly will be broadcasting some information to its surroundings (indoor use, low distant range) using Bluetooth. This method allows you to attach your information to a specific beacon, so users that enter in the beacon's range will receive the desired information.

Beacons have caused a great impact on markets and department stores. You can learn more about Bluetooth and Beacons here.

URL

Parameters on the following URL are inside braces { } 

{base_url}/rest/api/tools/createBeacon/{instanceId}/{name}/{uuid}/{major}/{minor}/{manufacturer}/{distance}/{eventType}/{msgTitle}/{msgContent}/{rules}/{appName}/{publicKey}/{signature}
Parameter Name Description
instanceId An instance id is the workspace identification number, if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
name The desired beacon's name. This parameter must be Base64 encoded. You can't exceed 80 characters
uuid Beacon's UUID value. This value comes with the device
major Beacon's MAJOR VERSION value. This value comes with the device
minor Beacon's MINOR VERSION value. This value comes with the device
manufacturer Beacon's Manufacturer. Each manufacturer could provide a proprietary mechanism to modify UUID, Major & Minor values
distance User's distance to the beacon needed to trigger the event. Valid values are: INMEDIATE | NEAR | FAR
eventType The type of event that triggers the Beacon. Valid values are: ENTER | EXIT | ENTER-EXIT
msgTitle
OPTIONAL 		A title for this message. This parameter must be Base64 encoded. You can't exceed 80 characters.
Write null to ignore
msgContent
OPTIONAL 		The content of the message per se. This parameter must be Base64 encoded. You can't exceed 200 characters.
Write null to ignore
rules
OPTIONAL 		Powerful mechanism of rules. For more information please read the RULE parameter appendix
Write null to ignore
appName Your App's name which will receive your Push Notifications
publicKey The public key to access this API. if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
signature The unique SHA256 signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our Java Example

Response

The Response XML is divided in a static part and a dynamic one, we call it dynamic because it will vary depending on the method you invoke. Please read our Response XML Basics section if you want to learn more about the response parts. 

<input>createBeacon</input>
<status>OK</status>
<description>Completed</description>
<result>
	<Beacon>
		<regionId>e4f1f80f-eb8f-4b05-a40a-803f2f212054</regionId>
		<name>BeaconTest</name>
		<type>BEACON</type>
		<eventType>ENTER</eventType>
		<msgTitle>Beacon subject</msgTitle>
		<msgContent>Beacon text</msgContent>
		<appName>OgangiTest</appName>
		<timezone>America/Caracas</timezone>
		<update>2014-06-08T23:46:12.805-04:30</update>
		<uuid>B9407F30-F5F8-466E-AFF9-25556B57FE6D</uuid>
		<major>8888</major>
		<minor>3333</minor>
		<manufacturer>ESTIMOTE</manufacturer>
		<distance>NEAR</distance>
	<Beacon>
</result>

Please be aware that the <Beacon> object it's generic and may apply to other responses in other methods.

Result parameters
Parameter Name Description Possible Values
Beacon.regionId Region's unique identifier Text
Beacon.name Beacon's name Text
Beacon.type Location Based Campaign's type. Always BEACON for this method
Beacon.eventType The type of event that triggers the beacon. Valid values are: ENTER | EXIT | ENTER-EXIT
Beacon.msgTitle The message's title to be deliver when the beacon fires. Text
Beacon.msgContent The message's content to be deliver when the beacon fires. Text
Beacon.appName The identifier of the application, who will monitor the beacon. Text
Beacon.timezone Timezone used Text
Beacon.update The date mark when the last update occurs A formatted date string: yyyy-MM-dd'T'HH:mm:ss.SSSZZ
For more information please review the pattern letters quick reference
uuid Beacon's UUID value. Text
major Beacon's MAJOR VERSION value. Text
minor Beacon's MINOR VERSION value. Text
manufacturer Beacon's Manufacturer. Text
distance User's distance to the beacon needed to trigger the event. INMEDIATE
NEAR
FAR

Remove Beacon

Overview

This function will delete a registered beacon region.

This function send a special push message to every device registered with your App so it can delete the Beacon on the device's platform.

URL

Parameters on the following URL are inside braces { } 

{base_url}/rest/api/tools/removeBeacon/{instanceId}/{regionId}/{appName}/{publicKey}/{signature}
Parameter Name Description
instanceId An instance id is the workspace identification number, if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
regionId The identifier of the region that trigger the event.
appName The App's name which will receive your Push Notifications
publicKey The public key to access this API. if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
signature The unique SHA256 signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our Java Example

Response

The Response XML is divided in a static part and a dynamic one, we call it dynamic because it will vary depending on the method you invoke. Please read our Response XML Basics section if you want to learn more about the response parts. 

<input>removeBeacon</input>
<status>OK</status>
<description>Completed</description>
<result>
	<transactionResult> 
		<successful>true</successful>
		<message>Region removed</message>
	</transactionResult>
</result>
Result parameters
Parameter Name Description Possible Values
successful Indicates if the region was deleted or not true
false
message A human readable explanation Text

Retrieve Beacon

Overview

This method will list all client's Beacons.

URL

Parameters on the following URL are inside braces { } 

{base_url}/rest/api/tools/getBeacons/{instanceId}/{appName}/{publicKey}/{signature}
Parameter Name Description
instanceId An instance id is the workspace identification number, if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
appName The App's name which will receive your Push Notifications
publicKey The public key to access this API. if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
signature The unique SHA256 signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our Java Example

Response

The Response XML is divided in a static part and a dynamic one, we call it dynamic because it will vary depending on the method you invoke. Please read our Response XML Basics section if you want to learn more about the response parts. 

<input>getBeacons</input>
<status>OK</status>
<description>Completed</description>
<result>
	<BeaconRegions>
		<Beacon>
			<regionId>e4f1f80f-eb8f-4b05-a40a-803f2f212054</regionId>
			<name>BeaconTest</name>
			<type>BEACON</type>
			<eventType>ENTER</eventType>
			<msgTitle>Beacon subject</msgTitle>
			<msgContent>Beacon text</msgContent>
			<appName>OgangiTest</appName>
			<timezone>America/Caracas</timezone>
			<update>2014-06-08T23:46:12.805-04:30</update>
			<uuid>B9407F30-F5F8-466E-AFF9-25556B57FE6D</uuid>
			<major>8888</major>
			<minor>3333</minor>
			<manufacturer>ESTIMOTE</manufacturer>
			<distance>NEAR</distance>
		<Beacon>
 
		...
 
		<Beacon>
			<regionId>8s37da21-lof3-8a9d-01nf-kai23laod9000</regionId>
			<name>BeaconTest2</name>
			<type>BEACON</type>
			<eventType>ENTER</eventType>
			<msgTitle>Beacon subject2</msgTitle>
			<msgContent>Beacon text2</msgContent>
			<appName>OgangiTest</appName>
			<timezone>America/Caracas</timezone>
			<update>2014-04-08T13:49:11.304-04:30</update>
			<uuid>9KIJ82HD-8SD7-01LD-JAUW-01JDLAO98E9S</uuid>
			<major>8888</major>
			<minor>3333</minor>
			<manufacturer>ESTIMOTE</manufacturer>
			<distance>NEAR</distance>
		<Beacon>
	</BeaconRegions>
</result>

Please be aware that the <Beacon> object it's generic and may apply to other responses in other methods.

Result parameters
Parameter Name Description Possible Values
Beacon.regionId Region's unique identifier Text
Beacon.name Beacon's name Text
Beacon.type Location Based Campaign's type. Always BEACON for this method
Beacon.eventType The type of event that triggers the beacon. Valid values are: ENTER | EXIT | ENTER-EXIT
Beacon.msgTitle The message's title to be deliver when the beacon fires. Text
Beacon.msgContent The message's content to be deliver when the beacon fires. Text
Beacon.appName The identifier of the application, who will monitor the beacon. Text
Beacon.timezone Timezone used Text
Beacon.update The date mark when the last update occurs A formatted date string: yyyy-MM-dd'T'HH:mm:ss.SSSZZ
For more information please review the pattern letters quick reference
uuid Beacon's UUID value. Text
major Beacon's MAJOR VERSION value. Text
minor Beacon's MINOR VERSION value. Text
manufacturer Beacon's Manufacturer. Text
distance User's distance to the beacon needed to trigger the event. INMEDIATE
NEAR
FAR

Retrieve Beacon by Id

Overview

Given a Beacon's Id retrieve the information about it

URL

Parameters on the following URL are inside braces { } 

{base_url}/rest/api/tools/getBeaconById/{instanceId}/{regionId}/{publicKey}/{signature}
Parameter Name Description
instanceId An instance id is the workspace identification number, if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
regionId The Beacon's identifier to look for
publicKey The public key to access this API. if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
signature The unique SHA256 signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our Java Example

Response

The Response XML is divided in a static part and a dynamic one, we call it dynamic because it will vary depending on the method you invoke. Please read our Response XML Basics section if you want to learn more about the response parts. 

<input>getBeaconById</input>
<status>OK</status>
<description>Completed</description>
<result>
	<Beacon>
		<regionId>e4f1f80f-eb8f-4b05-a40a-803f2f212054</regionId>
		<name>BeaconTest</name>
		<type>BEACON</type>
		<eventType>ENTER</eventType>
		<msgTitle>Beacon subject</msgTitle>
		<msgContent>Beacon text</msgContent>
		<appName>OgangiTest</appName>
		<timezone>America/Caracas</timezone>
		<update>2014-06-08T23:46:12.805-04:30</update>
		<uuid>B9407F30-F5F8-466E-AFF9-25556B57FE6D</uuid>
		<major>8888</major>
		<minor>3333</minor>
		<manufacturer>ESTIMOTE</manufacturer>
		<distance>NEAR</distance>
	<Beacon>
</result>

Please be aware that the <Beacon> object it's generic and may apply to other responses in other methods.

Result parameters
Parameter Name Description Possible Values
Beacon.regionId Region's unique identifier Text
Beacon.name Beacon's name Text
Beacon.type Location Based Campaign's type. Always BEACON for this method
Beacon.eventType The type of event that triggers the beacon. Valid values are: ENTER | EXIT | ENTER-EXIT
Beacon.msgTitle The message's title to be deliver when the beacon fires. Text
Beacon.msgContent The message's content to be deliver when the beacon fires. Text
Beacon.appName The identifier of the application, who will monitor the beacon. Text
Beacon.timezone Timezone used Text
Beacon.update The date mark when the last update occurs A formatted date string: yyyy-MM-dd'T'HH:mm:ss.SSSZZ
For more information please review the pattern letters quick reference
uuid Beacon's UUID value. Text
major Beacon's MAJOR VERSION value. Text
minor Beacon's MINOR VERSION value. Text
manufacturer Beacon's Manufacturer. Text
distance User's distance to the beacon needed to trigger the event. INMEDIATE
NEAR
FAR

Update Beacon

Overview

Once you have created a Beacon you could use this method to edit it and keeping it updated.

The Campaign Manager will notify all devices about this update by sending a special push message.

URL

Parameters on the following URL are inside braces { } 

{base_url}/rest/api/tools/editBeacon/{instanceId}/{regionId}/{name}/{uuid}/{major}/{minor}/{manufacturer}/{distance}/{eventType}/{msgTitle}/{msgContent}/{rules}/{publicKey}/{signature}
Parameter Name Description
instanceId An instance id is the workspace identification number, if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
regionId The Beacon's id you want to update
name
OPTIONAL 		The desired beacon's name. This parameter must be Base64 encoded. You can't exceed 80 characters
Write null to ignore this placeholder
uuid
OPTIONAL 		Beacon's UUID value. This value comes with the device.
Write null to ignore this placeholder
major
OPTIONAL 		Beacon's MAJOR VERSION value. This value comes with the device.
Write null to ignore this placeholder
minor
OPTIONAL 		Beacon's MINOR VERSION value. This value comes with the device.
Write null to ignore this placeholder
manufacturer
OPTIONAL 		Beacon's Manufacturer. Each manufacturer could provide a proprietary mechanism to modify UUID, Major & Minor values.
Write null to ignore this placeholder
distance
OPTIONAL 		User's distance to the beacon needed to trigger the event. Valid values are: INMEDIATE | NEAR | FAR or null to ignore this placeholder
eventType
OPTIONAL 		The type of event that triggers the Beacon. Valid values are: ENTER | EXIT | ENTER-EXIT or null to ignore this placeholder
msgTitle
OPTIONAL 		A title for this message. This parameter must be Base64 encoded. You can't exceed 80 characters.
Write null to ignore this placeholder
msgContent
OPTIONAL 		The content of the message per se. This parameter must be Base64 encoded. You can't exceed 200 characters.
Write null to ignore this placeholder
rules
OPTIONAL 		Powerful mechanism of rules. For more information please read the RULE parameter appendix
Write null to ignore this placeholder
publicKey The public key to access this API. if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
signature The unique SHA256 signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our Java Example

Response

The Response XML is divided in a static part and a dynamic one, we call it dynamic because it will vary depending on the method you invoke. Please read our Response XML Basics section if you want to learn more about the response parts. 

<input>editBeacon</input>
<status>OK</status>
<description>Completed</description>
<result>
	<Beacon>
		<regionId>e4f1f80f-eb8f-4b05-a40a-803f2f212054</regionId>
		<name>BeaconTest</name>
		<type>BEACON</type>
		<eventType>ENTER</eventType>
		<msgTitle>Beacon subject</msgTitle>
		<msgContent>Beacon text</msgContent>
		<appName>OgangiTest</appName>
		<timezone>America/Caracas</timezone>
		<update>2014-06-08T23:46:12.805-04:30</update>
		<uuid>B9407F30-F5F8-466E-AFF9-25556B57FE6D</uuid>
		<major>8888</major>
		<minor>3333</minor>
		<manufacturer>ESTIMOTE</manufacturer>
		<distance>NEAR</distance>
	<Beacon>
</result>

Please be aware that the <Beacon> object it's generic and may apply to other responses in other methods.

Result parameters
Parameter Name Description Possible Values
Beacon.regionId Region's unique identifier Text
Beacon.name Beacon's name Text
Beacon.type Location Based Campaign's type. Always BEACON for this method
Beacon.eventType The type of event that triggers the beacon. Valid values are: ENTER | EXIT | ENTER-EXIT
Beacon.msgTitle The message's title to be deliver when the beacon fires. Text
Beacon.msgContent The message's content to be deliver when the beacon fires. Text
Beacon.appName The identifier of the application, who will monitor the beacon. Text
Beacon.timezone Timezone used Text
Beacon.update The date mark when the last update occurs A formatted date string: yyyy-MM-dd'T'HH:mm:ss.SSSZZ
For more information please review the pattern letters quick reference
uuid Beacon's UUID value. Text
major Beacon's MAJOR VERSION value. Text
minor Beacon's MINOR VERSION value. Text
manufacturer Beacon's Manufacturer. Text
distance User's distance to the beacon needed to trigger the event. INMEDIATE
NEAR
FAR

Retrieve IP Address Info

Overview

This handy method provides the geographical information from an IP address.

We keep our internal database synced to the geographical information provided by ip2location.

URL

Parameters on the following URL are inside braces { } 

{base_url}/rest/api/tools/getIPAddressInfo/{instanceId}/{ip}/{publicKey}/{signature}
Parameter Name Description
instanceId An instance id is the workspace identification number, if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
ip The IP address to query
publicKey The public key to access this API. if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
signature The unique SHA256 signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our Java Example

Response

The Response XML is divided in a static part and a dynamic one, we call it dynamic because it will vary depending on the method you invoke. Please read our Response XML Basics section if you want to learn more about the response parts. 

<input>getIPAddressInfo</input>
<status>OK</status>
<description>Completed</description>
<result>
	<ipAddressInfo>
		<isoCountryCode>US</isoCountryCode>
		<regionCode>VA</regionCode>FINISHED>
		<regionName>Virginia</regionName>
		<city>Falls Church</city>
		<zipCode>22042</zipCode>
		<latitude>38.863998</latitude>
		<longitude>-77.192200</longitude>
		<metroCode>511</metroCode>
		<areaCode>703</areaCode>
	</ipAddressInfo>
</result>
Result parameters
Parameter Name Description Possible Values
isoCountryCode The two-character ISO 3166-1 standard for country code A ISO 3166 String
regionCode The principal geographical subdivision code according the ISO 3166-1 standard A ISO 3166 String
regionName Name of the providence or state. Text
city The city name for the location associated with the IP address. Text
zipCode Zip Code for the location associated with the IP address. Text
latitude Latitudinal coordinates corresponding to the location . Number (decimal notation)
longitude Longitudinal coordinates corresponding to the location. Number (decimal notation)
metroCode Is the Designated Market Area (DMA) region code associated with the IP address. These are only available for networks in the US. Text
Only available in the United States
areaCode Is the telephone area code associated with the IP address. This output is deprecated, and may not reflect newer area codes. Text
Only available in the United States