Devices and Telemetry API

The Devices API works one level below the Vehicles API. A vehicle is the business entity (registration number, owner, group); a device is the tracker hardware that reports it, identified by its IMEI. Use these endpoints when you need raw telemetry, IMEI-first lookups, or hardware inventory views.

Every request requires the same credentials as the rest of the Livepin API:

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

See Authentication to exchange your API key for a JWT.

Device model

Name
id
Type
integer
Description
Internal device identifier.
Name
imei
Type
string
Description
Tracker IMEI. The hardware identity used by all telemetry endpoints.
Name
vehicle
Type
object
Description
Relation to the vehicle this device reports for.
Name
active
Type
boolean
Description
Whether the device is currently active. Defaults to false.
Name
gps_model
Type
object
Description
GPS tracker model, including model_name, company, and credit_usage.
Name
allowed_plan
Type
object
Description
Plan linked to this device.
Name
is_primary
Type
boolean
Description
Primary device indicator. Defaults to true.
Name
sim_no
Type
string
Description
SIM card number.
Name
relay_control
Type
boolean
Description
Whether relay (engine cut-off) control is supported.
Name
on_demand_tracking
Type
boolean
Description
Whether on-demand tracking is enabled.
Name
fuel_monitoring
Type
boolean
Description
Whether fuel monitoring is enabled.
Name
buzzer_sound
Type
boolean
Description
Whether buzzer control is supported.
Name
expiry
Type
date
Description
Subscription expiry date.
Name
is_dashcam
Type
boolean
Description
Dashcam capability indicator. Defaults to false.
Name
dashcam_total_channels
Type
integer
Description
Number of dashcam channels. Defaults to 0.

Device lookup

Name
GET /api/devices/imei/:imei
Description
Get a device by IMEI, with all relations populated.
Name
GET /api/devices/by-gps-model/:gps_model_id
Description
List devices for a GPS model, with custody status.
Name
GET /api/devices
Description
Standard device list (CRUD find).
Name
GET /api/devices/:id
Description
Get a single device by ID.
Name
POST /api/devices
Description
Create a device.
Name
PUT /api/devices/:id
Description
Update a device.
Name
DELETE /api/devices/:id
Description
Delete a device.

Get device by IMEI

GET

/api/devices/imei/:imei

curl "$LIVEPIN_API_BASE_URL/api/devices/imei/352592573176740" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Query parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number.
`pageSize`	integer	`10`	Items per page.
`computed_status`	string	—	Filter by `DEPLOYED`, `FLAGGED`, `WITH_YOU`, or `WITH_OTHER`.

Devices by GPS model

GET

/api/devices/by-gps-model/:gps_model_id

curl -G "$LIVEPIN_API_BASE_URL/api/devices/by-gps-model/17" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d page=1 \
  -d pageSize=10 \
  -d computed_status=DEPLOYED

computed_status resolves against the caller. A device assigned to you reports WITH_YOU; the same device viewed by another user reports WITH_OTHER.

Location history

Raw telemetry history lives on the device, so these endpoints are keyed by IMEI or device ID. Each record is a single tracker packet, not a trip.

Name
GET /api/devices/imei/:imei/location-history
Description
Location history for an IMEI, by date or timestamp range.
Name
GET /api/devices/location-history/:device_id
Description
Location history for a device ID (date only).

Parameters

Name
record_date
Type
string
Description
Single day in D/M/YYYY format, for example 29/4/2026. Defaults to today.
Name
start_timestamp
Type
integer
Description
Range start in milliseconds since epoch. Requires end_timestamp.
Name
end_timestamp
Type
integer
Description
Range end in milliseconds since epoch. Requires start_timestamp.

History by date

GET

/api/devices/imei/:imei/location-history

curl -G "$LIVEPIN_API_BASE_URL/api/devices/imei/352592573176740/location-history" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d record_date=29/4/2026

History by timestamp range

GET

/api/devices/imei/:imei/location-history

curl -G "$LIVEPIN_API_BASE_URL/api/devices/imei/352592573176740/location-history" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d start_timestamp=1732080473000 \
  -d end_timestamp=1732084073000

Latest location

Return the most recent packet for a device, read from the realtime store rather than from history tables. This is the fastest way to place a vehicle on a map.

Name
POST /api/devices/latest-location
Description
Latest location for an imei or a vehicle_no. Provide at least one.

Latest location

POST

/api/devices/latest-location

