Notifications API

Livepin generates alerts from tracker telemetry — overspeed, SOS, ignition, battery, geofence crossings, and more. Use these endpoints to control which alerts a vehicle raises, to read the alert feed, and to register the push tokens that deliver them.

All endpoints require the standard credentials:

x-api-key: <YOUR_API_KEY>
Authorization: Bearer <JWT_TOKEN>

To have alerts delivered to your own backend instead of (or as well as) a mobile app, see Webhooks.

Notification model

Per-vehicle notification preferences are stored as a notification entity.

Name
id
Type
integer
Description
Internal notification preference ID.
Name
vehicle
Type
object
Description
Vehicle the preferences apply to.
Name
overspeed
Type
boolean
Description
Alert on overspeed events. Defaults to true.
Name
overspeed_limit
Type
integer
Description
Speed threshold in km/h. Defaults to 60.
Name
engine_on
Type
boolean
Description
Alert on ignition on. Defaults to true.
Name
geofence_events
Type
boolean
Description
Alert on geofence entry and exit. Defaults to false.
Name
renewal
Type
boolean
Description
Alert on subscription renewal. Defaults to true.
Name
safe_parking
Type
boolean
Description
Alert on safe parking events. Defaults to false.

Device tokens

Register the push token used to deliver mobile notifications to a user. The token is stored on the active session, so each sign-in can carry its own device token.

Name
POST /api/notifications/update-fcm-token
Description
Register or replace the FCM token for the current session.

Body

Name
fcm_token
Type
string
Description
Required. Firebase Cloud Messaging registration token.

Request

curl -X POST "$LIVEPIN_API_BASE_URL/api/notifications/update-fcm-token" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fcm_token":"<FCM_TOKEN>"}'

Response

{ "message": "FCM Token updated successfully" }

Call this again whenever the push token rotates, and after every sign-in on a new device. Signing out clears the token.

Notification types

The catalogue of alert types the platform can raise.

Name
GET /api/notifications/types
Description
Returns the configured notification type catalogue.

Request

curl "$LIVEPIN_API_BASE_URL/api/notifications/types" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Response

[
  "safe_parking",
  "overspeed",
  "engine_status",
  "low_battery",
  "low_external_voltage",
  "sos",
  "vibration",
  "wire_disconnect",
  "geofence_exit",
  "geofence_enter"
]

Vehicle preferences

Read and update which alerts a specific vehicle raises.

Name
GET /api/notifications/vehicle-preferences/:vehicle_id
Description
Read preferences for a vehicle. Creates a default record on first read.
Name
POST /api/notifications/update-preferences/:vehicle_id
Description
Update preferences. Only the fields you send are changed.

Updatable fields

Name
overspeed
Type
boolean
Description
Enable or disable overspeed alerts.
Name
overspeed_limit
Type
integer
Description
Speed threshold in km/h.
Name
engine_on
Type
boolean
Description
Enable or disable ignition alerts.
Name
geofence_events
Type
boolean
Description
Enable or disable geofence alerts.
Name
renewal
Type
boolean
Description
Enable or disable renewal alerts.
Name
safe_parking
Type
boolean
Description
Enable or disable safe parking alerts.

Read preferences

GET

/api/notifications/vehicle-preferences/:vehicle_id

curl "$LIVEPIN_API_BASE_URL/api/notifications/vehicle-preferences/3001" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Update preferences

POST

/api/notifications/update-preferences/:vehicle_id

curl -X POST "$LIVEPIN_API_BASE_URL/api/notifications/update-preferences/3001" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"overspeed":true,"overspeed_limit":80,"geofence_events":true}'

Reading notifications

Name
GET /api/notifications/vehicle-notifications/:vehicle_id
Description
Notifications raised for one vehicle.
Name
GET /api/notifications/alerts
Description
Alert feed across vehicles, trips, or groups.
Name
GET /api/notifications
Description
Standard preference records list.
Name
GET /api/notifications/:id
Description
Get a single preference record.

Vehicle notifications parameters

Name
type
Type
string
Description
Filter by notification type, for example sos or overspeed.
Name
record_date
Type
string
Description
D/M/YYYY. Defaults to today.

Alerts parameters

Name
tripId
Type
string
Description
Return alerts attached to a trip. Takes priority over the filters below.
Name
groupId
Type
string
Description
Return alerts for a vehicle group. Takes priority over vehicle_id.
Name
vehicle_id
Type
integer
Description
Return alerts for one vehicle. Requires both timestamps.
Name
start_timestamp
Type
integer
Description
Range start in milliseconds since epoch.
Name
end_timestamp
Type
integer
Description
Range end in milliseconds since epoch.
Name
type
Type
string
Description
Filter by notification type.

Vehicle notifications

GET

/api/notifications/vehicle-notifications/:vehicle_id

curl -G "$LIVEPIN_API_BASE_URL/api/notifications/vehicle-notifications/3001" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d record_date=29/4/2026 \
  -d type=sos

Exactly one of tripId, groupId, or vehicle_id + timestamps is required. A request without any of them returns an empty array.

Alerts

GET

/api/notifications/alerts

curl -G "$LIVEPIN_API_BASE_URL/api/notifications/alerts" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d vehicle_id=3001 \
  -d start_timestamp=1732080473000 \
  -d end_timestamp=1732084073000

Continue to Account API