Create alert rule

Service version: 1 Last edit: 2022.09.01

Decommission notice

December 16, 2025

This service will be decommissioned on January 31, 2027.
All endpoints will be withdrawn following a 12 months deprecation period.
There is no recommended migration path.

Purpose

This endpoint is used to configure an 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 their values. The generic request format is as follows.

URL request format

post

URL request format

1
https://{baseURL}/geofencing/{versionNumber}/alerts/rules?key={Your_API_Key}&adminKey={Your_Admin_Key}

curl command requestformat

post

curl command requestformat

1
curl -v -XPOST -H "Content-type: application/json" -d
2
'{
3
   "name": "Enter name of created alert rule",
4
   "project": "Enter id of watched project",
5
   "fence": "Enter id of watched fence",
6
   "object": "Enter id of watched object",
7
   "alertType": "Enter type of alert to configure",
8
   "alertRuleConstraints": {
9
     "key": "value"
10
   },
11
   "notificationGroup": "Enter id of your notification group",
12
   "enabled": true
13
 }'
14
'https://{baseURL}/geofencing/{versionNumber}/alerts/rules?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 parameters	Description
`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

POST request body format - JSON

1
{
2
  "name": "Enter name of created alert rule",
3
  "project": "Enter id of watched project",
4
  "fence": "Enter id of watched fence",
5
  "object": "Enter id of watched object",
6
  "alertType": "Enter type of alert to configure",
7
  "alertRuleConstraints": {
8
    "key": "value"
9
  },
10
  "notificationGroup": "Enter id of your notification group",
11
  "enabled": true
12
}

POST request body fields

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

Primary fields
Field	Description
`name` string	The name of the Alert Rule. Field is not required. Default value: `empty`
`project` string	The UUID of the Project or `*` for any Project in the Configuration.
`fence` string	The UUID of the Fence or `*` for any Fence in the Configuration.
`object` string	The UUID of the Object or `` for any Object in the Configuration. This field is required for the “TRANSITION” , “DWELL” and “PROXIMITY” Alert types*.
`alertType` string	The type of the Alert Rule. Possible values: `"TRANSITION"`: When an Object entered or exited the Fence. `"DWELL"`: When an Object stays too long inside a Fence. `"OBJECT_COUNT"`: When the limit of Objects in a Fence is exceeded. `"PROXIMITY"`: When the distance between an Object and a Fence is smaller than the provided threshold.
`alertRuleConstraints` object	Contains Alert constraints specific to the selected Alert Rule.
`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`
alertRuleConstraints object
Field	Description
`transitionType` string	The type of the Transition to Alert. Possible values: `"ENTER"`: When an Object just entered the Fence. `"EXIT"`: When an Object just exited the Fence. `"ALL"`: When an Object just entered or exited the Fence. Required for the “TRANSITION” Alert type.
`maxDwellTime` integer	Maximum time (in seconds) that an Object can stay inside a Fence before an Alert is raised. Required for the “DWELL” Alert type.
`maxObjectCount` integer	Maximum number of Objects that can be present in a Fence at once before an Alert is raised. Required for the “OBJECT_COUNT” Alert type.
`proximityDistance` integer	Distance from the Fence within which the alarm will be triggered. The maximum proximity distance is 10 kilometers. Inside proximity alerts are triggered when an Object inside a Fence transitioned to a buffer area created from proximity. The value is expressed in meters. Value: `min/max: 1 to 10000` Required for the “PROXIMITY” Alert type.
`proximitySide` string	Determines the side of the Fence from which the proximity will be measured. Possible values: `"INSIDE"`: When proximity is supposed to be measured inside a Fence. `"OUTSIDE"`: When proximity is supposed to be measured outside a Fence. Required for the “PROXIMITY” Alert type.

Response data

Response body

Response body format - JSON

1
{
2
  "id": "Id of created alert rule",
3
  "covers": [
4
    "Id of covered other alert rule",
5
    "Id of covered other different alert rule"
6
  ]
7
}

Response fields

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

Primary fields	Description
`id` string	The UUID of the Alert Rule.
`covers` array	The list of UUID Alerts covered by the already created Alert Rules.

Response codes

Code	Meaning & possible causes
`201`	Created
`400`	Bad 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. Alert type is not provided. Alert type is incorrect. Notification group id is not provided. Notification group id is incorrect. Bad request for TRANSITION alert type: Transition type is not provided. Transition type is incorrect. Bad request for DWELL alert type: Maximum dwell time is not provided. Maximum dwell time is a non-integer. Maximum dwell time is negative. Bad request for OBJECT_COUNT alert type: Maximum object count is not provided. Maximum object count is a non-integer. Maximum object count is negative. Bad request for PROXIMITY alert type: ProximityDistance is not provided. ProximityDistance is not a number. ProximityDistance cannot be greater than 10000. ProximityDistance cannot be smaller than 1. ProximitySide is not provided. ProximitySide is not a valid string value.
`403`	Forbidden: Provided Admin Key is invalid. Admin Key is missing.

Code

Meaning & possible causes

201

Created

400

Bad 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.
Alert type is not provided.
Alert type is incorrect.
Notification group id is not provided.
Notification group id is incorrect.

Bad request for TRANSITION alert type:

Transition type is not provided.
Transition type is incorrect.

Bad request for DWELL alert type:

Maximum dwell time is not provided.
Maximum dwell time is a non-integer.
Maximum dwell time is negative.

Bad request for OBJECT_COUNT alert type:

Maximum object count is not provided.
Maximum object count is a non-integer.
Maximum object count is negative.

Bad request for PROXIMITY alert type:

ProximityDistance is not provided.
ProximityDistance is not a number.
ProximityDistance cannot be greater than 10000.
ProximityDistance cannot be smaller than 1.
ProximitySide is not provided.
ProximitySide is not a valid string value.

403

Forbidden:

Provided Admin Key is invalid.
Admin Key is missing.

Examples

Create a new Transition Alert Rule for all Fences in the Configuration.

URL request example

post

URL request example

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

POST body request example

post

POST body request example - JSON

1
{
2
  "name": "Airport transition alert",
3
  "project": "47b10143-0b43-4803-a931-98cb1e595520",
4
  "fence": "*",
5
  "object": "fc94720b-23cd-4ddf-a560-00f8518e43c9",
6
  "alertType": "TRANSITION",
7
  "alertRuleConstraints": {
8
    "transitionType": "ALL"
9
  },
10
  "notificationGroup": "358a3348-26d6-4d9d-8d5a-c3de41b26f63",
11
  "enabled": true
12
}

Response body example

Response body example - JSON

1
{
2
  "id": "bf40406b-1d8d-4218-bcf2-e67b83063d02",
3
  "covers": []
4
}

Create a new Dwell Time Alert Rule for all Objects in the Configuration.

URL request example

post

URL request example

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

POST body request example

post

POST body request example - JSON

1
{
2
  "name": "24-hour parking #5 alert",
3
  "project": "47b10143-0b43-4803-a931-98cb1e595520",
4
  "fence": "0b16633b-7b2b-4fd6-a834-f36c2250ab66",
5
  "object": "*",
6
  "alertType": "DWELL",
7
  "alertRuleConstraints": {
8
    "maxDwellTime": 600
9
  },
10
  "notificationGroup": "8e34613a-2324-4749-ac9d-25bf7a91d218",
11
  "enabled": true
12
}

Response body example

Response body example - JSON

1
{
2
  "id": "a5e0e694-851e-4b6e-9c35-0dee908165c1",
3
  "covers": [
4
    "c30520d9-e5bc-4522-8e4b-02e595e4784c",
5
    "8378399e-169e-4963-a22d-950e137ae1ef"
6
  ]
7
}

Create a new Object Count Alert Rule.

URL request example

post

URL request example

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

POST body request example

post

POST body request example - JSON

1
{
2
  "name": "City parking #7 with a capacity of 20 cars",
3
  "project": "47b10143-0b43-4803-a931-98cb1e595520",
4
  "fence": "0b16633b-7b2b-4fd6-a834-f36c2250ab66",
5
  "alertType": "OBJECT_COUNT",
6
  "alertRuleConstraints": {
7
    "maxObjectCount": 20
8
  },
9
  "notificationGroup": "8e34613a-2324-4749-ac9d-25bf7a91d218",
10
  "enabled": true
11
}

Response body example

Response body example - JSON

1
{
2
  "id": "f19df201-09f1-4ac2-84ce-913658c32c2e",
3
  "covers": ["303cc7cf-038e-420a-b14a-e9f52fbf741e"]
4
}

Create a new Proximity Alert Rule

URL request example

post

URL request example

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

POST body request format

post

POST body request format - JSON

1
{
2
  "name": "Driver is approaching the end of the safety zone",
3
  "project": "47b10143-0b43-4803-a931-98cb1e595520",
4
  "fence": "0b16633b-7b2b-4fd6-a834-f36c2250ab66",
5
  "object": "*",
6
  "alertType": "PROXIMITY",
7
  "alertRuleConstraints": {
8
    "proximityDistance": 1000,
9
    "proximitySide": "OUTSIDE"
10
  },
11
  "notificationGroup": "8e34613a-2324-4749-ac9d-25bf7a91d218",
12
  "enabled": true
13
}

Response body example

Response body example - JSON

1
{
2
  "id": "274c7ff0-8030-4b67-a239-aa9f62cefef0",
3
  "covers": []
4
}

Create alert rule

Decommission notice

Purpose

Request data

HTTPS method: POST

URL request format

curl command requestformat

Request parameters

POST request body

POST request body fields

Response data

Response body

Response fields

Response codes

Examples

URL request example

POST body request example

Response body example

URL request example

POST body request example

Response body example

URL request example

POST body request example

Response body example

URL request example

POST body request format

Response body example

HTTPS method: `POST`