Update Current Connection

curl --request PATCH \
  --url https://api.withterminal.com/tsp/v1/connections/current \
  --header 'Authorization: Bearer <token>' \
  --header 'Connection-Token: <connection-token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "connected",
  "options": {
    "ingestHistoryFromSourceSystem": true
  },
  "company": {
    "name": "Acme Inc.",
    "dotNumbers": [
      "<string>"
    ]
  },
  "externalId": "<string>",
  "syncMode": "automatic",
  "tags": [
    "<string>"
  ],
  "filters": {
    "vehicles": {
      "status": "active",
      "excludeIds": [
        "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ],
      "includeIds": [
        "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ]
    },
    "drivers": {
      "status": "active",
      "excludeIds": [
        "drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ],
      "includeIds": [
        "drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ]
    }
  }
}
'

{
  "id": "conn_01GV12VR4DJP70GD1ZBK0SDWFH",
  "company": {
    "name": "Frank's Trucking",
    "dotNumbers": [
      "1234567"
    ]
  },
  "account": {
    "name": "Frank's Trucking",
    "dotNumbers": [
      "1234567"
    ],
    "user": {
      "sourceId": "1234567",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]"
    }
  },
  "status": "connected",
  "provider": {
    "code": "geotab",
    "name": "Geotab"
  },
  "syncMode": "automatic",
  "token": "con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4",
  "options": {
    "ingestHistoryFromSourceSystem": true
  },
  "linkUrl": "https://link.withterminal.com/connection/{CONNECTION_ID}?key={PUBLISHABLE_KEY}",
  "createdAt": "2021-01-06T03:24:53.000Z",
  "updatedAt": "2021-01-06T03:24:53.000Z",
  "externalId": "1234",
  "sourceId": "123456789",
  "tags": [
    "Tag Name"
  ],
  "filters": {
    "vehicles": {
      "status": "active",
      "excludeIds": [
        "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ],
      "includeIds": [
        "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ]
    },
    "drivers": {
      "status": "active",
      "excludeIds": [
        "drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ],
      "includeIds": [
        "drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ]
    }
  }
}

PATCH

connections

current

Update Current Connection

curl --request PATCH \
  --url https://api.withterminal.com/tsp/v1/connections/current \
  --header 'Authorization: Bearer <token>' \
  --header 'Connection-Token: <connection-token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "connected",
  "options": {
    "ingestHistoryFromSourceSystem": true
  },
  "company": {
    "name": "Acme Inc.",
    "dotNumbers": [
      "<string>"
    ]
  },
  "externalId": "<string>",
  "syncMode": "automatic",
  "tags": [
    "<string>"
  ],
  "filters": {
    "vehicles": {
      "status": "active",
      "excludeIds": [
        "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ],
      "includeIds": [
        "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ]
    },
    "drivers": {
      "status": "active",
      "excludeIds": [
        "drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ],
      "includeIds": [
        "drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ]
    }
  }
}
'

{
  "id": "conn_01GV12VR4DJP70GD1ZBK0SDWFH",
  "company": {
    "name": "Frank's Trucking",
    "dotNumbers": [
      "1234567"
    ]
  },
  "account": {
    "name": "Frank's Trucking",
    "dotNumbers": [
      "1234567"
    ],
    "user": {
      "sourceId": "1234567",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]"
    }
  },
  "status": "connected",
  "provider": {
    "code": "geotab",
    "name": "Geotab"
  },
  "syncMode": "automatic",
  "token": "con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4",
  "options": {
    "ingestHistoryFromSourceSystem": true
  },
  "linkUrl": "https://link.withterminal.com/connection/{CONNECTION_ID}?key={PUBLISHABLE_KEY}",
  "createdAt": "2021-01-06T03:24:53.000Z",
  "updatedAt": "2021-01-06T03:24:53.000Z",
  "externalId": "1234",
  "sourceId": "123456789",
  "tags": [
    "Tag Name"
  ],
  "filters": {
    "vehicles": {
      "status": "active",
      "excludeIds": [
        "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ],
      "includeIds": [
        "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ]
    },
    "drivers": {
      "status": "active",
      "excludeIds": [
        "drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ],
      "includeIds": [
        "drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ]
    }
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Connection-Token

string

required

The token returned when a user authenticated their account. This authorizes access to a specific account.

Example:

"con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4"

Body

application/json

status

enum<string>

Available options:

connected,

archived,

disconnected

options

Omnitracs Options · object

Omnitracs Options
Omnitracs ES Options
Omnitracs XRS Options

Show child attributes

options.ingestHistoryFromSourceSystem

boolean

default:true

By default our system will ingest Vehicle Locations and Stat Logs from the source system. Omnitracs also supports history at a higher sample rate through a historical file process. If you are using these historical files and want to avoid mixing the data sources, set this to false.

company

object

Show child attributes

company.name

string

The name of the company.

Example:

"Acme Inc."

company.dotNumbers

string[]

DOT numbers associated with the company.

externalId

string

syncMode

enum<string>

default:automatic

Enum values:

automatic: Terminal will keep this connections data up to date
manual: Terminal will only sync data upon request

Available options:

automatic,

manual

Response

string<ulid>

required

Example:

"conn_01GV12VR4DJP70GD1ZBK0SDWFH"

company

object

required

Show child attributes

company.name

string

Optional name of the connection. This is what you will see in the Terminal UI.

Example:

"Frank's Trucking"

company.dotNumbers

string[]

Optional DOT numbers associated with this connection. This is what you will see in the Terminal UI.

account

object

required

Show child attributes

account.name

string

The name of the account according to the provider.

Example:

"Frank's Trucking"

account.dotNumbers

string[]

DOT numbers associated with the account according to the provider.

account.user

object

The user of the provider account that created the connection.

Show child attributes

account.user.sourceId

string

The ID of the user in the provider's system.

Example:

"1234567"

account.user.firstName

string

Example:

"John"

account.user.lastName

string

Example:

"Doe"

account.user.email

string

Example:

"[email protected]"

status

enum<string>

required

Enum values:

connected: active and authenticated connection
disconnected: connection is no longer authenticated - please ask your user to link the account again
archived: connection has been archived from view - attempts to re-connect will cause us to check the connection status again

Available options:

connected,

disconnected,

archived,

pending_deletion

provider

object

required

Show child attributes

provider.code

string

required

Every provider has a unique code to identify it across Terminal's system. You can find each provider's code under provider details.

Example:

"geotab"

provider.name

string

required

The name of the Telematics Service Provider.

Example:

"Geotab"

syncMode

enum<string>

default:automatic

required

Enum values:

automatic: Terminal will keep this connections data up to date
manual: Terminal will only sync data upon request

Available options:

automatic,

manual

token

string

required

This token is used when interacting with a connections' data.

Example:

"con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4"

options

Omnitracs Options · object

required

Omnitracs Options
Omnitracs ES Options
Omnitracs XRS Options

Show child attributes

options.ingestHistoryFromSourceSystem

boolean

default:true

linkUrl

string<uri>

required

The URL to send your user to in order to have them re-authenticate the connection.

Example:

"https://link.withterminal.com/connection/{CONNECTION_ID}?key={PUBLISHABLE_KEY}"

createdAt

string<date-time>

required

ISO 8601 date

Example:

"2021-01-06T03:24:53.000Z"

updatedAt

string<date-time>

required

ISO 8601 date

Example:

"2021-01-06T03:24:53.000Z"

externalId

string

An optional ID from your system that can be used to reference connections.

Example:

"1234"

sourceId

string

The ID used in the source system to represent the account this connection has access to.

This may be an organizationId or accountId.

Note: not all systems expose this information, in which case it may be undefined.

Example:

"123456789"

API Reference

Authentication

Vehicles

Drivers

Hours of Service

Vehicle Utilization

Trips

Devices

Safety

Groups

Trailers

IFTA

Connections

Data Management

Providers

Issues

Fault Codes

Webhook Events

Update Current Connection

Authorizations

Headers

Body

Response