This tutorial explains how to set up monitors using the REST API. In order to do so, we will need to understand how to configure the notification and set up a triggering policy.
Post Monitor Request #
The following example is the structure of the HTTP request intended to set up the monitor according to the needs of a third party App.
The following path parameters are required, they need to be replaced by the appropriate value:
- {chId} is the id of the channel.
1
2
3
4
5
6
7
$ curl \
--POST \
--url /accounts/channels/{chId}/monitors \
--data 'client_id=<client_id>' \
--header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
--cert 'path/to/client_cert.pem[:<cert_password>]' \
--key 'path/to/key.pem' \
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
{
"label": "string",
"subscribeParam": {
"refreshEvent": 60,
"channelAttributes": {
"pushnotif": [
{
"type": "Header",
"key": "X-Vehicle_Id",
"value": "$Vin"
}
],
"webhook": [
[
{
"type": "Header",
"key": "X-Vehicle_Id",
"value": "$Vin"
}
]
],
"websocket": [
[
{
"type": "Header",
"key": "X-Vehicle_Id",
"value": "$Vin"
}
]
]
}
},
"onEvent": {
"actions": [
{
"type": "Notify",
"monitorAction": {
"changeType": "Pause",
"monitorId": "string"
},
"remoteAction": {
"ChannelId": "_-2_5B-_1_b_b_-",
"remote": {
"label": "string",
"attributes": [
{
"type": "Body",
"key": "string",
"value": "string"
}
],
"channelAttributes": {
"pushnotif": [
{
"type": "Header",
"key": "X-Vehicle_Id",
"value": "$Vin"
}
],
"webhook": [
[
{
"type": "Header",
"key": "X-Vehicle_Id",
"value": "$Vin"
}
]
],
"websocket": [
[
{
"type": "Header",
"key": "X-Vehicle_Id",
"value": "$Vin"
}
]
]
},
"extendedEventParam": [
"vehicle.latestTelemetry"
],
"action": {
"locking": {
"state": "Unlocked"
},
"horn": {
"state": "Activated"
},
"lights": {
"state": "Activated"
},
"preconditioning": {
"airConditioning": {
"immediate": false,
"programs": [
{
"start": "string",
"occurrence": {
"day": [
"Mon"
]
},
"enabled": true,
"temp": 0,
"slot": 4,
"actionsType": "Set"
}
],
"settings": {
"temp": 0,
"mode": "Auto",
"state": "Activated"
}
}
},
"onboardPersonalData": {
"action": "Delete"
},
"charging": {
"charge": {
"immediate": false,
"programs": [
{
"start": "string",
"occurrence": {
"day": [
"Mon"
]
},
"enabled": true,
"end": "string",
"chargeToFull": true,
"minChargingLevel": 50,
"maxChargingLevel": 100,
"chargeType": "Regular",
"slot": 2,
"actionsType": "Set"
}
],
"settings": {
"chargePreferenceRate": "Low",
"chargeLimit": "MedPlus"
}
}
},
"wakeup": {
"action": "Wakeup"
},
"immobilization": {
"activate": true
},
"navigation": {
"positions": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
5.970338,
-62.536239
]
},
"properties": {
"address": {
"houseNumber": "string",
"postalCode": 0,
"streetName": "string",
"cityName": "string",
"countryName": "string",
"provinceName": "string"
},
"placeid": 0,
"name": "Doltone House",
"category": "Restraunt",
"description": "",
"phoneNumber": "+61 2 1234 5678",
"url": "string"
}
}
]
},
"vehicleFinder": {
"action": "GetPresentLocation"
},
"stolen": {
"state": true,
"crankInhibit": {
"activate": true
}
},
"tan": {
"suppress": {
"state": true,
"duration": 5
},
"confirm": {
"state": true
}
}
}
}
}
}
],
"onRefresh": false
},
"attributes": [
{
"type": "Body",
"key": "string",
"value": "string"
}
],
"extendedEventParam": [
"vehicle.doorsState"
],
"triggerParam": {
"triggers": [
{
"name": "\"yjxQQocgGqRlISqlhebicbuMdrXKiVCViAVXwCaLEUZMhctLJsccHsJZRKClpTbbOWgGuqgwqdCnZkiaaZwOIYmpV_39627472988157946618827322834207962461611165\"",
"zone": {
"transition": "Out",
"place": {
"radius": 20,
"center": {
"longitude": 2.333333,
"latitude": 48.866667
}
}
},
"time": {
"times": [
{
"recurrence": "Daily",
"start": "PT8H30M",
"duration": "PT7H30M",
"occurrence": [
"Mon",
"Tue",
"Thu",
"Fri"
]
}
],
"timeZone": "Europe/Paris"
},
"data": {
"data": "vehicle.energy.electric.level",
"op": "greaterThan",
"value": [
"75"
]
},
"setting": {
"type": "DigitalKey"
}
}
],
"boolExp": "((z1 & t1) | (z2 & !t1) | (f & z1) | (a & (z1|t)) | (o & (z1 | z2)))"
}
}
Below is a description of the JSON body to configure the monitor, refer to API Reference for the specification of this endpoint.
labelis the name of the monitor.subscribeParamis the Monitor channel subscription extension:- refreshEvent: Define the period (in sec.) between two refresh events. The refresh events are sent when the condition of the monitor is satisfied(Trigger -> toggled true) after a period >= refresh time because the monitor triggering is conditioned by the vehicle activity and so its data availability . A kind of periodic reminder.
- channelAttributes: Additional attributes that will add to or replace the specific channel (pushnotif, webhook or websocket) ones when sending the event.
extendedEventParam: Allow to set extra vehicle data (defined in data model) to add to the monitor event when publishing.triggerParam: Monitor trigger-param that allows to compound triggers by applying a boolean expression to evaluate them:- triggers is where to declare the triggering event blocs.
- boolExp allows to setup the triggering policy.
Note: Each monitor can target only fleet only. However, it’s possible to create multiple monitors for multiple fleets.
Post Monitor Response #
If the monitor request is properly set-up, the monitor will be created and an HTTP response will be returned:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"createdAt": "2025-07-09T04:54:40.045Z",
"_links": {
"monitor": {
"href": "string",
"templated": true,
"type": "string",
"deprecation": "string",
"name": "string",
"title": "string",
"profile": "string",
"hreflang": "string"
}
},
"monitorId": "string",
"status": "Running"
}
This message indicates that the monitor has been successfully created with a unique identifier. This identifier is sent with every notification, therefore, it allows tracking this monitor.
Triggering Events Blocs #
As seen in the about page, monitors are triggered under the following patterns. Checkout the API Reference for the specification of trigger events.
- 🗺️ Zone: Zone Alert parameter object.
- ⏱️ Time: Temporal monitor for triggering vehicle moving event within a time interval.
- 🚗 Data: A monitor for triggering the vehicle data change event.
- ⚙️ Setting: A monitor for triggering the vehicle settings change event.
The array triggerParam.trigger of the monitor creation request allows declaring and name the list of triggering event blocs.
Declaration of event blocs is not enough to describe the way the callback is being triggered, they must be used in the triggerParam.boolExp field in order to set up the triggering policy of this monitor.
Triggering Policy #
Once the triggers blocs are declared, they need to be combined together to create a triggering policy. To do so, we use a boolean expression syntax:
Grammar: Here is the list of available operands for monitors configuration.
- AND:
trigger1 & trigger2if both conditions have to be triggered- OR:
trigger1 | trigger2if at least one condition has to be triggered- PARENTHESIS:
trigger1 | (trigger2 & trigger3)to prioritize an expression over another- NOT:
!trigger1if the condition has to not be triggered
This is an example of boolean expression, where z1, z2, t1, t2, o1, o2, o3 are trigger bloc names:
1
2
3
4
5
6
7
8
9
10
11
{
"label": "<monitor-name>",
"subscribeParam": { },
"triggerParam": {
"triggers": [
{"name": "z1" }, {"name": "z2" }, {"name": "t1" }, {"name": "t2" },
{"name": "o1" }, {"name": "o2" }, {"name": "o3" }
],
"boolExp": "((z1 & t1) | (z2 & !t1) | (o1 & z1) | (o2 & (z1 | t2)) | (o3 & (z1 | z2)))"
}
}
In this boolean expression, the monitor will notify the server in all these situations:
- (z1 & t1) = z1 AND t1 are being triggered
- (z2 & !t1) = z2 is triggered AND t1 is NOT triggered
- (o1 & z1) = o1 is triggered AND z1 is triggered
- (o2 & (z1 | t2)) = o2 is triggered AND either z1 OR t2 is triggered
- (o3 & (z1 | z2)) = o3 is triggered AND either z1 OR z2 is triggered
Examples: Time Trigger #
The monitor Time Trigger Entry that specifies the start (relative or absolute) and duration of the time interval. The relative start time must be to midnight and the absolute must be expressed in UTC.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
"label": "Monitor {{$randomInt}}",
"subscribeParam": {
"refreshEvent": 80,
"channelAttributes": {
"webhook": [
{
"type": "Header",
"key": "X-vehicle-id",
"value": "$Vin"
}
]
}
},
"triggerParam": {
"triggers": [
{
"name": "t1",
"time": {
"times": [
{
"duration": "PT3H12M",
"start": "1990-05-25T15:30:00Z",
"recurrence": "None",
"occurrence": {
"day": [
"Tue"
]
},
"enabled": true
}
],
"timeZone": "Europe/Paris"
}
}
],
"boolExp": "t1"
}
}
Example: Zone Trigger #
Zone monitoring type (‘In’ for monitoring entering zone and ‘Out’ for monitoring leaving zone).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
"label": "Monitor {{$randomInt}}",
"subscribeParam": {
"refreshEvent": 60,
"channelAttributes": {
"pushnotif": [
{
"type": "Body",
"key": "disableNotificationPayload",
"value": "true"
},
{
"type": "Query",
"key": "deliveryPriority",
"value": "low"
}
]
}
},
"triggerParam": {
"triggers": [
{
"name": "t6",
"zone": {
"transition": "In",
"place": {
"radius": 10,
"center": {
"longitude": -80,
"latitude": 68
}
}
}
}
],
"boolExp": "t6"
}
}
Example: Data Trigger #
A monitor for triggering the vehicle data change event.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
"label": "Monitor {{$randomInt}}",
"subscribeParam": {
"refreshEvent": 60,
"channelAttributes": {
"websocket": [
{
"type": "Header",
"key": "X-Vehicle_Id",
"value": "$Vin"
}
]
}
},
"triggerParam": {
"triggers": [
{
"name": "t6",
"data": {
"op": "includedIn",
"value": [
"AssistanceButtonFault"
],
"data": "vehicle.alert",
"previous": {
"op": "equalsTo",
"value": [
"AssistanceButtonFault"
]
}
}
}
],
"boolExp": "t6"
}
}