//[[restapi:start|RESTful API]]//

====== Request Device Location ======

==== Overview ====

You can request the location for a particular device by using this method, the Campaign Manager will request the current location from the device using a special PUSH message, when the device's location arrive it will deliver the information through your [[restapi:appx_callbacks|Callback URL]].

<WRAP round tip>
Please note that this method is just a request, which means that you have to be ready at your end to handle the location information when it arises.
</WRAP>

==== URL ====

Parameters on the following URL are inside braces { }
  {base_url}/rest/api/tools/getLocation/{instanceId}/{to}/{appName}/{platform}/{from}/{carrier}/{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// |
| to | This is the device's mobile phone number |
| appName \\ <wrap notice>OPTIONAL</wrap> | Your App's name which will receive your Push Notifications \\ <wrap info>Write **//null//** on this placeholder to ignore this parameter</wrap>|
| platform \\ <wrap notice>OPTIONAL</wrap> | The target platform for the push service. \\ <wrap info>Valid values are: **ANDROID**, **IOS** or **null** to ignore</wrap> |
| from \\ <wrap notice>OPTIONAL</wrap> | The short or long code that will originate the SMS if needed \\ <wrap info>Write **//null//** on this placeholder to ignore this parameter</wrap> | 
| carrier \\ <wrap notice>OPTIONAL</wrap> | The carrier operator used to fire the SMS if needed \\ <wrap info>Write **//null//** on this placeholder to ignore this parameter</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]] |

<WRAP round notice>
Please note that all **OPTIONAL** parameter are linked, which means that you have to choose between use them all or ignore them all together.
</WRAP>

==== 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>getLocation</input>
<status>OK</status>
<description>Completed</description>
<result>
	<LocationRequest>
		<requestId>3d97e8ca-fcc9-4f15-8c22-8cbf123c723f</requestId>
		<user>13056708084</user>
		<requestType>LOCATION</requestType>
		<latitude>0.0</latitude>
		<longitude>0.0</longitude>
		<status>PENDING</status>
		<clientId>uTJoDFuabB6YFvc9s43</clientId>
		<appName>AppName</appName>
		<platform>IOS</platform>
		<date>2014-03-17T17:26:23.133-04:30</date>
	</LocationRequest>
</result>

</code>

<WRAP round tip>Please be aware that the **//<LocationRequest>//** tag and its content is a generic object and may apply to other responses in other methods.

As this is an asynchronous method this will not contains the actual device's information, you will be receiving an update through your [[restapi:appx_callbacks|Callback URL]]

</WRAP>

== Result parameters ==

^ Parameter Name ^ Description ^ Possible Values ^
| LocationRequest.requestId | This is your request identifier | Text | 
| LocationRequest.user | The deviceId or mobile phone number | Text |
| LocationRequest.requestType | The request's type. | <wrap info>In this case: LOCATION</wrap> |
| LocationRequest.latitude | The device's latitude. <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap>| <wrap info>Starting value: 0.0</wrap> |
| LocationRequest.longitude | The device's longitude. <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap>| <wrap info>Starting value: 0.0</wrap>) |
| LocationRequest.status | This is the general status for the operation | <wrap info>Starting value: PENDING </wrap> |
| LocationRequest.clientId | This is your unique id, it represents you on the Campaign Manager Platform | Text | 
| LocationRequest.appName | The identifier of the application, which will receive the push message. | Text |
| LocationRequest.platform | The target platform used | Valid values: \\ **ANDROID \\ IOS** |
| LocationRequest.date | Time mark at the origination moment | 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 |

====== Checking Device Location by Coordinates ======

==== Overview ====

Verify if a particular device is inside a region at this moment.

==== URL ====

Parameters on the following URL are inside braces { }
  {base_url}/rest/api/tools/checkLocation/{instanceId}/{to}/{appName}/{platform}/{from}/{carrier}/{latitude}/{longitude}/{radius}/{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// |
| to | This is the device's mobile phone number |
| appName | Your App's name which will receive your Push Notifications |
| platform | The target platform for the push service. \\ <wrap info>Valid values are: **ANDROID** or **IOS** </wrap> |
| from \\ <wrap notice>OPTIONAL</wrap> | The short or long code that will originate the SMS if needed \\ <wrap info>Write **//null//** on this placeholder to ignore this parameter</wrap> | 
| carrier \\ <wrap notice>OPTIONAL</wrap> | The carrier operator used to fire the SMS if needed \\ <wrap info>Write **//null//** on this placeholder to ignore this parameter</wrap> |
| latitude | The point latitude <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> |
| longitude | The point longitude <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> |
| radius | The circle radius. <wrap info>Use **meters** for this value</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]] |

