Decisiv SRM Gateway - Telematics
Ingest and read connected-asset telematics inside SRM: diagnostic readings and fault codes for registered assets, so a fault on a vehicle can open or enrich a service case at the point of service.
OpenAPI Specification
openapi: 3.1.0
info:
version: 0.48.24
termsOfService: https://www.decisiv.com/terms-of-use
contact:
name: Decisiv Support
email: support@decisiv.com
url: https://www.decisiv.com
title: Telematics
description: Inside of **Decisiv SRM Gateway**, the `Telematics` module represents all interactions and functionality which
an Account enabled with `Telematics subscription` can perform through an API interface.
license:
name: Proprietary
identifier: proprietary
url: https://www.decisiv.com/terms-of-use/
servers:
- url: https://srm-api.staging.decisivapps.com
- url: https://srm-api.decisivapps.com
security:
- OAuth2AuthorizationCode: []
AccessToken: []
- OAuth2Password: []
AccessToken: []
paths:
/telematics/{srm_account_id}/v1/diagnostic_readings:
get:
operationId: listDiagnosticReadings
summary: List all diagnostic readings for the requested account
description: Retrieve all diagnostic readings for a specific SRM account.
tags:
- Diagnostic Readings
parameters:
- name: srm_account_id
in: path
description: The account ID for SRM
required: true
schema:
type: string
- name: filter[asset_data.chassis_id]
in: query
required: false
schema:
type: string
description: Filters diagnostic readings by exact match on `asset_data.chassis_id`
- name: filter[asset_data.device_id]
in: query
required: false
schema:
type: string
description: Filters diagnostic readings by exact match on `asset_data.device_id`
- name: filter[asset_data.serial_number]
in: query
required: false
schema:
type: string
description: Filters diagnostic readings by exact match on `asset_data.serial_number`
- name: filter[asset_data.vin]
in: query
required: false
schema:
type: string
description: Filters diagnostic readings by exact match on `asset_data.vin`
- name: filter[origin]
in: query
required: false
schema:
type: string
description: Filters diagnostic readings by exact match on `origin`
- name: filter[triggered_at:gt]
in: query
required: false
schema:
type: string
format: date-time
description: Returns diagnostic readings with `triggered_at` strictly greater than the provided `ISO8601` date-time
- name: filter[triggered_at:gte]
in: query
required: false
schema:
type: string
format: date-time
description: Returns diagnostic readings with `triggered_at` greater than or equal to the provided `ISO8601` date-time
- name: filter[triggered_at:lt]
in: query
required: false
schema:
type: string
format: date-time
description: Returns diagnostic readings with `triggered_at` strictly less than the provided `ISO8601` date-time
- name: filter[triggered_at:lte]
in: query
required: false
schema:
type: string
format: date-time
description: Returns diagnostic readings with `triggered_at` less than or equal to the provided `ISO8601` date-time
responses:
'200':
description: Returns list of Diagnostic Readings
content:
application/vnd.api+json:
example:
data:
- id: 3cad1e59-8eed-410f-9a15-527d11cba0d0
type: diagnostic_readings
attributes:
triggered_at: '2025-03-11T18:48:34Z'
sensor_readings:
- name: Intake NOx
description: Aftertreatment 1 Intake NOx, Range -200 to 3012.75
value: '115.8'
unit_of_measure: ppm
classification_header: Engine Operation
key_data: false
localize: false
components:
- name: ECU
description: 'The #1 on the Engine CA is to identify that this is the first PA being used for the particular
function, Engine. It may only be used for the NAME Function of 0'
version: '12'
origin_id: 90bd02a4-9ca6-4db6-8cba-c8a24f6ea717
origin: name_of_origin
location:
heading: '251'
altitude: '3649'
latitude: '-58.28'
longitude: '152.41'
asset_data:
vin: PHFCJ2YS9LB593266
make: Make
year: '2000'
model: CH613
device_id: '1234567890'
chassis_id: '12312312'
serial_number: LB593266
external_resources:
- href: https://telematics-source.oem-system.com/videos/28972.mp4
title: Interactive Video
description: Video to accelerate repair time and uptime.
classification_header: Repair Information
type: video
relationships:
faults:
data:
- type: faults
id: a6156681-443f-481f-9007-272b99240259
source_account:
data:
type: srm_accounts
id: dc8beef2-e304-11ea-86c2-1f9b5bc5281b
links:
self: https://srm-api.decisivapps.com/telematics/v1/diagnostic_readings/3cad1e59-8eed-410f-9a15-527d11cba0d0
schema:
$ref: '#/components/schemas/diagnostic_readings'
'400':
description: This response may occur when an invalid request has been provided to the server. The request may be
corrected by the consumer and resubmitted.
content:
application/vnd.api+json:
example:
errors:
- title: Filter not allowed
detail: '''{{filter_name}}'' is not allowed. Valid filters: {{filters_list}}'
code: decisiv:filters:001
status: '400'
source:
parameter: filter[filter_name]
schema:
$ref: '#/components/schemas/errors_response'
'401':
description: This response may occur when the access token provided within the Authorization token has expired.
content:
application/vnd.api+json:
example:
errors:
- title: Access unauthorized
detail: Access unauthorized
code: decisiv::access_token:001
status: '401'
schema:
$ref: '#/components/schemas/errors_response'
'403':
description: This response may occur when the authenticated user embedded within the Authorization header does not
have access to the requested resource.
content:
application/vnd.api+json:
example:
errors:
- title: Forbidden
detail: User does not have permission to perform this action on the requested resource(s)
code: decisiv:access:001
status: '403'
schema:
$ref: '#/components/schemas/errors_response'
'404':
description: This response may occur when the requested resource is not found.
content:
application/vnd.api+json:
example:
errors:
- title: Record not found
detail: The requested record or one of its relationships could not be found
code: '404'
status: '404'
schema:
$ref: '#/components/schemas/errors_response'
'424':
description: This response may occur when there is an unresolved data dependency or configuration required inside
of the Decisiv Platform preventing access to the requested action.
content:
application/vnd.api+json:
example:
errors:
- title: Failed Dependency
detail: Failed Dependency
code: '424'
status: '424'
schema:
$ref: '#/components/schemas/errors_response'
'504':
description: This response may occur when there is an unexpected system timeout.
content:
application/vnd.api+json:
example:
errors:
- code: '504'
detail: Gateway timeout error
status: '504'
title: Gateway timeout error
schema:
$ref: '#/components/schemas/errors_response'
post:
operationId: createDiagnosticReading
summary: Create a new diagnostic reading
description: Create a new diagnostic reading record for a specific SRM account.
tags:
- Diagnostic Readings
parameters:
- name: srm_account_id
in: path
description: The account ID for SRM
required: true
schema:
type: string
responses:
'201':
description: Creates a new Diagnostic Reading record
content:
application/vnd.api+json:
example:
data:
id: 3cad1e59-8eed-410f-9a15-527d11cba0d0
type: diagnostic_readings
attributes:
triggered_at: '2025-03-11T18:48:34Z'
sensor_readings:
- name: Intake NOx
description: Aftertreatment 1 Intake NOx, Range -200 to 3012.75
value: '115.8'
unit_of_measure: ppm
classification_header: Engine Operation
key_data: false
localize: false
components:
- name: ECU
description: 'The #1 on the Engine CA is to identify that this is the first PA being used for the particular
function, Engine. It may only be used for the NAME Function of 0'
version: '12'
origin_id: 90bd02a4-9ca6-4db6-8cba-c8a24f6ea717
origin: name_of_origin
location:
heading: '251'
altitude: '3649'
latitude: '-58.28'
longitude: '152.41'
asset_data:
vin: PHFCJ2YS9LB593266
make: Make
year: '2000'
model: CH613
device_id: '1234567890'
chassis_id: '12312312'
serial_number: LB593266
external_resources:
- href: https://telematics-source.oem-system.com/videos/28972.mp4
title: Interactive Video
description: Video to accelerate repair time and uptime.
classification_header: Repair Information
type: video
relationships:
faults:
data:
- type: faults
id: a6156681-443f-481f-9007-272b99240259
source_account:
data:
type: srm_accounts
id: dc8beef2-e304-11ea-86c2-1f9b5bc5281b
links:
self: https://srm-api.decisivapps.com/telematics/v1/diagnostic_readings/3cad1e59-8eed-410f-9a15-527d11cba0d0
schema:
$ref: '#/components/schemas/diagnostic_reading'
'400':
description: Invalid Filter / Incorrect attribute for the resource type / Missing required key / Missing required
value / Invalid Attribute Value on External Resources Type
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/errors_response'
examples:
Invalid Filter:
value:
errors:
- title: Filter not allowed
detail: '''{{filter_name}}'' is not allowed. Valid filters: {{filters_list}}'
code: decisiv:filters:001
status: '400'
source:
parameter: filter[filter_name]
Incorrect attribute for the resource type:
value:
errors:
- status: '400'
code: decisiv:resource:002
title: Invalid JSON:API Resource specified in request
detail: '''{{invalid_resource}}'' is an invalid resource'
source:
pointer: /data/type
Missing required key:
value:
errors:
- status: '400'
code: decisiv:request_attributes:001
title: Missing required attribute key
detail: Required key not provided in request body
source:
pointer: /data/attributes/content
Missing required value:
value:
errors:
- status: '400'
code: decisiv:request_attributes:002
title: Missing required attribute value
detail: Required key must be populated
source:
pointer: /data/attributes/content
Invalid Attribute Value on External Resources Type:
value:
errors:
- status: '400'
title: Invalid Attribute Value
detail: Invalid {{attribute_name}} value provided - {{reason}}
code: decisiv:request_attributes:010
source:
pointer: /data/attributes/external_resources/0/type
'401':
description: This response may occur when the access token provided within the Authorization token has expired.
content:
application/vnd.api+json:
example:
errors:
- title: Access unauthorized
detail: Access unauthorized
code: decisiv::access_token:001
status: '401'
schema:
$ref: '#/components/schemas/errors_response'
'403':
description: This response may occur when the authenticated user embedded within the Authorization header does not
have access to the requested resource.
content:
application/vnd.api+json:
example:
errors:
- title: Forbidden
detail: User does not have permission to perform this action on the requested resource(s)
code: decisiv:access:001
status: '403'
schema:
$ref: '#/components/schemas/errors_response'
'429':
description: This response will often be associated as a result of an over abundance of calls by a specific Application,
Account, or IP Address resulting in a required cool off period.
content:
application/vnd.api+json:
example:
errors:
- code: '429'
detail: The maximum number of requests for this application has been far exceeded with the given credentials.
status: '429'
title: Too Many Requests
schema:
$ref: '#/components/schemas/errors_response'
requestBody:
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/create_diagnostic_reading'
examples:
Create diagnostic reading:
value:
data:
type: diagnostic_readings
attributes:
triggered_at: '2025-03-11T18:48:34Z'
sensor_readings:
- name: Intake NOx
description: Aftertreatment 1 Intake NOx, Range -200 to 3012.75
value: '115.8'
unit_of_measure: ppm
classification_header: Engine Operation
key_data: false
localize: false
components:
- name: ECU
description: 'The #1 on the Engine CA is to identify that this is the first PA being used for the
particular function, Engine. It may only be used for the NAME Function of 0'
version: '12'
origin_id: 90bd02a4-9ca6-4db6-8cba-c8a24f6ea717
origin: name_of_origin
location:
heading: '251'
altitude: '3649'
latitude: '-58.28'
longitude: '152.41'
asset_data:
vin: PHFCJ2YS9LB593266
make: Make
year: '2000'
model: CH613
device_id: '1234567890'
chassis_id: '12312312'
serial_number: LB593266
external_resources:
- href: https://telematics-source.oem-system.com/videos/28972.mp4
title: Interactive Video
description: Video to accelerate repair time and uptime.
classification_header: Repair Information
type: video
/telematics/{srm_account_id}/v1/diagnostic_readings/{uuid}:
get:
operationId: getDiagnosticReading
summary: Get details for a specific diagnostic reading
description: Retrieve details for a specific diagnostic reading by UUID.
tags:
- Diagnostic Readings
parameters:
- name: srm_account_id
in: path
description: The account ID for SRM
required: true
schema:
type: string
- name: uuid
in: path
schema:
type: string
format: uuid
description: The diagnostic reading UUID
required: true
responses:
'200':
description: Returns details for the requested diagnostic reading
content:
application/vnd.api+json:
example:
data:
id: 3cad1e59-8eed-410f-9a15-527d11cba0d0
type: diagnostic_readings
attributes:
triggered_at: '2025-03-11T18:48:34Z'
sensor_readings:
- name: Intake NOx
description: Aftertreatment 1 Intake NOx, Range -200 to 3012.75
value: '115.8'
unit_of_measure: ppm
classification_header: Engine Operation
key_data: false
localize: false
components:
- name: ECU
description: 'The #1 on the Engine CA is to identify that this is the first PA being used for the particular
function, Engine. It may only be used for the NAME Function of 0'
version: '12'
origin_id: 90bd02a4-9ca6-4db6-8cba-c8a24f6ea717
origin: name_of_origin
location:
heading: '251'
altitude: '3649'
latitude: '-58.28'
longitude: '152.41'
asset_data:
vin: PHFCJ2YS9LB593266
make: Make
year: '2000'
model: CH613
device_id: '1234567890'
chassis_id: '12312312'
serial_number: LB593266
external_resources:
- href: https://telematics-source.oem-system.com/videos/28972.mp4
title: Interactive Video
description: Video to accelerate repair time and uptime.
classification_header: Repair Information
type: video
relationships:
faults:
data:
- type: faults
id: a6156681-443f-481f-9007-272b99240259
source_account:
data:
type: srm_accounts
id: dc8beef2-e304-11ea-86c2-1f9b5bc5281b
links:
self: https://srm-api.decisivapps.com/telematics/v1/diagnostic_readings/3cad1e59-8eed-410f-9a15-527d11cba0d0
schema:
$ref: '#/components/schemas/diagnostic_reading'
'400':
description: This response may occur when an invalid request has been provided to the server. The request may be
corrected by the consumer and resubmitted.
content:
application/vnd.api+json:
example:
errors:
- title: Filter not allowed
detail: '''{{filter_name}}'' is not allowed. Valid filters: {{filters_list}}'
code: decisiv:filters:001
status: '400'
source:
parameter: filter[filter_name]
schema:
$ref: '#/components/schemas/errors_response'
'401':
description: This response may occur when the access token provided within the Authorization token has expired.
content:
application/vnd.api+json:
example:
errors:
- title: Access unauthorized
detail: Access unauthorized
code: decisiv::access_token:001
status: '401'
schema:
$ref: '#/components/schemas/errors_response'
'403':
description: This response may occur when the authenticated user embedded within the Authorization header does not
have access to the requested resource.
content:
application/vnd.api+json:
example:
errors:
- title: Forbidden
detail: User does not have permission to perform this action on the requested resource(s)
code: decisiv:access:001
status: '403'
schema:
$ref: '#/components/schemas/errors_response'
'404':
description: This response may occur when the requested resource is not found.
content:
application/vnd.api+json:
example:
errors:
- title: Record not found
detail: The requested record or one of its relationships could not be found
code: '404'
status: '404'
schema:
$ref: '#/components/schemas/errors_response'
'424':
description: This response may occur when there is an unresolved data dependency or configuration required inside
of the Decisiv Platform preventing access to the requested action.
content:
application/vnd.api+json:
example:
errors:
- title: Failed Dependency
detail: Failed Dependency
code: '424'
status: '424'
schema:
$ref: '#/components/schemas/errors_response'
'504':
description: This response may occur when there is an unexpected system timeout.
content:
application/vnd.api+json:
example:
errors:
- code: '504'
detail: Gateway timeout error
status: '504'
title: Gateway timeout error
schema:
$ref: '#/components/schemas/errors_response'
/telematics/{srm_account_id}/v1/faults:
get:
operationId: listFaults
summary: List all faults for the requested account
description: Retrieve all faults for a specific SRM account.
tags:
- Faults
parameters:
- name: srm_account_id
in: path
description: The account ID for SRM
required: true
schema:
type: string
responses:
'200':
description: Returns list of Faults
content:
application/vnd.api+json:
example:
data:
- id: 44e10524-07a3-4008-8bcd-08950f3b00e8
type: faults
attributes:
triggered_at: '2025-03-11T18:48:34Z'
spn: '3456'
fmi: '19'
fault_code: '1223'
sensor_readings:
- name: AFTRT 1 Intake NOx
description: Aftertreatment 1 Intake NOx, Range -200 to 3012.75
value: '115.8'
unit_of_measure: ppm
classification_header: Engine Operation
key_data: false
localize: false
guidance:
- name: AFTRT 2 NOx
description: Take to the closest dealer immediately!
value: '15.8'
classification_header: Engine Operation
location:
heading: '251'
altitude: '3649'
latitude: '-58.28'
longitude: '152.41'
details:
component:
name: ECU
description: Component description
version: Engine
occurrences: 3
odometer_unit: mi
odometer_value: 23993123
severity_level: Severe
description: Fault description
active: false
severity: 2
external_resources:
- href: https://telematics-source.oem-system.com/videos/28972.mp4
title: Interactive Video
description: Video to accelerate repair time and uptime.
classification_header: Repair Information
type: video
relationships:
diagnostic_reading:
data:
type: diagnostic_readings
id: 3cad1e59-8eed-410f-9a15-527d11cba0d0
source_account:
data:
type: srm_accounts
id: dc8beef2-e304-11ea-86c2-1f9b5bc5281b
asset:
data:
type: assets
id: 73b781e9-d724-4c8c-89fe-b289abade626
links:
self: https://srm-api.decisivapps.com/telematics/v1/faults/44e10524-07a3-4008-8bcd-08950f3b00e8
schema:
$ref: '#/components/schemas/faults'
'400':
description: This response may occur when an invalid request has been provided to the server. The request may be
corrected by the consumer and resubmitted.
content:
application/vnd.api+json:
example:
errors:
- title: Filter not allowed
detail: '''{{filter_name}}'' is not allowed. Valid filters: {{filters_list}}'
code: decisiv:filters:001
status: '400'
source:
parameter: filter[filter_name]
schema:
$ref: '#/components/schemas/errors_response'
'401':
description: This response may occur when the access token provided within the Authorization token has expired.
content:
application/vnd.api+json:
example:
errors:
- title: Access unauthorized
detail: Access unauthorized
code: decisiv::access_token:001
status: '401'
schema:
$ref: '#/components/schemas/errors_response'
'403':
description: This response may occur when the authenticated user embedded within the Authorization header does not
have access to the requested resource.
content:
application/vnd.api+json:
example:
errors:
- title: Forbidden
detail: User does not have permission to perform this action on the requested resource(s)
code: decisiv:access:001
status: '403'
schema:
$ref: '#/components/schemas/errors_response'
'404':
description: This response may occur when the requested resource is not found.
content:
application/vnd.api+json:
example:
errors:
- title: Record not found
detail: The requested record or one of its relationships could not be found
code: '404'
status: '404'
schema:
$ref: '#/components/schemas/errors_response'
'424':
description: This response may occur when there is an unresolved data dependency or configuration required inside
of the Decisiv Platform preventing access to the requested action.
content:
application/vnd.api+json:
example:
errors:
- title: Failed Dependency
detail: Failed Dependency
code: '424'
status: '424'
schema:
$ref: '#/components/schemas/errors_response'
'504':
description: This response may occur when there is an unexpected system timeout.
content:
application/vnd.api+json:
example:
errors:
- code: '504'
detail: Gateway timeout error
status: '504'
title: Gateway timeout error
schema:
$ref: '#/components/schemas/errors_response'
post:
operationId: createFault
summary: Create a new fault
description: Create a new fault record for a specific SRM account.
tags:
- Faults
parameters:
- name: srm_account_id
in: path
description: The account ID for SRM
required: true
schema:
type: string
responses:
'201':
description: Creates a new Fault record
content:
application/vnd.api+json:
example:
data:
id: 44e10524-07a3-4008-8bcd-08950f3b00e8
type: faults
attributes:
triggered_at: '2025-03-11T18:48:34Z'
spn: '3456'
fmi: '19'
fault_code: '1223'
sensor_readings:
- name: AFTRT 1 Intake NOx
description: Aftertreatment 1 Intake NOx, Range -200 to 3012.75
value: '115.8'
# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/decisiv/refs/heads/main/openapi/decisiv-telematics-openapi.yml