Trips and Operations API

A trip is a single journey made by a vehicle, from pickup to destination, along with the cargo, driver, seals, and photographic evidence captured along the way. Use these endpoints to build dispatch boards, escort tracking, and proof-of-delivery workflows.

All trip endpoints require the standard credentials:

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

Trip model

Name
id
Type
integer
Description
Internal trip identifier.
Name
tripId
Type
string
Description
Business trip identifier. This is the value used by /trips/:tripId/... routes.
Name
vehicle
Type
object
Description
Relation to the vehicle making the trip.
Name
device
Type
object
Description
Relation to the tracker reporting the trip.
Name
driver
Type
object
Description
Relation to the assigned driver.
Name
startTime
Type
datetime
Description
Trip start.
Name
endTime
Type
datetime
Description
Trip end. Null while the trip is in progress.
Name
status
Type
enum
Description
INPROGRESS, COMPLETED, APPROVED, DISAPPROVE, ESCALATED, PAID. Defaults to INPROGRESS.
Name
cargoType
Type
enum
Description
COAL, COKE, IRONORE, OTHER.
Name
pickupPoint
Type
object
Description
Origin location component: latitude, longitude, address.
Name
destination
Type
object
Description
Destination location component: latitude, longitude, address.
Name
pickupLocationId
Type
string
Description
Identifier of the pickup point.
Name
destinationId
Type
string
Description
Identifier of the destination.
Name
journeyLocations
Type
array
Description
Repeatable location components recorded during the journey.
Name
seals
Type
text
Description
Seal numbers applied to the load.
Name
specialInstruction
Type
text
Description
Free-text instructions for the driver.
Name
live_location
Type
object
Description
Populated at read time for active trips.

Evidence media

Name
evidencePicture
Type
array
Description
Pickup evidence photos.
Name
truckFront
Type
media
Description
Pickup photo of the truck front.
Name
truckBack
Type
media
Description
Pickup photo of the truck rear.
Name
truckLeft
Type
media
Description
Pickup photo of the truck left side.
Name
truckRight
Type
media
Description
Pickup photo of the truck right side.
Name
cameraTop
Type
media
Description
Pickup photo of the top camera.
Name
tieLock
Type
media
Description
Photo of the tie lock.
Name
cameraSlip
Type
media
Description
Camera slip photo.
Name
pickupBill
Type
media
Description
Pickup bill photo.
Name
exitEvidencePicture
Type
array
Description
Exit evidence photos.
Name
exitTruckFront
Type
media
Description
Exit photo of the truck front.
Name
exitTruckBack
Type
media
Description
Exit photo of the truck rear.
Name
exitTruckLeft
Type
media
Description
Exit photo of the truck left side.
Name
exitTruckRight
Type
media
Description
Exit photo of the truck right side.
Name
exitCameraTop
Type
media
Description
Exit photo of the top camera.
Name
exitSeal
Type
media
Description
Exit seal photo.
Name
installerGeoPicture
Type
media
Description
Installer geotagged photo.
Name
destinationGeoPicture
Type
media
Description
Destination geotagged photo.

Trip endpoints

Trips use the standard REST collection pattern.

Name
GET /api/trips
Description
List trips.
Name
GET /api/trips/:id
Description
Get one trip.
Name
POST /api/trips
Description
Create a trip.
Name
PUT /api/trips/:id
Description
Update a trip.
Name
DELETE /api/trips/:id
Description
Delete a trip.
Name
GET /api/trips/operations-analytics
Description
Dispatch summary for the current day.
Name
GET /api/trips/custom-vehicle-groups/transport-companies
Description
Distinct transport company names.

List trips

GET

/api/trips

curl -G "$LIVEPIN_API_BASE_URL/api/trips" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d "filters[status][\$eq]=INPROGRESS" \
  -d "sort[0]=startTime:desc" \
  -d "pagination[page]=1" \
  -d "pagination[pageSize]=25" \
  -d "populate=vehicle,driver,device"

Standard collection endpoints expect the body wrapped in data.

Create trip

POST

/api/trips

