Skip to main content
POST
/
api
/
GetSafetyScore
Get Safety Scores
curl --request POST \
  --url https://api.telemax.com.au/api/GetSafetyScore \
  --header 'Authorization: Bearer <token>'
[
  {
    "startTime": "2024-01-15T08:00:00Z",
    "endTime": "2024-01-15T08:45:00Z",
    "riskLevel": "Medium",
    "riskScore": 62,
    "duration": 2700,
    "distance": 35.75
  },
  {
    "startTime": "2024-01-16T14:10:00Z",
    "endTime": "2024-01-16T14:50:00Z",
    "riskLevel": "Low",
    "riskScore": 20,
    "duration": 2400,
    "distance": 28.9
  }
]

​
Overview

Returns trip safety score payload from ISafetyScoreService for a legacy vehicle id over a date range.
A V2 version of this endpoint is available: Safety score. New integrations should prefer V2.

​
Endpoint

POST /api/GetSafetyScore

​
Query parameters

​
vehicleId
integer
required
Legacy vehicle id.
​
intervalType
integer
Used only when start and finish are omitted: 1 = instant range (see note), 2 = relative to end of local day, 3 = three-day window, 4 = week window—implementation uses finish - TimeSpan.FromDays(-N) which adds days to finish.
​
start
string (datetime)
Range start (optional if using intervalType).
​
finish
string (datetime)
Range end (optional if using intervalType).
⚠️ Note: When start and finish are omitted, finish is derived from “today” in the user’s timezone and intervalType selects start per the switch in GetSafetyScoreAsync. The arithmetic uses -TimeSpan.FromDays(-k) (double negative), which adds days to finish for types 2–4. For intervalType 1, start is set to DateTime.UtcNow. Validate ranges in staging before relying on preset windows.

​
Response

200 OK — array of trip safety score objects.
FieldTypeDescription
startTimestring (datetime)Trip start time
endTimestring (datetime)Trip end time
riskLevelstring"Low", "Medium", or "High"
riskScoreinteger (0–100)Numeric risk score; lower is safer
durationintegerTrip duration in seconds
distancenumberTrip distance in km

​
Error responses

StatusMeaning
404Unknown legacy vehicle
401Vehicle or user/company not allowed
400"Invalid date range specified." or generic “An error occurred while attempting to fetch the safety scores…”

Authorizations

​
Authorization
string
header
required

JWT Bearer token obtained from POST /api/authentication/token/user or POST /api/authentication/token/api-key.

Lifetime: ~24 hours (86,399 seconds). Cache the token and reuse it. Re-authenticate 5 minutes before expiry.

Scoping:

  • User tokens are scoped to a single company.
  • API key tokens may restrict access to a vehicle allowlist and/or action set (see token claims).

No refresh endpoint — re-authenticate with your credentials when the token expires.

Headers

​
Authorization
string
required

Bearer your_token

Query Parameters

​
vehicleId
integer
required

Legacy vehicle ID.

​
intervalType
integer

Preset window (used only when start/finish are omitted). 1 = instant range, 2 = relative to end of local day, 3 = three-day window, 4 = week window. Note: the implementation uses a double-negative offset (finish - TimeSpan.FromDays(-N)) which adds days to finish for types 2–4. Validate in staging before relying on preset windows.

​
start
string

Range start (ISO 8601 UTC). Optional when using intervalType.

​
finish
string

Range end (ISO 8601 UTC). Optional when using intervalType.

Response

Successful response with array of trip safety score data

​
startTime
string<date-time>

Trip start time (also used as trip ID component)

Example:

"2024-01-15T08:00:00Z"

​
endTime
string<date-time>

Trip end time

Example:

"2024-01-15T08:45:00Z"

​
riskLevel
string

Human-readable risk level

Example:

"Medium"

​
riskScore
integer<int32>

Risk score (0–100)

Required range: 0 <= x <= 100
Example:

62

​
duration
integer

Trip duration in seconds

Example:

2700

​
distance
number<float>

Total distance in kilometers

Example:

35.75