WIwithterminal
Connections

Update Current Connection

Changed on

Update the details of the current active connection. The current connection is derived from the provided connection token.

Across all lists, the maximum is about 8,000 IDs. A larger update is rejected with 422 and is not saved. If one list contains most vehicles or drivers, use the opposite list: excludeIds for the ones to skip, or includeIds for the ones to keep.

patch/connections/current

Request

  • Base URL
    https://api.withterminal.com/tsp/v1
  • URL
    https://api.withterminal.com/tsp/v1/connections/current
  • Auth
    HTTP bearer

Headers

Connection-Tokenstring required
Example:con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4

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

Request body

status'connected' | 'archived' | 'disconnected'
externalIdstring
syncMode'automatic' | 'manual'

Enum values:

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

Example request

{
  "company": {
    "name": "Acme Inc."
  },
  "filters": {
    "vehicles": {
      "excludeIds": [
        "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ],
      "includeIds": [
        "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ]
    },
    "drivers": {
      "excludeIds": [
        "drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ],
      "includeIds": [
        "drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ]
    }
  }
}

Response

OK

idstring ulid required
externalIdstring

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

sourceIdstring

The ID used to represent the entity in the source system.

syncMode'automatic' | 'manual' required

Enum values:

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

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

tagsstring[]

An optional list of tags from your system that can be used to reference connections.

createdAtstring date-time required

ISO 8601 date

updatedAtstring date-time required

ISO 8601 date

status'connected' | 'disconnected' | 'archived' | 'pending_deletion' required

The current status of the connection.

linkUrlstring uri required

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

Example response

{
  "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": "john.doe@example.com"
    }
  },
  "provider": {
    "code": "geotab",
    "name": "Geotab"
  },
  "externalId": "1234",
  "sourceId": "123456789",
  "token": "con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4",
  "tags": [
    "Tag Name"
  ],
  "createdAt": "2021-01-06T03:24:53.000Z",
  "updatedAt": "2021-01-06T03:24:53.000Z",
  "filters": {
    "vehicles": {
      "excludeIds": [
        "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ],
      "includeIds": [
        "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ]
    },
    "drivers": {
      "excludeIds": [
        "drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ],
      "includeIds": [
        "drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
      ]
    }
  },
  "linkUrl": "https://link.withterminal.com/connection/{CONNECTION_ID}?key={PUBLISHABLE_KEY}"
}

Changes

  • 71081936e1bdRevision changes
    • breaking

      added to the response body oneOf list for the response status

    • warning

      added the new oauth_client_id_unknown enum value to the response property for the response status

    • warning

      added the new provider_timeout enum value to the response property for the response status

    • info

      added subschema #1: Omnitracs Options subschema #2: Omnitracs ES Options subschema #3: Omnitracs XRS Options to the request property oneOf list

    • info

      removed subschema #1: Full Connection subschema #2: Deleted Connection from the response body oneOf list for the response status

    • info

      added the non-success response with the status