Smart Trailer API Guide

The following is a description of the Smart Trailer APIs for Searchable Properties, Sensor Events, , Accident Reconstruction, and Predictive Physical Damage. The user must authenticate with their existing CTC credentials through the login interface prior to using these APIs.

  • Sensor searchable properties: Lists all the properties you can search through for sensor data.
  • Sensor search: Performs a search for sensor data based on those properties.
  • Create TPMS threshold: Sets a threshold value for TPMS (tire pressure monitoring system).
  • TPMS threshold searchable properties: Retrieves the searchable properties for previously established TPMS thresholds.
  • TPMS threshold search: Performs a search for device data (if the threshold values have already been added) based on the threshold properties.
  • TPMS threshold bulk update: Updates threshold data for multiple assets.
  • Trailer volumetric fill: Retrieves the volumetric fill for trailers (based on asset ID).
  • Assets by volumetric fill: Returns data on whether trailers' loads are above or below the threshold.

Prior to using these APIs, the user must authenticate with their existing CTC credentials through the login interface.

Note: All the APIs will follow the authentication and authorization against CTC as for other microservices.

If only one parameter is specified in the payload, the other parameters will assume their default values.

Sensor Searchable Properties

The sensor searchableproperties API provides a list of fields and properties you can use for searching sensor data. After authenticating the endpoint below, the user will have to enter their authentication token, as well as the x-app-key to request the API functionality.

GET: https://{hostname}/sensor/events/searchableproperties

Your API call history will appear in the Your Request History box.

This will return one of these status codes:

  • 200: Successful execution of the enablement of this API
  • 401: Unauthorized access

Each response code will be expandable to detail the results of the API call.

Search for Sensor Events

The sensor search API retrieves sensor data based on the searchable properties. To make the API call, the user must authenticate and provide the calamp-services-app string. This search API provides the option to search sensor data on fields that are listed by the searchable properties API.

This is the POST request to the API server:
POST https://{hostname}/sensor/events/search

Your API call history will appear in the Your Request History box.

In the Body Params box, you can enter your search criteria in the input fields:

maxResults: Input an integer value to limit the number of results
searchTerms: The input fields searchable for this API are the following:

  • mobileId: The numerical identifier
  • mobileIdType: The type or classification of identifier (such as ESN)
  • accountId: The numerical identifier
  • assetId: The numerical identifier
  • sensorType: The sensor you are sending the API to fetch data for (e.g. TPMS, WETS, CargoSense, DoorState, PSI_TPMS, BMS, LMU, WMS)
  • messageTime: The parameters of time in which you want the search to be performed

The expected response status codes are as follows:

  • 200: OK - successful search
  • 400: Bad request - invalid searchable property
  • 401: Unauthorized - invalid x-app-key/authorization token
  • 403: Forbidden - subscription error

Each response code will be expandable to detail the results of the API call.

Create TPMS Threshold

The thresholds API enables a user to request to update the threshold values for TPMS in order to monitor the temperature and pressure of the tires on a vehicle as well as adhere to safety standards. These thresholds are observed in CTC and allow a user to communicate the condition of the tires in field and monitor additional vehicle metrics.

Your API call history will appear in the Your Request History box.

You can update the following values via this API:

  • TPMS high temperature threshold
  • TPMS high pressure threshold
  • TPMS low pressure threshold

The following are required input fields to create a threshold:

  • mobileId: The numerical identifier
  • mobileIdType: The type or classification of identifier (such as ESN)
  • thresholds object: Such as the name (for example, High Temperature), value, and units
  • value: The numeric value of temperature
  • units: F or C

This is the POST request to the API server:
POST: https://{hostname}/sensor/thresholds

The expected response status codes are the following:

  • 200: OK - successful creation of the TPMS threshold
  • 400: Bad request - TPMS threshold created already
  • 401: Unauthorized - invalid x-app-key/authorization token
  • 404: Not found - no TPMS threshold data in CTC

Each response code will be expandable to detail the results of the API call.

TPMS Threshold Searchable Properties

