Create Connection
curl --request POST \
--url https://api.withterminal.com/tsp/v1/connections \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"provider": "geotab",
"credentials": {},
"company": {
"name": "<string>",
"dotNumbers": [
"<string>"
]
},
"options": {},
"externalId": "<string>",
"syncMode": "automatic",
"backfill": {
"startFrom": "2021-01-06T03:24:53.000Z",
"days": 123
},
"tags": [
"Tag Name"
],
"agreements": [
{
"agreementUrl": "<string>",
"ipAddress": "127.0.0.1",
"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"
}
]
}
'import requests
url = "https://api.withterminal.com/tsp/v1/connections"
payload = {
"provider": "geotab",
"credentials": {},
"company": {
"name": "<string>",
"dotNumbers": ["<string>"]
},
"options": {},
"externalId": "<string>",
"syncMode": "automatic",
"backfill": {
"startFrom": "2021-01-06T03:24:53.000Z",
"days": 123
},
"tags": ["Tag Name"],
"agreements": [
{
"agreementUrl": "<string>",
"ipAddress": "127.0.0.1",
"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"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
provider: 'geotab',
credentials: {},
company: {name: '<string>', dotNumbers: ['<string>']},
options: {},
externalId: '<string>',
syncMode: 'automatic',
backfill: {startFrom: '2021-01-06T03:24:53.000Z', days: 123},
tags: ['Tag Name'],
agreements: [
{
agreementUrl: '<string>',
ipAddress: '127.0.0.1',
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'
}
]
})
};
fetch('https://api.withterminal.com/tsp/v1/connections', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.withterminal.com/tsp/v1/connections",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'provider' => 'geotab',
'credentials' => [
],
'company' => [
'name' => '<string>',
'dotNumbers' => [
'<string>'
]
],
'options' => [
],
'externalId' => '<string>',
'syncMode' => 'automatic',
'backfill' => [
'startFrom' => '2021-01-06T03:24:53.000Z',
'days' => 123
],
'tags' => [
'Tag Name'
],
'agreements' => [
[
'agreementUrl' => '<string>',
'ipAddress' => '127.0.0.1',
'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'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.withterminal.com/tsp/v1/connections"
payload := strings.NewReader("{\n \"provider\": \"geotab\",\n \"credentials\": {},\n \"company\": {\n \"name\": \"<string>\",\n \"dotNumbers\": [\n \"<string>\"\n ]\n },\n \"options\": {},\n \"externalId\": \"<string>\",\n \"syncMode\": \"automatic\",\n \"backfill\": {\n \"startFrom\": \"2021-01-06T03:24:53.000Z\",\n \"days\": 123\n },\n \"tags\": [\n \"Tag Name\"\n ],\n \"agreements\": [\n {\n \"agreementUrl\": \"<string>\",\n \"ipAddress\": \"127.0.0.1\",\n \"acceptedAt\": \"2021-01-06T03:24:53.000Z\",\n \"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\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.withterminal.com/tsp/v1/connections")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"provider\": \"geotab\",\n \"credentials\": {},\n \"company\": {\n \"name\": \"<string>\",\n \"dotNumbers\": [\n \"<string>\"\n ]\n },\n \"options\": {},\n \"externalId\": \"<string>\",\n \"syncMode\": \"automatic\",\n \"backfill\": {\n \"startFrom\": \"2021-01-06T03:24:53.000Z\",\n \"days\": 123\n },\n \"tags\": [\n \"Tag Name\"\n ],\n \"agreements\": [\n {\n \"agreementUrl\": \"<string>\",\n \"ipAddress\": \"127.0.0.1\",\n \"acceptedAt\": \"2021-01-06T03:24:53.000Z\",\n \"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\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.withterminal.com/tsp/v1/connections")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"provider\": \"geotab\",\n \"credentials\": {},\n \"company\": {\n \"name\": \"<string>\",\n \"dotNumbers\": [\n \"<string>\"\n ]\n },\n \"options\": {},\n \"externalId\": \"<string>\",\n \"syncMode\": \"automatic\",\n \"backfill\": {\n \"startFrom\": \"2021-01-06T03:24:53.000Z\",\n \"days\": 123\n },\n \"tags\": [\n \"Tag Name\"\n ],\n \"agreements\": [\n {\n \"agreementUrl\": \"<string>\",\n \"ipAddress\": \"127.0.0.1\",\n \"acceptedAt\": \"2021-01-06T03:24:53.000Z\",\n \"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\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"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"
},
"syncMode": "automatic",
"token": "con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4",
"createdAt": "2021-01-06T03:24:53.000Z",
"updatedAt": "2021-01-06T03:24:53.000Z",
"options": {},
"linkUrl": "https://link.withterminal.com/connection/{CONNECTION_ID}?key={PUBLISHABLE_KEY}",
"externalId": "1234",
"sourceId": "123456789",
"tags": [
"Tag Name"
],
"filters": {
"vehicles": {
"excludeIds": [
"vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
],
"includeIds": [
"vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
]
},
"drivers": {
"excludeIds": [
"drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
],
"includeIds": [
"drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
]
}
}
}{
"code": "bad_request",
"message": "Invalid request body",
"detail": [
{
"message": "'vehicleId' property must be a valid ulid",
"path": "{requestQuery}.vehicleId",
"suggestion": "Please ensure you submit a valid 'vehicleId' property",
"context": {}
}
]
}{
"code": "unauthorized",
"message": "Unauthorized Request",
"detail": "Please ensure you have a valid API key"
}{
"code": "forbidden",
"message": "Forbidden Request",
"detail": "Please ensure the connection token matches the resource you are attempting to access."
}{
"message": "<string>",
"detail": [
{
"message": "<string>",
"path": "<string>",
"suggestion": "<string>",
"context": {}
}
]
}{
"code": "too_many_requests",
"message": "Too Many Requests",
"retryAfter": 60,
"detail": "You have exceeded your rate limit. Please try again later."
}{
"code": "internal_server_error",
"message": "Internal Server Error",
"detail": "Something went wrong"
}{
"code": "gateway_timeout",
"message": "Gateway Timeout"
}Create Connection
Create a new connection via API. This endpoint can be used to provide a completely custom connection creation experience for your customers.
POST
/
connections
Create Connection
curl --request POST \
--url https://api.withterminal.com/tsp/v1/connections \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"provider": "geotab",
"credentials": {},
"company": {
"name": "<string>",
"dotNumbers": [
"<string>"
]
},
"options": {},
"externalId": "<string>",
"syncMode": "automatic",
"backfill": {
"startFrom": "2021-01-06T03:24:53.000Z",
"days": 123
},
"tags": [
"Tag Name"
],
"agreements": [
{
"agreementUrl": "<string>",
"ipAddress": "127.0.0.1",
"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"
}
]
}
'import requests
url = "https://api.withterminal.com/tsp/v1/connections"
payload = {
"provider": "geotab",
"credentials": {},
"company": {
"name": "<string>",
"dotNumbers": ["<string>"]
},
"options": {},
"externalId": "<string>",
"syncMode": "automatic",
"backfill": {
"startFrom": "2021-01-06T03:24:53.000Z",
"days": 123
},
"tags": ["Tag Name"],
"agreements": [
{
"agreementUrl": "<string>",
"ipAddress": "127.0.0.1",
"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"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
provider: 'geotab',
credentials: {},
company: {name: '<string>', dotNumbers: ['<string>']},
options: {},
externalId: '<string>',
syncMode: 'automatic',
backfill: {startFrom: '2021-01-06T03:24:53.000Z', days: 123},
tags: ['Tag Name'],
agreements: [
{
agreementUrl: '<string>',
ipAddress: '127.0.0.1',
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'
}
]
})
};
fetch('https://api.withterminal.com/tsp/v1/connections', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.withterminal.com/tsp/v1/connections",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'provider' => 'geotab',
'credentials' => [
],
'company' => [
'name' => '<string>',
'dotNumbers' => [
'<string>'
]
],
'options' => [
],
'externalId' => '<string>',
'syncMode' => 'automatic',
'backfill' => [
'startFrom' => '2021-01-06T03:24:53.000Z',
'days' => 123
],
'tags' => [
'Tag Name'
],
'agreements' => [
[
'agreementUrl' => '<string>',
'ipAddress' => '127.0.0.1',
'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'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.withterminal.com/tsp/v1/connections"
payload := strings.NewReader("{\n \"provider\": \"geotab\",\n \"credentials\": {},\n \"company\": {\n \"name\": \"<string>\",\n \"dotNumbers\": [\n \"<string>\"\n ]\n },\n \"options\": {},\n \"externalId\": \"<string>\",\n \"syncMode\": \"automatic\",\n \"backfill\": {\n \"startFrom\": \"2021-01-06T03:24:53.000Z\",\n \"days\": 123\n },\n \"tags\": [\n \"Tag Name\"\n ],\n \"agreements\": [\n {\n \"agreementUrl\": \"<string>\",\n \"ipAddress\": \"127.0.0.1\",\n \"acceptedAt\": \"2021-01-06T03:24:53.000Z\",\n \"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\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.withterminal.com/tsp/v1/connections")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"provider\": \"geotab\",\n \"credentials\": {},\n \"company\": {\n \"name\": \"<string>\",\n \"dotNumbers\": [\n \"<string>\"\n ]\n },\n \"options\": {},\n \"externalId\": \"<string>\",\n \"syncMode\": \"automatic\",\n \"backfill\": {\n \"startFrom\": \"2021-01-06T03:24:53.000Z\",\n \"days\": 123\n },\n \"tags\": [\n \"Tag Name\"\n ],\n \"agreements\": [\n {\n \"agreementUrl\": \"<string>\",\n \"ipAddress\": \"127.0.0.1\",\n \"acceptedAt\": \"2021-01-06T03:24:53.000Z\",\n \"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\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.withterminal.com/tsp/v1/connections")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"provider\": \"geotab\",\n \"credentials\": {},\n \"company\": {\n \"name\": \"<string>\",\n \"dotNumbers\": [\n \"<string>\"\n ]\n },\n \"options\": {},\n \"externalId\": \"<string>\",\n \"syncMode\": \"automatic\",\n \"backfill\": {\n \"startFrom\": \"2021-01-06T03:24:53.000Z\",\n \"days\": 123\n },\n \"tags\": [\n \"Tag Name\"\n ],\n \"agreements\": [\n {\n \"agreementUrl\": \"<string>\",\n \"ipAddress\": \"127.0.0.1\",\n \"acceptedAt\": \"2021-01-06T03:24:53.000Z\",\n \"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\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"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"
},
"syncMode": "automatic",
"token": "con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4",
"createdAt": "2021-01-06T03:24:53.000Z",
"updatedAt": "2021-01-06T03:24:53.000Z",
"options": {},
"linkUrl": "https://link.withterminal.com/connection/{CONNECTION_ID}?key={PUBLISHABLE_KEY}",
"externalId": "1234",
"sourceId": "123456789",
"tags": [
"Tag Name"
],
"filters": {
"vehicles": {
"excludeIds": [
"vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
],
"includeIds": [
"vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
]
},
"drivers": {
"excludeIds": [
"drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
],
"includeIds": [
"drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"
]
}
}
}{
"code": "bad_request",
"message": "Invalid request body",
"detail": [
{
"message": "'vehicleId' property must be a valid ulid",
"path": "{requestQuery}.vehicleId",
"suggestion": "Please ensure you submit a valid 'vehicleId' property",
"context": {}
}
]
}{
"code": "unauthorized",
"message": "Unauthorized Request",
"detail": "Please ensure you have a valid API key"
}{
"code": "forbidden",
"message": "Forbidden Request",
"detail": "Please ensure the connection token matches the resource you are attempting to access."
}{
"message": "<string>",
"detail": [
{
"message": "<string>",
"path": "<string>",
"suggestion": "<string>",
"context": {}
}
]
}{
"code": "too_many_requests",
"message": "Too Many Requests",
"retryAfter": 60,
"detail": "You have exceeded your rate limit. Please try again later."
}{
"code": "internal_server_error",
"message": "Internal Server Error",
"detail": "Something went wrong"
}{
"code": "gateway_timeout",
"message": "Gateway Timeout"
}For most use cases we recommend using the Link UI to create connections.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
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"
Show child attributes
Show child attributes
Enum values:
automatic: Terminal will keep this connections data up to datemanual: Terminal will only sync data upon request
Available options:
automatic, manual Optional backfill to be requested upon successful connection. Will start from NOW if not provided.
Show child attributes
Show child attributes
The agreements to link the connection to.
Show child attributes
Show child attributes
Response
Created
- Full Connection
- Deleted Connection
The connection your application has with your customer's TSP.
Example:
"conn_01GV12VR4DJP70GD1ZBK0SDWFH"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Enum values:
automatic: Terminal will keep this connections data up to datemanual: Terminal will only sync data upon request
Available options:
automatic, manual This token is used when interacting with a connections' data.
Pattern:
^con_tkn_\S+$Example:
"con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4"
The current status of the connection.
Available options:
connected, disconnected, archived, pending_deletion 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}"
An optional ID from your system that can be used to reference connections.
Example:
"1234"
The ID used in the source system to represent the account this connection has or had 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"
An optional list of tags from your system that can be used to reference connections.
Filters applied to connection data
Show child attributes
Show child attributes
⌘I