curl -X POST "$LIVEPIN_API_BASE_URL/api/trips" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "tripId": "TRIP-813",
      "vehicle": 3001,
      "driver": 44,
      "device": 41,
      "startTime": "2026-09-15T04:30:00.000Z",
      "cargoType": "IRONORE",
      "pickupPoint": { "latitude": "13.633925", "longitude": "80.01978", "address": "Example Mine Gate" },
      "destination": { "latitude": "13.1989", "longitude": "77.7068", "address": "Example Plant" },
      "seals": "SL-00124",
      "status": "INPROGRESS"
    }
  }'

Escalations

Escalations record an issue raised against a device or trip — a camera failure, a route deviation, or any operator-defined exception. Each escalation receives a generated ESC-<timestamp> identifier.

Name
POST /api/trips/escalate
Description
Raise an escalation.
Name
GET /api/trips/escalations
Description
List escalations with filters.
Name
PUT /api/trips/escalations/:id
Description
Update an escalation.
Name
DELETE /api/trips/escalations
Description
Bulk delete escalations by ids array.

Create fields

Name
kind
Type
string
Description
Required. Escalation category. CAMERA also flags the device.
Name
issueLabel
Type
string
Description
Required. Short issue label.
Name
deviceId
Type
integer
Description
Required. Device involved.
Name
tripId
Type
integer
Description
Required. Trip involved. Sets the trip status to ESCALATED.
Name
status
Type
string
Description
Defaults to OPEN.
Name
note
Type
string
Description
Defaults to an empty string.

List query parameters

Name
kind
Type
string
Description
Filter by escalation kind.
Name
status
Type
string
Description
Filter by status.
Name
deviceId
Type
integer
Description
Filter by device.
Name
tripId
Type
integer
Description
Filter by trip.
Name
page
Type
integer
Description
Default 1.
Name
limit
Type
integer
Description
Default 20.

Raise escalation

POST

/api/trips/escalate

curl -X POST "$LIVEPIN_API_BASE_URL/api/trips/escalate" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "CAMERA",
    "issueLabel": "Camera offline",
    "deviceId": 41,
    "tripId": 812,
    "status": "OPEN",
    "note": "No feed on channel 2"
  }'

List escalations

GET

/api/trips/escalations

curl -G "$LIVEPIN_API_BASE_URL/api/trips/escalations" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d status=OPEN \
  -d page=1 \
  -d limit=20

The whole request body is applied to the escalation.

Update escalation

PUT

/api/trips/escalations/:id

curl -X PUT "$LIVEPIN_API_BASE_URL/api/trips/escalations/ESC-1776065116000" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"RESOLVED","note":"Camera reseated"}'

Bulk delete

DELETE

/api/trips/escalations

curl -X DELETE "$LIVEPIN_API_BASE_URL/api/trips/escalations" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids":["ESC-1776065116000","ESC-1776065199000"]}'

Handovers

A handover transfers custody of one or more devices from one user to another. The recipient must confirm before custody moves.

Name
POST /api/trips/handovers
Description
Create a pending handover. Body: toUserId, deviceIds.
Name
GET /api/trips/handovers
Description
List handovers. Filters: status, toUserId, fromUserId.
Name
PUT /api/trips/handovers/confirm
Description
Confirm a handover as the recipient. Body: handoverId.

Only the designated recipient can confirm a handover. Any other user receives a 403.

Create handover

POST

/api/trips/handovers

curl -X POST "$LIVEPIN_API_BASE_URL/api/trips/handovers" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"toUserId":931,"deviceIds":[41,42]}'

Confirm handover

PUT

/api/trips/handovers/confirm

curl -X PUT "$LIVEPIN_API_BASE_URL/api/trips/handovers/confirm" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"handoverId":"HO-1776065116000-421"}'

Custom locations

Custom locations are the saved pickup and destination points your operators reuse when creating trips. They are scoped to your account (or parent account).

Name
GET /api/trips/custom-locations
Description
List saved locations.
Name
POST /api/trips/custom-locations/bulk-add
Description
Add locations. Body: locations array.
Name
POST /api/trips/custom-locations/bulk-update
Description
Update locations. Body: updates array.
Name
POST /api/trips/custom-locations/bulk-delete
Description
Delete locations. Body: ids array of location identifiers.

Location fields

Name
latitude
Type
number
Description
Location latitude.
Name
longitude
Type
number
Description
Location longitude.
Name
address
Type
string
Description
Human readable address.

