Skip to main content
POST
/
link
/
short
Create Short Link URL
curl --request POST \
  --url https://api.withterminal.com/tsp/v1/link/short \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider": "geotab",
  "providerHints": [
    "geotab"
  ],
  "externalId": "fleet_456",
  "name": "<string>",
  "tags": [
    "Tag Name"
  ],
  "redirectUrl": "https://app.acme.com/telematics-success",
  "syncMode": "automatic",
  "backfill": {
    "startFrom": "2021-01-06T03:24:53.000Z",
    "days": 123
  },
  "template": "ltp_01HXQ4YK8V2X0X0X0X0X0X0X0X"
}
'
import requests

url = "https://api.withterminal.com/tsp/v1/link/short"

payload = {
"provider": "geotab",
"providerHints": ["geotab"],
"externalId": "fleet_456",
"name": "<string>",
"tags": ["Tag Name"],
"redirectUrl": "https://app.acme.com/telematics-success",
"syncMode": "automatic",
"backfill": {
"startFrom": "2021-01-06T03:24:53.000Z",
"days": 123
},
"template": "ltp_01HXQ4YK8V2X0X0X0X0X0X0X0X"
}
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',
providerHints: ['geotab'],
externalId: 'fleet_456',
name: '<string>',
tags: ['Tag Name'],
redirectUrl: 'https://app.acme.com/telematics-success',
syncMode: 'automatic',
backfill: {startFrom: '2021-01-06T03:24:53.000Z', days: 123},
template: 'ltp_01HXQ4YK8V2X0X0X0X0X0X0X0X'
})
};

fetch('https://api.withterminal.com/tsp/v1/link/short', 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/link/short",
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',
'providerHints' => [
'geotab'
],
'externalId' => 'fleet_456',
'name' => '<string>',
'tags' => [
'Tag Name'
],
'redirectUrl' => 'https://app.acme.com/telematics-success',
'syncMode' => 'automatic',
'backfill' => [
'startFrom' => '2021-01-06T03:24:53.000Z',
'days' => 123
],
'template' => 'ltp_01HXQ4YK8V2X0X0X0X0X0X0X0X'
]),
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/link/short"

payload := strings.NewReader("{\n \"provider\": \"geotab\",\n \"providerHints\": [\n \"geotab\"\n ],\n \"externalId\": \"fleet_456\",\n \"name\": \"<string>\",\n \"tags\": [\n \"Tag Name\"\n ],\n \"redirectUrl\": \"https://app.acme.com/telematics-success\",\n \"syncMode\": \"automatic\",\n \"backfill\": {\n \"startFrom\": \"2021-01-06T03:24:53.000Z\",\n \"days\": 123\n },\n \"template\": \"ltp_01HXQ4YK8V2X0X0X0X0X0X0X0X\"\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/link/short")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"provider\": \"geotab\",\n \"providerHints\": [\n \"geotab\"\n ],\n \"externalId\": \"fleet_456\",\n \"name\": \"<string>\",\n \"tags\": [\n \"Tag Name\"\n ],\n \"redirectUrl\": \"https://app.acme.com/telematics-success\",\n \"syncMode\": \"automatic\",\n \"backfill\": {\n \"startFrom\": \"2021-01-06T03:24:53.000Z\",\n \"days\": 123\n },\n \"template\": \"ltp_01HXQ4YK8V2X0X0X0X0X0X0X0X\"\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.withterminal.com/tsp/v1/link/short")

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 \"providerHints\": [\n \"geotab\"\n ],\n \"externalId\": \"fleet_456\",\n \"name\": \"<string>\",\n \"tags\": [\n \"Tag Name\"\n ],\n \"redirectUrl\": \"https://app.acme.com/telematics-success\",\n \"syncMode\": \"automatic\",\n \"backfill\": {\n \"startFrom\": \"2021-01-06T03:24:53.000Z\",\n \"days\": 123\n },\n \"template\": \"ltp_01HXQ4YK8V2X0X0X0X0X0X0X0X\"\n}"

response = http.request(request)
puts response.read_body
{
  "id": "slk_01JB7K3N2QZP7TVR4FX8SDWFH9",
  "code": "az9qtk2d",
  "url": "https://term.new/az9qtk2d",
  "expiresAt": "2021-01-06T03:24:53.000Z"
}
{
"id": "slk_01JB7K3N2QZP7TVR4FX8SDWFH9",
"code": "az9qtk2d",
"url": "https://term.new/az9qtk2d",
"expiresAt": "2021-01-06T03:24:53.000Z"
}
{
"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."
}
{
"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"
}
The response contains an 8-character code and the full url to share with your user. Short links are valid for 1 year from creation. Identical request bodies are de-duplicated automatically. Calling this endpoint a second time with the same parameters returns the original short link with an Idempotent-Replayed: true response header.

Authorizations

Authorization
string
header
required

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

Body

application/json
provider
string

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"

providerHints
string[]

An optional list of provider codes to hoist to the top of the Link provider list.

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

externalId
string

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

Example:

"fleet_456"

name
string

An optional human-readable name to associate with the resulting connection.

tags
string[]

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

redirectUrl
string<uri>

URL to redirect your user to after they complete the Link flow.

Example:

"https://app.acme.com/telematics-success"

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
backfill
object

Optional backfill to be requested upon successful connection. Will start from NOW if not provided.

template
string<ulid>

Unique identifier for the Link Template.

Example:

"ltp_01HXQ4YK8V2X0X0X0X0X0X0X0X"

Response

OK

A short URL for the Link onboarding flow. The associated parameters are stored at creation time and retrieved when your user visits the URL.

id
string<ulid>
required

Durable identifier for the short link resource.

Pattern: ^slk_[0-9A-HJKMNP-TV-Z]{26}$
Example:

"slk_01JB7K3N2QZP7TVR4FX8SDWFH9"

code
string
required

8-character code that is associated with the original Link parameters.

Pattern: ^[a-hjkmnp-z2-9]{8}$
Example:

"az9qtk2d"

url
string<uri>
required

Full short URL to share with your user.

Example:

"https://term.new/az9qtk2d"

expiresAt
string<date-time>
required
Example:

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