//[[restapi:start|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.

<WRAP round tip>
Beacons have caused a great impact on markets and department stores. You can learn more about Bluetooth and Beacons [[http://www.bluetooth.com/marketing-and-branding/markets/retail-and-location-based-services|here]].
</WRAP>

==== 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 [[misc:otto|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 [[restapi:appx_ciphering|Base64 encoded]]. <wrap alert>You can't exceed 80 characters</wrap> |
| uuid | Beacon's UUID value. <wrap info>This value comes with the device</wrap> |
| major | Beacon's MAJOR VERSION value. <wrap info>This value comes with the device</wrap> |
| minor | Beacon's MINOR VERSION value. <wrap info>This value comes with the device</wrap> |
| manufacturer | Beacon's Manufacturer. <wrap info>Each manufacturer could provide a proprietary mechanism to modify UUID, Major & Minor values </wrap> | 
| distance | User's distance to the beacon needed to trigger the event. <wrap info>Valid values are: INMEDIATE | NEAR | FAR </wrap> |
| eventType | The type of event that triggers the Beacon. <wrap info>Valid values are: ENTER | EXIT | ENTER-EXIT</wrap> |
| msgTitle \\ <wrap notice>OPTIONAL</wrap> | A title for this message. This parameter must be [[restapi:appx_ciphering|Base64 encoded]]. <wrap alert>You can't exceed 80 characters.</wrap> \\ <wrap info>Write **null** to ignore</wrap> |
| msgContent \\ <wrap notice>OPTIONAL</wrap> | The content of the message per se. This parameter must be [[restapi:appx_ciphering|Base64 encoded]]. <wrap alert>You can't exceed 200 characters.</wrap> \\ <wrap info> Write **null** to ignore</wrap> |
| rules \\ <wrap notice>OPTIONAL</wrap> | Powerful mechanism of rules. <wrap info>For more information please read [[restapi:appx_rules|the RULE parameter]] appendix</wrap> \\ <wrap info>Write **null** to ignore</wrap> |
| 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 [[misc:otto|ticketing tool]], you will need to provide your Mobile Engagement Campaign Manager's URL and your user login// |
| signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|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 [[restapi:appx_resp_xml|Response XML Basics]] section if you want to learn more about the response parts.

<code xml>

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

</code>

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

== 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. | <wrap info> Always BEACON for this method</wrap> |
| Beacon.eventType | The type of event that triggers the beacon. | <wrap info>Valid values are: **ENTER** | **EXIT** | **ENTER-EXIT**</wrap> |
| 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 [[restapi:appx_date#date_format_-_pattern_letters|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. 

<WRAP round tip>
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.
</WRAP>

==== 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 [[misc:otto|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 [[misc:otto|ticketing tool]], you will need to provide your Mobile Engagement Campaign Manager's URL and your user login// |
| signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|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 [[restapi:appx_resp_xml|Response XML Basics]] section if you want to learn more about the response parts.

<code xml>

<input>removeBeacon</input>
<status>OK</status>
<description>Completed</description>
<result>
	<transactionResult> 
		<successful>true</successful>
		<message>Region removed</message>
	</transactionResult>
</result>

</code>

== Result parameters ==

^ Parameter Name ^ Description ^ Possible Values ^
| successful | Indicates if the region was deleted or not | <color blue>true</color> \\ <color red>false</color> |
| 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 [[misc:otto|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 [[misc:otto|ticketing tool]], you will need to provide your Mobile Engagement Campaign Manager's URL and your user login// |
| signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|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 [[restapi:appx_resp_xml|Response XML Basics]] section if you want to learn more about the response parts.

<code xml>

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

</code>

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

== 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. | <wrap info> Always BEACON for this method</wrap> |
| Beacon.eventType | The type of event that triggers the beacon. | <wrap info>Valid values are: **ENTER** | **EXIT** | **ENTER-EXIT**</wrap> |
| 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 [[restapi:appx_date#date_format_-_pattern_letters|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 [[misc:otto|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 [[misc:otto|ticketing tool]], you will need to provide your Mobile Engagement Campaign Manager's URL and your user login// |
| signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|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 [[restapi:appx_resp_xml|Response XML Basics]] section if you want to learn more about the response parts.

<code xml>

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

</code>

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

== 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. | <wrap info> Always BEACON for this method</wrap> |
| Beacon.eventType | The type of event that triggers the beacon. | <wrap info>Valid values are: **ENTER** | **EXIT** | **ENTER-EXIT**</wrap> |
| 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 [[restapi:appx_date#date_format_-_pattern_letters|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.

<WRAP round tip>
The [[:campaign_manager|Campaign Manager]] will notify all devices about this update by sending a special push message.
</WRAP>

==== 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 [[misc:otto|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 \\ <wrap notice>OPTIONAL</wrap> | The desired beacon's name. This parameter must be [[restapi:appx_ciphering|Base64 encoded]]. <wrap alert>You can't exceed 80 characters</wrap> \\ <wrap info>Write **null** to ignore this placeholder</wrap> |
| uuid \\ <wrap notice>OPTIONAL</wrap> | Beacon's UUID value. <wrap info>This value comes with the device.</wrap> \\ <wrap info>Write **null** to ignore this placeholder</wrap> |
| major \\ <wrap notice>OPTIONAL</wrap> | Beacon's MAJOR VERSION value. <wrap info>This value comes with the device.</wrap> \\ <wrap info>Write **null** to ignore this placeholder</wrap> |
| minor \\ <wrap notice>OPTIONAL</wrap> | Beacon's MINOR VERSION value. <wrap info>This value comes with the device.</wrap> \\ <wrap info>Write **null** to ignore this placeholder</wrap> |
| manufacturer \\ <wrap notice>OPTIONAL</wrap> | Beacon's Manufacturer. <wrap info>Each manufacturer could provide a proprietary mechanism to modify UUID, Major & Minor values.</wrap> \\ <wrap info>Write **null** to ignore this placeholder</wrap> | 
| distance \\ <wrap notice>OPTIONAL</wrap> | User's distance to the beacon needed to trigger the event. <wrap info>Valid values are: **INMEDIATE** | **NEAR** | **FAR** or **null** to ignore this placeholder</wrap> |
| eventType \\ <wrap notice>OPTIONAL</wrap> | The type of event that triggers the Beacon. <wrap info>Valid values are: **ENTER** | **EXIT** | **ENTER-EXIT** or **null** to ignore this placeholder</wrap> |
| msgTitle \\ <wrap notice>OPTIONAL</wrap> | A title for this message. This parameter must be [[restapi:appx_ciphering|Base64 encoded]]. <wrap alert>You can't exceed 80 characters.</wrap> \\ <wrap info>Write **null** to ignore this placeholder</wrap> |
| msgContent \\ <wrap notice>OPTIONAL</wrap> | The content of the message per se. This parameter must be [[restapi:appx_ciphering|Base64 encoded]]. <wrap alert>You can't exceed 200 characters.</wrap> \\ <wrap info> Write **null** to ignore this placeholder</wrap> |
| rules \\ <wrap notice>OPTIONAL</wrap> | Powerful mechanism of rules. <wrap info>For more information please read [[restapi:appx_rules|the RULE parameter]] appendix</wrap> \\ <wrap info>Write **null** to ignore this placeholder</wrap> |
| publicKey | The public key to access this API. //if you don't know yours please request it using our [[misc:otto|ticketing tool]], you will need to provide your Mobile Engagement Campaign Manager's URL and your user login// |
| signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|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 [[restapi:appx_resp_xml|Response XML Basics]] section if you want to learn more about the response parts.

<code xml>

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

</code>

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

== 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. | <wrap info> Always BEACON for this method</wrap> |
| Beacon.eventType | The type of event that triggers the beacon. | <wrap info>Valid values are: **ENTER** | **EXIT** | **ENTER-EXIT**</wrap> |
| 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 [[restapi:appx_date#date_format_-_pattern_letters|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. 

<WRAP round tip>
We keep our internal database synced to the geographical information provided by [[http://www.ip2location.com|ip2location]].
</WRAP>
==== 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 [[misc:otto|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 [[misc:otto|ticketing tool]], you will need to provide your Mobile Engagement Campaign Manager's URL and your user login// |
| signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|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 [[restapi:appx_resp_xml|Response XML Basics]] section if you want to learn more about the response parts.

<code xml>

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

</code>

== Result parameters ==

^ Parameter Name ^ Description ^ Possible Values ^
| isoCountryCode | The two-character ISO 3166-1 standard for country code | A [[http://www.iso.org/iso/country_codes|ISO 3166]] String |
| regionCode | The principal geographical subdivision code according the ISO 3166-1 standard | A [[http://www.iso.org/iso/country_codes|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 ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]]) |
| longitude | Longitudinal coordinates corresponding to the location. | Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|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 \\ <wrap info>Only available in the United States</wrap> |
| areaCode | Is the telephone area code associated with the IP address. This output is deprecated, and may not reflect newer area codes. | Text \\ <wrap info>Only available in the United States</wrap> |