WIwithterminal
Connections

Create Connection

Changed on

Create a new connection via API. This endpoint can be used to provide a completely custom connection creation experience for your customers.

For most use cases we recommend using the Link UI to create connections.

post/connections

Request

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

Request body

OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR

Example request

{
  "backfill": {
    "startFrom": "2021-01-06T03:24:53.000Z"
  },
  "tags": [
    "Tag Name"
  ],
  "agreements": [
    {
      "acceptedAt": "2021-01-06T03:24:53.000Z",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36"
    }
  ]
}

Response

Created

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