Tracking Device API (2.0)

The Tracking Device API is a unified interface to post or request information about tracking devices. Usually a tracking device is a vehicle, which needs to be registered to our platform before you can feed GPS data to other endpoints.

Make sure you request the Auth API first

Register or update a tracking device

Registers a new or updates an existing tracking device depending if the device is already known. A device is defined by a unique combination of the externalSystemId and the externalDeviceId. So registering an already existing device will update all the attributes except the DeviceUUID

SecurityBearerAuth
Request
Request Body schema: application/json

Tracking Device that needs to be added to the service

externalDeviceId
required
string

The identifier you use to recognize the device/vehicle in your source system

externalSystemId
required
string

Identifier for the source system we use to uniquely recognize the shipper/carrier

active
required
boolean
Default: true

Indicates whether the current tracking device is active or not

carrierCode
required
string

This code is used by the Simacan Control Tower to match a Tracking Device with a carrier

customerDeviceId
required
string
licensePlate
string

License Plate linked with the current tracking device

driverName
string

Driver name linked with the current tracking device

attributes
object

Any freeform additional attributes

Responses
200

Indicates that your request was successful. You will see an entity describing or containing the result of your action

400

Bad Request: You will receive this status, when the data you’ve delivered is not in the correct format. You will see an entity describing what went wrong.

401

Unauthorized: Whenever you will get this status, you have either provided the wrong credentials or none at all. Check if you bearer token has not expired.

403

Forbidden: You will receive this status, when you successfully supplied credentials, but your username does not have the necessary permissions for the resource.

404

Not Found: Whenever you will get a 404, you are probably using a malformed or incorrect URL.

post/
Request samples
application/json
{
  • "externalDeviceId": "string",
  • "externalSystemId": "string",
  • "active": true,
  • "carrierCode": "string",
  • "customerDeviceId": "string",
  • "licensePlate": "string",
  • "driverName": "string",
  • "attributes": { }
}
Response samples
application/json
{
  • "deviceUUID": "b9ed42ff-3ffb-4418-9498-5eb0ba308899",
  • "externalSystemId": "fms-janszoon_transport",
  • "externalDeviceId": "1234",
  • "customerDeviceId": "string",
  • "active": "true",
  • "relation": "janszoon_transport",
  • "carrierCode": "string",
  • "creationDate": "2020-06-07T09:17:43Z",
  • "lastUpdatedDate": "string",
  • "licensePlate": "AB-12-CD",
  • "driverName": "string",
  • "attributes": {
    }
}

Register or update a tracking device

Registers a new or updates an existing tracking device depending if the device is already known. A device is defined by a unique combination of the externalSystemId and the externalDeviceId. So registering an already existing device will update all the attributes except the DeviceUUID

SecurityBearerAuth
Request
Request Body schema: application/json

Tracking Device that needs to be added to the service

externalDeviceId
required
string

The identifier you use to recognize the device/vehicle in your source system

externalSystemId
required
string

Identifier for the source system we use to uniquely recognize the shipper/carrier

active
required
boolean
Default: true

Indicates whether the current tracking device is active or not

carrierCode
required
string

This code is used by the Simacan Control Tower to match a Tracking Device with a carrier

customerDeviceId
required
string
licensePlate
string

License Plate linked with the current tracking device

driverName
string

Driver name linked with the current tracking device

attributes
object

Any freeform additional attributes

Responses
200

Indicates that your request was successful. You will see an entity describing or containing the result of your action

400

Bad Request: You will receive this status, when the data you’ve delivered is not in the correct format. You will see an entity describing what went wrong.

401

Unauthorized: Whenever you will get this status, you have either provided the wrong credentials or none at all. Check if you bearer token has not expired.

403

Forbidden: You will receive this status, when you successfully supplied credentials, but your username does not have the necessary permissions for the resource.

404

Not Found: Whenever you will get a 404, you are probably using a malformed or incorrect URL.

put/
Request samples
application/json
{
  • "externalDeviceId": "string",
  • "externalSystemId": "string",
  • "active": true,
  • "carrierCode": "string",
  • "customerDeviceId": "string",
  • "licensePlate": "string",
  • "driverName": "string",
  • "attributes": { }
}
Response samples
application/json
{
  • "deviceUUID": "b9ed42ff-3ffb-4418-9498-5eb0ba308899",
  • "externalSystemId": "fms-janszoon_transport",
  • "externalDeviceId": "1234",
  • "customerDeviceId": "string",
  • "active": "true",
  • "relation": "janszoon_transport",
  • "carrierCode": "string",
  • "creationDate": "2020-06-07T09:17:43Z",
  • "lastUpdatedDate": "string",
  • "licensePlate": "AB-12-CD",
  • "driverName": "string",
  • "attributes": {
    }
}

Retrieve all devices

Retrieves all devices of the associated carriers of the authenticated account.

SecurityBearerAuth
Responses
200

Indicates that your request was successful. You will see an entity describing or containing the result of your action

400

Bad Request: You will receive this status, when the data you’ve delivered is not in the correct format. You will see an entity describing what went wrong.

401

