# Tracking Device API

## Context

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. A tracking device can be used to track a truck, but can be a trailer or any other moving object. For this
guide we only track GPS data, but a device could be able to track other data as well, like heading, temperature,
engine running or doors open/closed.

## Example

### Register (or update) a tracking device

As mentioned before, we are first going to register a tracking device on the Simacan Platform. We can do this by
sending a small payload to the baseURI in either a PUT or POST request method.

A small word of caution: if your `externalDeviceId` is already known on our platform, we will update its record

#### Payload

Below is an example payload you could send:


```json
{
  "externalDeviceId": "1234",
  "externalSystemId": "fms-janszoon_transport",
  "active": true,
  "carrierCode": "",
  "customerDeviceId": "",
  "licensePlate": "AB-12-CD",
  "driverName": "Harry de Vries"
}
```

In this example the `externalDeviceId` indicates the unique Id as used on your own platform; active can be set to
true or false to indicate if the device is in use. And `carrierCode` is the unique identifier for your carrier account,
which you should obtain from Simacan.

#### Send it

The next example will only work, if you obtained a bearer token from our [Auth API](/docs/fms/auth-api).
Include this in the header. Here we post to the staging URL


```shell
curl -d "{
        \"externalDeviceId\": \"1234\", 
        \"externalSystemId\": \"fms-janszoon_transport\", 
        \"active\": true, 
        \"carrierCode\": \"\", 
        \"customerDeviceId\": \"\", 
        \"licensePlate\": \"AB-12-CD\", 
        \"driverName\": \"Harry de Vries\" }" 
    -H "Content-Type: application/json"
    -H "Authorization: Bearer eyXXX"
    -X POST -i  https://tracking-device-api-stg.services.simacan.com/api/public/v2/
```

Now let’s check if we successfully registered our first device

#### Response

If everything went fine, you should receive an HTTP status code 200 OK and a body which looks like this


```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": {
    "carBrand": "Mercedes"
  }
}
```

*Great! You’ve just successfully registered your first device on our platform.*

## API Marketplace

For a more detailed reference on the Tracking Device API, visit our [API Marketplace](/marketplace)