<WRAP round notice>
Please note that all **OPTIONAL** parameter are linked, which means that you have to choose between use them all or ignore them all together.
</WRAP>

==== 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>checkLocation</input>
<status>OK</status>
<description>Completed</description>
<result>
	<checkLocationRequest>
	        <requestId>3d97e8ca-fcc9-4f15-8c22-8cbf123c723f</requestId>
        	<user>584241111111</user>
	        <requestType>LOCATION</requestType>
        	<latitude>0.0</latitude>
	        <longitude>0.0</longitude>
        	<status>PENDING</status>
	        <clientId>uTJoDFuabB6YFvc9s43</clientId>
        	<appName>AppName</appName>
	        <platform>IOS</platform>
        	<date>2014-03-17T17:26:23.133-04:30</date>
	        <poiLatitude>8.630554</poiLatitude>
        	<poiLongitude>71.13327</poiLongitude>
	        <poiRadius>3000.0</poiRadius>
        	<poiName></poiName>
	</checkLocationRequest>
</result>

</code>

<WRAP round tip>Please be aware that the **//<checkLocationRequest>//** tag and its content is a generic object and may apply to other responses in other methods.

As this is an asynchronous method this will not contains the actual device's information, you will be receiving an update through your [[restapi:appx_callbacks|Callback URL]]
</WRAP>

== Result parameters ==

^ Parameter Name ^ Description ^ Possible Values ^
| checkLocationRequest.requestId | This is your request identifier | Text | 
| checkLocationRequest.user | The deviceId or mobile phone number | Text |
| checkLocationRequest.requestType | The request's type. | <wrap info>In this case: CHK_LOCATION </wrap> |
| checkLocationRequest.latitude | The device's latitude. <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> | <wrap info>Starting value: 0.0</wrap> |
| checkLocationRequest.longitude | The device's longitude. <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> | <wrap info>Starting value: 0.0</wrap>) |
| checkLocationRequest.status | This is the general status for the operation | <wrap info>Starting value: PENDING </wrap> |
| checkLocationRequest.clientId | This is your unique id, it represents you on the Campaign Manager Platform | Text | 
| checkLocationRequest.appName | The identifier of the application, which will receive the push message. | Text |
| checkLocationRequest.platform | The target platform used | Valid values: \\ **ANDROID \\ IOS** |
| checkLocationRequest.date | Time mark at the origination moment | 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 |
| checkLocationRequest.poiLatitude | The point of interest's latitude | Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]]) | 
| checkLocationRequest.poiLongitude | The point of interest's longitude | Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]]) |
| checkLocationRequest.poiRadius | The radius of the point of interest | Number (meters) |
| checkLocationRequest.poiName | The point of interest's name. | Text |

====== Create Geo-Fence ======

==== Overview ====

Create a geographical fence (represented as a circle) that will be watched. This fence is capable to detect when App's users pass through it in any direction.

If this happened you will be notified about this through your [[restapi:appx_callbacks|Callback URL]].

<WRAP round tip>
This function send a push notification to every device registered into your app so they can save the geo-fence in their platform's device (Android or iOS). 