Unauthorized: Whenever you will get this status, you have either provided the wrong credentials or none at all. Check if you bearer token has not expired.

403

Forbidden: You will receive this status, when you successfully supplied credentials, but your username does not have the necessary permissions for the resource.

404

Not Found: Whenever you will get a 404, you are probably using a malformed or incorrect URL.

get/
Request samples
import requests

url = "https://tracking-device-api.services.simacan.com/api/public/v2/"

headers = {"Authorization": "Bearer <YOUR_JWT_HERE>"}

response = requests.get(url, headers=headers)

data = response.json()
print(data)
Response samples
application/json
{
  • "deviceUUID": "b9ed42ff-3ffb-4418-9498-5eb0ba308899",
  • "externalSystemId": "fms-janszoon_transport",
  • "externalDeviceId": "1234",
  • "customerDeviceId": "string",
  • "active": "true",
  • "relation": "janszoon_transport",
  • "carrierCode": "string",
  • "creationDate": "2020-06-07T09:17:43Z",
  • "lastUpdatedDate": "string",
  • "licensePlate": "AB-12-CD",
  • "driverName": "string",
  • "attributes": {
    }
}

Retrieve a device by externalDeviceId

Retrieves a single device of the associated carrier of the authenticated account, based on the externalDeviceId

SecurityBearerAuth
Request
path Parameters
externalSystemId
required
string

Identifier for the source system we use to uniquely recognize the shipper/carrier

externalDeviceId
required
string

The identifier you use to recognize the device/vehicle in your source system

Responses
200

Indicates that your request was successful. You will see an entity describing or containing the result of your action

400

Bad Request: You will receive this status, when the data you’ve delivered is not in the correct format. You will see an entity describing what went wrong.

401

Unauthorized: Whenever you will get this status, you have either provided the wrong credentials or none at all. Check if you bearer token has not expired.

403

Forbidden: You will receive this status, when you successfully supplied credentials, but your username does not have the necessary permissions for the resource.

404

Not Found: Whenever you will get a 404, you are probably using a malformed or incorrect URL.

get/external-system/{externalSystemId}/external-device/{externalDeviceId}
Request samples
import requests

external_system_id = "YOUR_externalSystemId_PARAMETER"
external_device_id = "YOUR_externalDeviceId_PARAMETER"
url = "https://tracking-device-api.services.simacan.com/api/public/v2/external-system/" + external_system_id + "/external-device/" + external_device_id

headers = {"Authorization": "Bearer <YOUR_JWT_HERE>"}

response = requests.get(url, headers=headers)

data = response.json()
print(data)
Response samples
application/json
{
  • "deviceUUID": "b9ed42ff-3ffb-4418-9498-5eb0ba308899",
  • "externalSystemId": "fms-janszoon_transport",
  • "externalDeviceId": "1234",
  • "customerDeviceId": "string",
  • "active": "true",
  • "relation": "janszoon_transport",
  • "carrierCode": "string",
  • "creationDate": "2020-06-07T09:17:43Z",
  • "lastUpdatedDate": "string",
  • "licensePlate": "AB-12-CD",
  • "driverName": "string",
  • "attributes": {
    }
}

Retrieve device by license plate

Retrieves a single device of the associated carrier of the authenticated account, based on the linked license plate

SecurityBearerAuth
Request
path Parameters
externalSystemId
required
string

Identifier for the source system we use to uniquely recognize the shipper/carrier

licensePlate
required
string

License Plate linked for the current tracking device

Responses
200

Indicates that your request was successful. You will see an entity describing or containing the result of your action

400

Bad Request: You will receive this status, when the data you’ve delivered is not in the correct format. You will see an entity describing what went wrong.

401

Unauthorized: Whenever you will get this status, you have either provided the wrong credentials or none at all. Check if you bearer token has not expired.

403

Forbidden: You will receive this status, when you successfully supplied credentials, but your username does not have the necessary permissions for the resource.

404

Not Found: Whenever you will get a 404, you are probably using a malformed or incorrect URL.

get/external-system/{externalSystemId}/license-plate/{licensePlate}
Request samples
import requests

external_system_id = "YOUR_externalSystemId_PARAMETER"
license_plate = "YOUR_licensePlate_PARAMETER"
url = "https://tracking-device-api.services.simacan.com/api/public/v2/external-system/" + external_system_id + "/license-plate/" + license_plate

headers = {"Authorization": "Bearer <YOUR_JWT_HERE>"}

response = requests.get(url, headers=headers)

data = response.json()
print(data)
Response samples
application/json
{
  • "deviceUUID": "b9ed42ff-3ffb-4418-9498-5eb0ba308899",
  • "externalSystemId": "fms-janszoon_transport",
  • "externalDeviceId": "1234",
  • "customerDeviceId": "string",
  • "active": "true",
  • "relation": "janszoon_transport",
  • "carrierCode": "string",
  • "creationDate": "2020-06-07T09:17:43Z",
  • "lastUpdatedDate": "string",
  • "licensePlate": "AB-12-CD",
  • "driverName": "string",
  • "attributes": {
    }
}