> ## Documentation Index
> Fetch the complete documentation index at: https://docsy3.mile.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Update alert setting
> Updates the alert setting of your organization. Send at least one flag; flags you leave out keep their current value. Every flag is a boolean. You can also send the editable limits (`overspeedSpeedKmh`, `idleDistanceMeters`, `idleWindowMinutes`, `latenessGraceMinutes`, `routeDeviationDistanceMeters`, `lowBatteryPercent`, `driverOfflineMinutes`) as whole numbers within their ranges; a body with only limits is valid and leaves the switches unchanged. A limit that is not a whole number or is out of range returns `400` with `failedCode` `alert-009` and nothing is saved. A change applies to detections after it is saved; alerts already recorded do not change. `thresholds` itself is ignored when sent. Returns the full setting after the update.
Requires permission `edit/alertSetting`.
## OpenAPI
````yaml /openapi/public/openapi-monitoring.json put /alert-setting
openapi: 3.0.0
info:
title: API - Monitoring
version: 3.0.0
description: API Documentation - RESTful API for field operations management.
servers:
- url: https://apiweb.mile.app/api/v3
security:
- bearerAuth: []
tags:
- name: Alert
description: >-
An alert is an event raised while monitoring field users and vehicles, for
example entering or leaving a geofence, idling too long, a predicted late
task, a route deviation, driving above the speed limit or a panic button
press. You can list alerts, read a daily summary, and mark them resolved.
These endpoints are served under `/api/v4`.
- name: Alert Setting
description: >-
Alert settings switch each alert type on or off for your organization.
They also return the limits each alert type fires on. These endpoints are
served under `/api/v4`.
- name: Geofence
description: >-
A geofence is an area drawn on the map, as a polygon or a circle. Alerts
and automations can react when a field user enters or leaves it, or stays
inside longer than its dwell time.
- name: Geofence Group
description: >-
Geofence groups organize geofences so you can filter and manage them
together.
paths:
/alert-setting:
servers:
- url: https://apiweb.mile.app/api/v4
put:
tags:
- Alert Setting
summary: Update alert setting
description: >-
Updates the alert setting of your organization. Send at least one flag;
flags you leave out keep their current value. Every flag is a boolean.
You can also send the editable limits (`overspeedSpeedKmh`,
`idleDistanceMeters`, `idleWindowMinutes`, `latenessGraceMinutes`,
`routeDeviationDistanceMeters`, `lowBatteryPercent`,
`driverOfflineMinutes`) as whole numbers within their ranges; a body
with only limits is valid and leaves the switches unchanged. A limit
that is not a whole number or is out of range returns `400` with
`failedCode` `alert-009` and nothing is saved. A change applies to
detections after it is saved; alerts already recorded do not change.
`thresholds` itself is ignored when sent. Returns the full setting after
the update.
Requires permission `edit/alertSetting`.
operationId: updateAlertSetting
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AlertSettingUpdateRequest'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: boolean
description: Status of response.
message:
description: Message of API response.
type: string
data:
description: >-
Full alert setting after the update, including the
effective `thresholds`.
type: object
properties:
thresholds:
$ref: '#/components/schemas/AlertSettingThresholds'
additionalProperties: true
example:
status: true
message: Success
data:
geofence: true
idle: true
lateness: false
routeDeviation: false
overspeed: false
lowBattery: false
driverOffline: false
geofenceNotification: true
idleNotification: false
latenessNotification: true
routeDeviationNotification: true
overspeedNotification: true
lowBatteryNotification: true
driverOfflineNotification: true
updatedBy: admin@example.com
updatedTime: '2026-10-10T04:00:00.000Z'
thresholds:
overspeed:
speedKmh: 60
consecutivePings: 3
repeatMinutes: 10
idle:
distanceMeters: 50
windowMinutes: 30
repeatMinutes: 10
lateness:
graceMinutes: 2
routeDeviation:
distanceMeters: 150
consecutivePings: 3
lowBattery:
percent: 15
resetPercent: 25
repeatMinutes: 30
driverOffline:
minutes: 30
'400':
description: >-
Bad Request. `failedCode` is `alert-009` when a limit is not a whole
number or is out of its range, `alert-010` when a flag is not a
boolean, and `alert-001` when the body has no known field.
content:
application/json:
schema:
type: object
properties:
status:
type: boolean
description: Shows if the request was successful.
message:
type: string
description: A short message explaining what went wrong.
example:
status: false
message: Bad request - invalid parameters provided.
deprecated: false
security:
- bearerAuth: []
components:
schemas:
AlertSettingUpdateRequest:
type: object
description: At least one of the flags or limits is required.
properties:
geofence:
type: boolean
description: |-
Record geofence enter and leave alerts. Default `false`.
**Example:** `true`
idle:
type: boolean
description: |-
Record idle alerts (user stopped moving). Default `false`.
**Example:** `true`
lateness:
type: boolean
description: |-
Record predicted task lateness alerts. Default `false`.
**Example:** `false`
routeDeviation:
type: boolean
description: |-
Record route deviation alerts. Default `false`.
**Example:** `false`
overspeed:
type: boolean
description: >-
Record overspeed alerts (user drove above the speed limit). Default
`false`.
**Example:** `true`
lowBattery:
type: boolean
description: >-
Record low battery alerts (the phone battery of a user is at or
below the battery limit). Default `false`.
**Example:** `true`
driverOffline:
type: boolean
description: >-
Record driver offline alerts (a user on a trip sent no location for
the offline limit). Default `false`.
**Example:** `true`
geofenceNotification:
type: boolean
description: >-
Also send recorded geofence alerts to the notification bell. Default
`true`.
**Example:** `true`
idleNotification:
type: boolean
description: >-
Also send recorded idle alerts to the notification bell. Default
`true`.
**Example:** `false`
latenessNotification:
type: boolean
description: >-
Also send recorded lateness alerts to the notification bell. Default
`true`.
**Example:** `true`
routeDeviationNotification:
type: boolean
description: >-
Also send recorded route deviation alerts to the notification bell.
Default `true`.
**Example:** `true`
overspeedNotification:
type: boolean
description: >-
Also send recorded overspeed alerts to the notification bell.
Default `true`.
**Example:** `true`
lowBatteryNotification:
type: boolean
description: >-
Also send recorded low battery alerts to the notification bell.
Default `true`.
**Example:** `true`
driverOfflineNotification:
type: boolean
description: >-
Also send recorded driver offline alerts, and the second
notification when the driver is back online, to the notification
bell. Default `true`.
**Example:** `true`
overspeedSpeedKmh:
type: integer
minimum: 20
maximum: 200
description: >-
Speed limit of the overspeed alert, in km/h. Only a location update
faster than this counts; exactly this speed does not. Whole number
from 20 to 200. Default `80`.
**Example:** `60`
idleDistanceMeters:
type: integer
minimum: 10
maximum: 1000
description: >-
The user counts as idle when they move less than this distance, in
metres, within `idleWindowMinutes`. Whole number from 10 to 1000.
Default `50`.
**Example:** `50`
idleWindowMinutes:
type: integer
minimum: 5
maximum: 120
description: >-
Time window the idle distance is measured over, in minutes. Whole
number from 5 to 120. Default `30`.
**Example:** `30`
latenessGraceMinutes:
type: integer
minimum: 0
maximum: 60
description: >-
A lateness alert is raised when the predicted arrival is more than
this many minutes after the planned ETA. Whole number from 0 to 60.
Default `2`.
**Example:** `2`
routeDeviationDistanceMeters:
type: integer
minimum: 76
maximum: 2000
description: >-
Distance from the planned route that counts as off-route, in metres.
Whole number from 76 to 2000. Default `150`.
**Example:** `150`
lowBatteryPercent:
type: integer
minimum: 2
maximum: 60
description: >-
Battery limit of the low battery alert, in percent. An alert is
raised when a location update reports a level at or below this.
Whole number from 2 to 60. Default `15`.
**Example:** `15`
driverOfflineMinutes:
type: integer
minimum: 10
maximum: 120
description: >-
Minutes without a location after which a user on a trip is offline.
Whole number from 10 to 120. Default `30`.
**Example:** `30`
example:
geofence: true
idle: true
idleNotification: false
overspeedSpeedKmh: 60
AlertSettingThresholds:
type: object
description: >-
Effective limits each alert type fires on for your organization, as the
server applies them. Geofence has no entry. Change a limit by sending
its flat field (for example `overspeedSpeedKmh`) in `PUT
/alert-setting`; this object itself is ignored when sent.
properties:
overspeed:
type: object
description: Limits of the overspeed alert.
properties:
speedKmh:
type: integer
description: >-
Speed limit, in km/h. Only a location update faster than this
counts; exactly this speed does not.
consecutivePings:
type: integer
description: Location updates in a row above the limit that raise an alert.
repeatMinutes:
type: integer
description: >-
Minutes between repeated alerts while the user keeps speeding.
The same time without a fast location update ends the episode.
idle:
type: object
description: Limits of the idle alert.
properties:
distanceMeters:
type: integer
description: >-
The user counts as idle when they move less than this distance,
in metres, within `windowMinutes`.
windowMinutes:
type: integer
description: Time window the distance is measured over, in minutes.
repeatMinutes:
type: integer
description: Minutes between repeated alerts while the user is still idle.
lateness:
type: object
description: Limits of the predicted lateness alert.
properties:
graceMinutes:
type: integer
description: >-
An alert is raised when the predicted arrival is more than this
many minutes after the planned ETA.
routeDeviation:
type: object
description: Limits of the route deviation alert.
properties:
distanceMeters:
type: integer
description: >-
Distance from the planned route that counts as off-route, in
metres.
consecutivePings:
type: integer
description: Off-route location updates in a row that raise an alert.
lowBattery:
type: object
description: Limits of the low battery alert.
properties:
percent:
type: integer
description: >-
Battery limit, in percent. A level at or below it raises an
alert.
resetPercent:
type: integer
description: >-
The alert can be raised again once the battery has been at or
above this level (the limit plus 10).
repeatMinutes:
type: integer
description: >-
Minutes between repeated alerts while the battery stays at or
below the limit.
driverOffline:
type: object
description: Limit of the driver offline alert.
properties:
minutes:
type: integer
description: >-
Minutes without a location after which a user on a trip is
offline. Default `30`.
example:
overspeed:
speedKmh: 80
consecutivePings: 3
repeatMinutes: 10
idle:
distanceMeters: 50
windowMinutes: 30
repeatMinutes: 10
lateness:
graceMinutes: 2
routeDeviation:
distanceMeters: 150
consecutivePings: 3
lowBattery:
percent: 15
resetPercent: 25
repeatMinutes: 30
driverOffline:
minutes: 30
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Use a valid Bearer token to authenticate.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.