The thresholds searchableproperties API functions similarly to the sensor searchableproperties API, in that it enables the user to authenticate, enter the x-app-key in order to send a request to the endpoint below, and make the API provide a list of which properties can be searched and filtered through and which can be used for searching sensor data.

The following is the GET call:

GET: https://{hostname}/sensor/thresholds/searchableproperties

Your API call history will appear in the Your Request History box.

This will return one of these status codes:

  • 200: Successful execution of the enablement of this API
  • 401: Unauthorized - invalid x-app-key/authorization token

Each response code will be expandable to detail the results of the API call.

Search for TPMS Threshold

If a TPMS threshold has already been set, the thresholds search API functions as a search request for a device based on the searchable properties of the TPMS data.

This is the POST request to the API server:
POST: https://{hostname}/sensor/thresholds/search

Your API call history will appear in the Your Request History box.

In the Body Params box, you can enter your search criteria in the input fields:

maxResults: Input an integer value to limit the number of results
searchTerms: The input fields searchable for this API are the following:

  • mobileId: The numerical identifier
  • mobileIdType: The type or classification of identifier (such as ESN)
  • assetId: The numerical identifier
  • messageUuid: The parameters of time in which you want the search to be performed

The expected response status codes are the following:

  • 200: OK - successful search of the TPMS threshold
  • 400: Bad request - invalid searchable property
  • 401: Unauthorized - invalid x-app-key/authorization token

Each response code will be expandable to detail the results of the API call.

TPMS Threshold Bulk Update

To update the TPMS threshold data for multiple in-field assets, such as for a fleet of vehicles that need to adhere to a company TPMS standard, you can use the thresholds bulkupdate API, which will perform a bulk-update function. To properly send the POST request, the body parameters need to be properly entered into the sensorThresholds input fields, in conjunction with the authentication token and x-app-key.

The POST request to the API server is the following:
POST: https://{hostname}/sensor/thresholds/bulkupdate

Your API call history will appear in the Your Request History box.

The following are required input fields to perform a bulk upload:

  • mobileId: The numerical identifier
  • mobileIdType: The type or classification of identifier (such as ESN)
  • name: Such as High Temperature
  • value: The numerical value of temperature
  • units: F or C
  • version: The numerical identifier
  • deviceId

The expected response status codes are as follows:

  • 200: OK - successful update of the TPMS threshold
  • 200: OK - object state out of date
  • 400: Bad request - invalid TPMS threshold values
  • 401: Unauthorized - invalid x-app-key/authorization token

Each response code will be expandable to detail the results of the API call.

Retrieve Volumetric Fill for Trailer

You can use the volumetricfill API to retrieve the volumetric fill of an in-field trailer, such as the load weight for a road or regional compliance value, and help avoid roadside delays or breakdowns. The user must send the request based on assetId, as designated in CTC.

This is the POST request to the API server:
POST https://{hostname}/sensor/events/volumetricfill

Your API call history will appear in the Your Request History box.

In the Body Params box, you can enter your criteria in the input fields:

assetId: The numerical identifier

The expected response status codes are the following:

  • 200: OK - successful retrieve with result
  • 200: OK - successful without result
  • 401: Unauthorized - invalid authorization token
  • 403: Forbidden - subscription error

Each response code will be expandable to detail the results of the API call.

Asset Above or Below Volumetric Fill

You can use the assetsbyvolumetricfill API to determine if an asset's load is above or below a set threshold. This data can help you monitor how close a trailer is to being deemed unsafe or too burdened with weight while on the road.

The GET call request to the API server is as follows:
GET: https://{hostname}/sensor/events/assetsbyvolumetricfill

In the Query Params box, you can enter your criteria in the input fields:

aboveVolumetricFill: The numerical value of fill volume above input
belowVolumetricFill: The numerical value of fill volume below input

Your API call history will appear in the Your Request History box.

These are the expected response status codes:

  • 200: OK - successful retrieve with result
  • 401: Unauthorized - invalid authorization token
  • 403: Forbidden - subscription error

Each response code will be expandable to detail the results of the API call.