List custom locations

GET

/api/trips/custom-locations

curl "$LIVEPIN_API_BASE_URL/api/trips/custom-locations" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Bulk add

POST

/api/trips/custom-locations/bulk-add

curl -X POST "$LIVEPIN_API_BASE_URL/api/trips/custom-locations/bulk-add" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      { "latitude": 13.633925, "longitude": 80.01978, "address": "Example Mine Gate" },
      { "latitude": 13.1989, "longitude": 77.7068, "address": "Example Plant" }
    ]
  }'

Each entry needs the location id plus the fields to change.

Bulk update

POST

/api/trips/custom-locations/bulk-update

curl -X POST "$LIVEPIN_API_BASE_URL/api/trips/custom-locations/bulk-update" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      { "id": "66e2f1a9c8b4d30012a4f001", "address": "Example Mine Gate 3" }
    ]
  }'

Bulk delete

POST

/api/trips/custom-locations/bulk-delete

curl -X POST "$LIVEPIN_API_BASE_URL/api/trips/custom-locations/bulk-delete" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids":["66e2f1a9c8b4d30012a4f001"]}'

Operations analytics

A single call that returns everything a dispatch board needs for the current day.

Name
GET /api/trips/operations-analytics
Description
Returns attention counters, today's activity, fleet-by-group breakdown, and the top priority alerts.

Request

curl "$LIVEPIN_API_BASE_URL/api/trips/operations-analytics" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Response (trimmed)

{
  "needsAttention": {
    "awaitingReview": 4,
    "escalated": 2,
    "priorityAlerts": 3,
    "camerasOffline": 1
  },
  "todayAtAGlance": {
    "liveNow": 18,
    "tripsToday": { "total": 26, "completed": 8 },
    "distanceTodayKm": 4213,
    "priorityAlerts": 3
  },
  "fleetByGroup": [
    { "group": "North Zone", "total": 12, "live": 9 }
  ],
  "priorityAlertsList": [
    {
      "vehicle_no": "DUMMY-VEHICLE-301",
      "notification_type": "Overspeed",
      "server_timestamp": 1776065116000
    }
  ]
}

priorityAlertsList is capped at 10 entries. Counters use the server's day boundary.

Trip media and reports

Name
GET /api/trips/:tripId/dashcam-media
Description
List dashcam media captured during a trip.
Name
POST /api/trips/:tripId/activate-stream
Description
Start the live stream for the trip's device and return the FLV URL.
Name
GET /api/trips/report/pdf
Description
Export a trip report. Query: tripIds, format.

Report parameters

Name
tripIds
Type
string
Description
Required. Comma-separated numeric trip IDs, for example 812,813.
Name
format
Type
string
Description
pdf (default), json, or xlsx.

Report fields

Name
tripId
Type
integer
Description
Numeric trip ID.
Name
vehicleNo
Type
string
Description
Vehicle registration number.
Name
transportCompany
Type
string
Description
Transport company name.
Name
driverName
Type
string
Description
Driver name.
Name
driverPhone
Type
string
Description
Driver phone number.
Name
cargoType
Type
string
Description
Cargo classification.
Name
pickupPoint
Type
string
Description
Pickup address.
Name
destination
Type
string
Description
Destination address.
Name
seals
Type
string
Description
Seal numbers.
Name
specialInstruction
Type
text
Description
Trip instructions.
Name
status
Type
string
Description
Trip status.
Name
startTime
Type
string
Description
Formatted start time.
Name
endTime
Type
string
Description
Formatted end time.
Name
distanceCovered
Type
string
Description
Formatted distance covered.
Name
images
Type
array
Description
Embedded evidence images as { title, base64 }.

format=pdf and format=xlsx return a file download. format=json returns the report inline, which is useful for testing.

Export trip report

GET

/api/trips/report/pdf

curl -G "$LIVEPIN_API_BASE_URL/api/trips/report/pdf" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d tripIds=812,813 \
  -d format=json \
  --output trip-report.pdf

Activate trip stream

POST

/api/trips/:tripId/activate-stream

curl -X POST "$LIVEPIN_API_BASE_URL/api/trips/TRIP-812/activate-stream" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Continue to Notifications API