Create dwell time alert rule

Service version: 1
Last edit: 2020.11.16
Deprecated

Deprecation notice

November 6, 2020
  • The "Create dwell time alert rule" endpoint has been deprecated.
  • This endpoint has been replaced with the generic endpoint to handle all types of Alert Rules: Create Alert Rule.
  • This endpoint will be withdrawn following a 12 month deprecation period.
  • The planned withdrawal date is December 1, 2021.
  • Following withdrawal, requests to this endpoint may receive an HTTP 404 error in response.
  • More details are available at the TomTom deprecation policy page.

Purpose

This endpoint is used to configure a Dwell Time Alert Rule.

Request data

HTTPS method: POST

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for these values. The generic URL format is as follows.

URL format

POST
URL request example
https://{baseURL}/geofencing/{versionNumber}/alerts/dwell?key={Your_API_Key}&adminKey={Your_Admin_Key}

curl command format

POST
Request curl command example
1curl -v -XPOST -H "Content-type: application/json" -d
2'{
3 "name": "Enter name of created alert rule",
4 "object": "Enter id of watched object",
5 "project": "Enter id of watched project",
6 "fence": "Enter id of watched fence",
7 "maxDwellTime": integer,
8 "notificationGroup": "Enter id of your notification group",
9 "enabled": true
10 }'
11'https://{baseURL}/geofencing/{versionNumber}/alerts/dwell?key={Your_API_Key}&adminKey={Your_Admin_Key}'

Request parameters

The following table describes the parameters that can be used in a request.

  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.
  • The order of request parameters is not important.

Note: There are no optional parameters in this endpoint.

Required parametersDescription
baseURL
string
The base URL for calling the API.
Value: api.tomtom.com
versionNumber
string
Service version.
Value: 1
key
string
An API Key valid for the requested service.
Value: Your valid API Key.
adminKey
string
An Admin Key valid for the provided API Key.
Value: Your valid Admin Key.

POST request body

POST
URL request example - JSON
1{
2 "name": "Enter name of created alert rule",
3 "object": "Enter id of watched object",
4 "project": "Enter id of watched project",
5 "fence": "Enter id of watched fence",
6 "maxDwellTime": integer,
7 "notificationGroup": "Enter the id of your notification group",
8 "enabled": true
9}

Request fields

The following table describes the fields that can be used in a request body.

Primary fieldsDescription
name
string
The name of the alert rule.
Field is not required.
Default value: empty
object
string
The UUID of the object or * for any object in configuration.
project
string
The UUID of the project or * for any project in configuration.
fence
string
The UUID of the fence or * for any fence in configuration.
maxDwellTime
integer
Maximum time (in seconds) an Object can stay inside a Fence, before alert is risen.
notificationGroup
string
The UUID of the owned group in the Notification Service to send an alert.
enabled
boolean
The Boolean value that says if an alert rule is enabled or not.
Values:
  • true: An alert is enabled.
  • false: An alert is disabled.

Field is not required.
Default value: true

Response data

Response body

Response body - JSON
1{
2 "id": "Id of created alert rule",
3 "covers": ["Id of covered other alert rule", "Id of covered other different alert rule"]
4}

Response fields

The following table describes all of the fields that can appear in a response.

Primary fieldsDescription
id
string
The UUID of the alert rule.
covers
array
The list of UUID alerts covered by the already created alert rules.

Response codes

CodeMeaning and possible causes
201Created
400Bad request:
  • Alert rule name is too long.
  • Object id is not provided.
  • Object id is incorrect.
  • Project id is not provided.
  • Project id is incorrect.
  • Fence id is not provided.
  • Fence id is incorrect.
  • Maximum dwell time is not provided.
  • Maximum dwell time is a non-integer.
  • Maximum dwell time is negative.
  • Notification group id is not provided.
  • Notification group id is incorrect.
403Forbidden:
  • Provided Admin Key is invalid.
  • Admin Key is missing.

Example

Create a new dwell time alert rule.

Request format

POST
URL request example
https://api.tomtom.com/geofencing/1/alerts/dwell?key=PJD7y0G5AFj9Jiok6F0tIK16NiWYotb3&adminKey=b330d317-4fe1-4d48-b75f-06cc3be58fb2

POST body format

POST
POST body format - JSON
1{
2 "name": "Airport Kiss&Ride&quot policy",
3 "object": "*",
4 "project": "ab550513-7026-4c98-9ff7-a930d70b66f8",
5 "fence": "0b16633b-7b2b-4fd6-a834-f36c2250ab66",
6 "maxDwellTime": 600,
7 "notificationGroup": "8e34613a-2324-4749-ac9d-25bf7a91d218",
8 "enabled": true
9}

Response body

Response body - JSON
1{
2 "id": "1f9e811f-867b-4d4d-aed9-7d8266fac0ae",
3 "covers": ["e4f06777-079e-4f02-a49d-97dd4c4e3a81", "c930bae3-98c8-4c07-93e6-f01ca1c3134a"]
4}