curl -X POST "$LIVEPIN_API_BASE_URL/api/devices/latest-location" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vehicle_no":"DUMMY-VEHICLE-301"}'

POST /api/devices/latest-location is a POST because it accepts either an imei or a vehicle_no in the body. The include the vehicle_no case, pass the vehicle registration number exactly as stored.

Geocoding and routing

Turn coordinates into addresses, addresses into coordinates, and compute a driving route from a vehicle's current position to a destination.

Name
GET /api/devices/reverse-geocode
Description
Resolve latitude and longitude into an address.
Name
GET /api/devices/geocode
Description
Resolve an address string into coordinates.
Name
GET /api/devices/auto-suggest-address
Description
Address autocomplete suggestions for a search query.
Name
GET /api/devices/generate-route
Description
Driving route from a vehicle's latest position to a destination.
Name
POST /api/devices/generate-route
Description
Identical to the GET variant. Parameters are read from the query string.

Reverse geocode

GET

/api/devices/reverse-geocode

curl -G "$LIVEPIN_API_BASE_URL/api/devices/reverse-geocode" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d latitude=13.633925 \
  -d longitude=80.01978

Geocode address

GET

/api/devices/geocode

curl -G "$LIVEPIN_API_BASE_URL/api/devices/geocode" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d address="Kempegowda International Airport"

Parameter	Type	Default	Description
`query`	string	—	Required. Minimum 3 characters.
`latitude`	number	—	Bias results near this latitude. Send with `longitude`.
`longitude`	number	—	Bias results near this longitude. Send with `latitude`.
`radius`	number	—	Bias radius in metres.
`country`	string	`IN`	ISO country code to restrict results.

Address autocomplete

GET

/api/devices/auto-suggest-address

curl -G "$LIVEPIN_API_BASE_URL/api/devices/auto-suggest-address" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d query="KIAL" \
  -d latitude=13.2 \
  -d longitude=77.7

Parameter	Type	Description
`imei`	string	Required. Route origin is this device's latest known position.
`destination_latitude`	number	Destination latitude.
`destination_longitude`	number	Destination longitude.
`destination_place_id`	string	Alternative to coordinates. Resolved to lat/lng server-side.

Generate route

GET

/api/devices/generate-route

curl -G "$LIVEPIN_API_BASE_URL/api/devices/generate-route" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d imei=352592573176740 \
  -d destination_latitude=13.1989 \
  -d destination_longitude=77.7068

Both GET and POST /api/devices/generate-route read their arguments from the query string. A JSON body is ignored.

Device custody

Track who physically holds a device. Custody is useful for installer and dealer workflows where hardware moves between people before it is fitted.

Name
POST /api/devices/assign-custody
Description
Assign a device to a user. Body: deviceId and userId.
Name
GET /api/trips/handovers
Description
List handovers between users.
Name
PUT /api/trips/handovers/confirm
Description
Confirm a handover as the recipient, which transfers custody.

Assign custody

curl -X POST "$LIVEPIN_API_BASE_URL/api/devices/assign-custody" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"deviceId":41,"userId":931}'

Response

{ "message": "Custody assigned successfully" }

Live tracking (RTT)

Real-time tracking endpoints for mobile and link-sharing flows. These resolve short-lived tracking identifiers rather than full vehicle records.

Name
GET /api/rtt-tracking/get-trip-tracking-location
Description
Position for a trackingId, including extra_data.
Name
GET /api/rtt-tracking/get-latest-tracking-location
Description
Latest position for a mobileNo.
Name
GET /api/rtt-tracking/get-imei-latest-location
Description
Latest legacy location record for an imei.
Name
GET /api/rtt-tracking/get-imei-based-on-vehicle-number
Description
Resolve a vehicleNumber to its device record.

Tracking by ID

GET

/api/rtt-tracking/get-trip-tracking-location

curl -G "$LIVEPIN_API_BASE_URL/api/rtt-tracking/get-trip-tracking-location" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d trackingId=<TRACKING_ID>

Latest by mobile

GET

/api/rtt-tracking/get-latest-tracking-location

curl -G "$LIVEPIN_API_BASE_URL/api/rtt-tracking/get-latest-tracking-location" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d mobileNo=%2B919999999999

IMEI by vehicle number

GET

/api/rtt-tracking/get-imei-based-on-vehicle-number

curl -G "$LIVEPIN_API_BASE_URL/api/rtt-tracking/get-imei-based-on-vehicle-number" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d vehicleNumber=DUMMY-VEHICLE-301

Continue to Trips API