Be aware that every platform has their conditions. For example, [[https://developer.apple.com/library/ios/documentation/UserExperience/Conceptual/LocationAwarenessPG/RegionMonitoring/RegionMonitoring.html|iOS limits the number of regions that may be simultaneously monitored by a single app]] to twenty.

</WRAP>

==== URL ====

Parameters on the following URL are inside braces { }
  {base_url}/rest/api/tools/createGeoFence/{instanceId}/{name}/{latitude}/{longitude}/{radius}/{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 name identifier for this Geo-Fence. This parameter must be [[restapi:appx_ciphering|Base64 encoded]]. <wrap alert>You can't exceed 80 characters</wrap> |
| latitude | The point latitude <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> |
| longitude | The point longitude <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> |
| radius | The circle radius. <wrap info>Use **meters** for this value</wrap> |
| eventType | The type of event that triggers the geo-fence. <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. 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. 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> |
| 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>createGeoFence</input>
<status>OK</status>
<description>Completed</description>
<result>
	<GeoFence>
	        <regionId>ef0d1fb5-c7cb-5db2e87f273d</regionId>
        	<name>test</name>
	        <latitude>8.620554</latitude>
        	<longitude>-71.13317</longitude>
	        <radius>3000.0</radius>
        	<type>geoFence</type>
	        <eventType>ENTER-EXIT</eventType>
        	</msgTitle>
	        </msgContent>
        	</rules>
	        <appName>AppTest</appName>
        	<timezone>America/Caracas</timezone>
	        <update>2014-03-20T17:55:16.621-04:30</update>
	</GeoFence>
</result>

</code>

== Result parameters ==

^ Parameter Name ^ Description ^ Possible Values ^
| GeoFence.regionId | Region's unique identifier | Text |
| GeoFence.name | Geo-Fence's name | Text |
| GeoFence.latitude | Region's latitude point. <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> | <wrap info>Starting value: 0.0</wrap> |
| GeoFence.longitude | Region's longitude point. <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> | <wrap info>Starting value: 0.0</wrap>) |
| GeoFence.radius | Region's radius  | Number (meters) |
| GeoFence.type | Campaign type, always **GEOFENCE** for this method | Text |
| GeoFence.eventType | The type of event that triggers the geo-fence. | <wrap info>Valid values are: ENTER | EXIT | ENTER-EXIT</wrap> |
| GeoFence.msgTitle | The title of this message. | Text | 
| GeoFence.msgContent | The content of the message per se. | Text |
| GeoFence.rules | The RULE defined at the creation time | Text |
| GeoFence.appName | The identifier of the application, who will monitor the region. | Text |
| GeoFence.timezone | Timezone used | Text |
| GeoFence.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 |

====== Notify Region Event ======

==== Overview ====

Use this method from the mobile App (if you are developing yours) when a Geo-Fence event occurs. Once the [[:campaign_manager|Campaign Manager]] get the notification it will pass it to the client through the 
[[restapi:appx_callbacks|Callback URL]].

==== URL ====

Parameters on the following URL are inside braces { }
  {base_url}/rest/api/tools/notifyRegionEvent/{instanceId}/{regionId}/{deviceId}/{status}/{date}/{latitude}/{longitude}/{regionType}/{appName}/{platform}/{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. |
| deviceId | The if of the device running device |
| status | The status for this event, entering or leaving <wrap info>Possible values: ENTER | EXIT </wrap> |
| date | The time & date when the event occurs. <wrap info>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</wrap> |
| latitude | The coordinate's latitude of the device's location when the event happened <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> |
| longitude | The coordinate's longitude of the device's location when the event happened <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> |
| regionType | The type of the region that triggers the event <wrap info>Possible values: geofence | beacon </wrap> |
| appName | The App's name which will receive your Push Notifications |
| platform | The target platform for the push service. <wrap info>Valid values are: **ANDROID** | **IOS**</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>notifyRegionEvent</input>
<status>OK</status>
<description>Completed</description>
<result>
	<transactionResult> 
		<successful>true</successful>
		<message>Successful registration</message>
	</transactionResult>
</result>

</code>

== Result parameters ==

^ Parameter Name ^ Description ^ Possible Values ^
| successful | Indicates if the notification was posted or not | <color blue>true</color> \\ <color red>false</color> |
| message | A human readable explanation | Text |

====== Remove Geo-Fence ======

==== Overview ====

Remove an existing Geo-Fence. 

<WRAP round tip>
This function send a special push message to every device registered with your App so it can delete the Geo-Fence on the device's platform.
</WRAP>

==== URL ====

Parameters on the following URL are inside braces { }
  {base_url}/rest/api/tools/removeGeoFence/{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>removeGeoFence</input>
<status>OK</status>
<description>Completed</description>
<result>
	<transactionResult> 
		<successful>true</successful>
		<message>Region deleted</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 |

====== Retrieving Geo-Fence ======

==== Overview ====

This method will list all client's Geo-Fences.

==== URL ====

Parameters on the following URL are inside braces { }
  {base_url}/rest/api/tools/getGeoFences/{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>getGeoFences</input>
<status>OK</status>
<description>Completed</description>
<result>
	<GeoFences>
		<GeoFence>
		        <regionId>ef0d1fb5-c7cb-5db2e87f273d</regionId>
        		<name>test</name>
		        <latitude>8.620554</latitude>
        		<longitude>-71.13317</longitude>
	        	<radius>3000.0</radius>
	        	<type>geoFence</type>
		        <eventType>ENTER-EXIT</eventType>
        		</msgTitle>
		        </msgContent>
        		</rules>
	        	<appName>AppTest</appName>
	        	<timezone>America/Caracas</timezone>
		        <update>2014-03-20T17:55:16.621-04:30</update>
		</GeoFence>

		...

		<GeoFence>
		        <regionId>8js7ah23-lolk-mkajhsud02uq</regionId>
        		<name>folks</name>
	        	<latitude>82.620554</latitude>
	        	<longitude>11.13317</longitude>
		        <radius>3000.0</radius>
        		<type>geoFence</type>
		        <eventType>ENTER</eventType>
        		</msgTitle>
	        	</msgContent>
	        	</rules>
		        <appName>AppTest</appName>
        		<timezone>America/Caracas</timezone>
		        <update>2014-02-02T07:15:14.131-04:30</update>
		</GeoFence>
	</GeoFences>
</result>

</code>

== Result parameters ==

^ Parameter Name ^ Description ^ Possible Values ^
| GeoFence.regionId | Region's unique identifier | Text |
| GeoFence.name | Geo-Fence's name | Text |
| GeoFence.latitude | Region's latitude point. <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> | <wrap info>Starting value: 0.0</wrap> |
| GeoFence.longitude | Region's longitude point. <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> | <wrap info>Starting value: 0.0</wrap>) |
| GeoFence.radius | Region's radius  | Number (meters) |
| GeoFence.type | Campaign type, always **GEOFENCE** for this method | Text |
| GeoFence.eventType | The type of event that triggers the geo-fence. | <wrap info>Valid values are: ENTER | EXIT | ENTER-EXIT</wrap> |
| GeoFence.msgTitle | The title of this message. | Text | 
| GeoFence.msgContent | The content of the message per se. | Text |
| GeoFence.rules | The RULE defined at the creation time | Text |
| GeoFence.appName | The identifier of the application, who will monitor the region. | Text |
| GeoFence.timezone | Timezone used | Text |
| GeoFence.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 |

====== Retrieving Geo-Fence (with pagination & filters) ======

==== Overview ====

This method will list all client's Geo-Fences. You can filter and paginate your results.

==== URL ====

Parameters on the following URL are inside braces { }
  {base_url}/rest/api/tools/getGeoFences/{instanceId}/{page}/{resultsPerPage}/{parameters}/{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// |
| page | A numeric indicator to fetch a specific page. <wrap tip>useful when you are dealing with a large bunch of data and you want to iterate over it</wrap> |
| resultsPerPage | How many items will show per fetch. |
| parameters | Use this as search's filters. Please learn more about this by reading the [[restapi:appx_geoline_search|Geo-Fence Inline Search String]] <wrap info>Write **null** on this placeholder if you don't want to use search filters </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>getGeoFences</input>
<status>OK</status>
<description>Completed</description>
<result>
	<GeoFences>
		<GeoFence>
		        <regionId>ef0d1fb5-c7cb-5db2e87f273d</regionId>
        		<name>test</name>
		        <latitude>8.620554</latitude>
        		<longitude>-71.13317</longitude>
	        	<radius>3000.0</radius>
	        	<type>geoFence</type>
		        <eventType>ENTER-EXIT</eventType>
        		</msgTitle>
		        </msgContent>
        		</rules>
	        	<appName>AppTest</appName>
	        	<timezone>America/Caracas</timezone>
		        <update>2014-03-20T17:55:16.621-04:30</update>
		</GeoFence>

		...

		<GeoFence>
		        <regionId>8js7ah23-lolk-mkajhsud02uq</regionId>
        		<name>folks</name>
	        	<latitude>82.620554</latitude>
	        	<longitude>11.13317</longitude>
		        <radius>3000.0</radius>
        		<type>geoFence</type>
		        <eventType>ENTER</eventType>
        		</msgTitle>
	        	</msgContent>
	        	</rules>
		        <appName>AppTest</appName>
        		<timezone>America/Caracas</timezone>
		        <update>2014-02-02T07:15:14.131-04:30</update>
		</GeoFence>
	</GeoFences>
</result>

</code>

== Result parameters ==

^ Parameter Name ^ Description ^ Possible Values ^
| GeoFence.regionId | Region's unique identifier | Text |
| GeoFence.name | Geo-Fence's name | Text |
| GeoFence.latitude | Region's latitude point. <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> | <wrap info>Starting value: 0.0</wrap> |
| GeoFence.longitude | Region's longitude point. <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> | <wrap info>Starting value: 0.0</wrap>) |
| GeoFence.radius | Region's radius  | Number (meters) |
| GeoFence.type | Campaign type, always **GEOFENCE** for this method | Text |
| GeoFence.eventType | The type of event that triggers the geo-fence. | <wrap info>Valid values are: ENTER | EXIT | ENTER-EXIT</wrap> |
| GeoFence.msgTitle | The title of this message. | Text | 
| GeoFence.msgContent | The content of the message per se. | Text |
| GeoFence.rules | The RULE defined at the creation time | Text |
| GeoFence.appName | The identifier of the application, who will monitor the region. | Text |
| GeoFence.timezone | Timezone used | Text |
| GeoFence.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 |






====== Retrieve Geo-Fence by ID ======

==== Overview ====

Given a Geo-Fence's Id retrieve the information about it

==== URL ====

Parameters on the following URL are inside braces { }
  {base_url}/rest/api/tools/getGeoFenceById/{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 identifier of the Geo-Fence 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>getGeoFenceById</input>
<status>OK</status>
<description>Completed</description>
<result>
	<GeoFence>
	        <regionId>ef0d1fb5-c7cb-5db2e87f273d</regionId>
        	<name>test</name>
	        <latitude>8.620554</latitude>
        	<longitude>-71.13317</longitude>
	        <radius>3000.0</radius>
        	<type>geoFence</type>
	        <eventType>ENTER-EXIT</eventType>
        	</msgTitle>
	        </msgContent>
        	</rules>
	        <appName>AppTest</appName>
        	<timezone>America/Caracas</timezone>
	        <update>2014-03-20T17:55:16.621-04:30</update>
	</GeoFence>
</result>

</code>

== Result parameters ==

^ Parameter Name ^ Description ^ Possible Values ^
| GeoFence.regionId | Region's unique identifier | Text |
| GeoFence.name | Geo-Fence's name | Text |
| GeoFence.latitude | Region's latitude point. <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> | <wrap info>Starting value: 0.0</wrap> |
| GeoFence.longitude | Region's longitude point. <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> | <wrap info>Starting value: 0.0</wrap>) |
| GeoFence.radius | Region's radius  | Number (meters) |
| GeoFence.type | Campaign type, always **GEOFENCE** for this method | Text |
| GeoFence.eventType | The type of event that triggers the geo-fence. | <wrap info>Valid values are: ENTER | EXIT | ENTER-EXIT</wrap> |
| GeoFence.msgTitle | The title of this message. | Text | 
| GeoFence.msgContent | The content of the message per se. | Text |
| GeoFence.rules | The RULE defined at the creation time | Text |
| GeoFence.appName | The identifier of the application, who will monitor the region. | Text |
| GeoFence.timezone | Timezone used | Text |
| GeoFence.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 |








====== Update Geo-Fence ======

==== Overview ====

Once you have created your Geo-Fence you could use this method to edit it and keeping it updated.

<WRAP round tip>
The Campaign Manager will notify all devices about this modification by sending a special push message
</WRAP>

==== URL ====

Parameters on the following URL are inside braces { }
  {base_url}/rest/api/tools/editGeoFence/{instanceId}/{regionId}/{name}/{latitude}/{longitude}/{radius}/{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 region's id you want to update |
| name | The name identifier for this Geo-Fence. This parameter must be [[restapi:appx_ciphering|Base64 encoded]]. <wrap alert>You can't exceed 80 characters</wrap> |
| latitude \\ <wrap notice>OPTIONAL</wrap> | The point latitude <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> |
| longitude \\ <wrap notice>OPTIONAL</wrap> | The point longitude <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> |
| radius \\ <wrap notice>OPTIONAL</wrap> | The circle radius. <wrap info>Use **meters** for this value</wrap> |
| eventType \\ <wrap notice>OPTIONAL</wrap> | The type of event that triggers the geo-fence. <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. 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. 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> |
| 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]] |

<WRAP round tip>
If you don't want to use any **<color blue>OPTIONAL</color>** parameter you just need to write **null** on that particular placeholder.
</WRAP>

==== 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>editGeoFence</input>
<status>OK</status>
<description>Completed</description>
<result>
	<GeoFence>
	        <regionId>ef0d1fb5-c7cb-5db2e87f273d</regionId>
        	<name>test</name>
	        <latitude>8.620554</latitude>
        	<longitude>-71.13317</longitude>
	        <radius>3000.0</radius>
        	<type>geoFence</type>
	        <eventType>ENTER-EXIT</eventType>
        	</msgTitle>
	        </msgContent>
        	</rules>
	        <appName>AppTest</appName>
        	<timezone>America/Caracas</timezone>
	        <update>2014-03-20T17:55:16.621-04:30</update>
	</GeoFence>
</result>

</code>

== Result parameters ==

^ Parameter Name ^ Description ^ Possible Values ^
| GeoFence.regionId | Region's unique identifier | Text |
| GeoFence.name | Geo-Fence's name | Text |
| GeoFence.latitude | Region's latitude point. <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> | <wrap info>Starting value: 0.0</wrap> |
| GeoFence.longitude | Region's longitude point. <wrap info>Number ([[https://en.wikipedia.org/wiki/Decimal_degrees|decimal notation]])</wrap> | <wrap info>Starting value: 0.0</wrap>) |
| GeoFence.radius | Region's radius  | Number (meters) |
| GeoFence.type | Campaign type, always **GEOFENCE** for this method | Text |
| GeoFence.eventType | The type of event that triggers the geo-fence. | <wrap info>Valid values are: ENTER | EXIT | ENTER-EXIT</wrap> |
| GeoFence.msgTitle | The title of this message. | Text | 
| GeoFence.msgContent | The content of the message per se. | Text |
| GeoFence.rules | The RULE defined at the creation time | Text |
| GeoFence.appName | The identifier of the application, who will monitor the region. | Text |
| GeoFence.timezone | Timezone used | Text |
| GeoFence.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 |