curl --request POST \
--url https://api.catenatelematics.com/v2/orgs/tms-invitations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tms_account_ref": "<string>"
}
'import requests
url = "https://api.catenatelematics.com/v2/orgs/tms-invitations"
payload = { "tms_account_ref": "<string>" }
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({tms_account_ref: '<string>'})
};
fetch('https://api.catenatelematics.com/v2/orgs/tms-invitations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.catenatelematics.com/v2/orgs/tms-invitations"
payload := strings.NewReader("{\n \"tms_account_ref\": \"<string>\"\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))
}require 'uri'
require 'net/http'
url = URI("https://api.catenatelematics.com/v2/orgs/tms-invitations")
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 \"tms_account_ref\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyHttpResponse<String> response = Unirest.post("https://api.catenatelematics.com/v2/orgs/tms-invitations")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"tms_account_ref\": \"<string>\"\n}")
.asString();using RestSharp;
var options = new RestClientOptions("https://api.catenatelematics.com/v2/orgs/tms-invitations");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
request.AddJsonBody("{\n \"tms_account_ref\": \"<string>\"\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.catenatelematics.com/v2/orgs/tms-invitations",
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([
'tms_account_ref' => '<string>'
]),
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;
}{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z",
"magic_link": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"expires_in_hours": 123,
"status": "active",
"tms_account_ref": "<string>",
"partner_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"partner_slug": "<string>",
"accepted_at": "2023-11-07T05:31:56Z",
"accepted_by": "<string>",
"pre_registration_access_token": "<string>",
"pre_registration_refresh_token": "<string>",
"decline_reason": "<string>",
"declined_at": "2023-11-07T05:31:56Z",
"limit_tms": [
"<string>"
],
"exclude_tms": [
"<string>"
],
"permissions": {},
"success_redirect_url": "<string>",
"failure_redirect_url": "<string>",
"callback_url": "<string>",
"tms_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z",
"magic_link": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"expires_in_hours": 123,
"status": "active",
"tms_account_ref": "<string>",
"partner_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"partner_slug": "<string>",
"accepted_at": "2023-11-07T05:31:56Z",
"accepted_by": "<string>",
"pre_registration_access_token": "<string>",
"pre_registration_refresh_token": "<string>",
"decline_reason": "<string>",
"declined_at": "2023-11-07T05:31:56Z",
"limit_tms": [
"<string>"
],
"exclude_tms": [
"<string>"
],
"permissions": {},
"success_redirect_url": "<string>",
"failure_redirect_url": "<string>",
"callback_url": "<string>",
"tms_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"code": 400,
"message": "Bad Request",
"detail": "<string>"
}{
"code": 401,
"message": "Unauthorized",
"detail": "<string>"
}{
"code": 403,
"message": "Forbidden",
"detail": "<string>"
}{
"code": 404,
"message": "Not Found",
"detail": "<string>"
}{
"code": 405,
"message": "Method Not Allowed",
"detail": "<string>"
}{
"code": 409,
"message": "Conflict",
"detail": "<string>"
}{
"code": 422,
"message": "Invalid Request Body",
"detail": [
{
"path": "<string>",
"input": "<string>",
"message": "<string>",
"error_type": "<string>"
}
]
}{
"code": 429,
"message": "Too Many Requests",
"detail": {
"retry_after_seconds": 123,
"message": "<string>"
}
}{
"message": "Internal Server Error"
}Create Tms Invitation
Create an invitation with a magic link to onboard a TMS account.
Returns an invitation object with a unique ID that serves as the magic link token. Share this link with the TMS account to begin the onboarding process. Once accepted, a TMS share agreement is automatically created to enable data sharing.
Note: If an active, accepted, or declined invitation already exists for the same tms_account_ref,
the invitation is refreshed (expiration extended, reactivated if declined) and returned with status
code 200 instead of 201.
curl --request POST \
--url https://api.catenatelematics.com/v2/orgs/tms-invitations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tms_account_ref": "<string>"
}
'import requests
url = "https://api.catenatelematics.com/v2/orgs/tms-invitations"
payload = { "tms_account_ref": "<string>" }
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({tms_account_ref: '<string>'})
};
fetch('https://api.catenatelematics.com/v2/orgs/tms-invitations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.catenatelematics.com/v2/orgs/tms-invitations"
payload := strings.NewReader("{\n \"tms_account_ref\": \"<string>\"\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))
}require 'uri'
require 'net/http'
url = URI("https://api.catenatelematics.com/v2/orgs/tms-invitations")
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 \"tms_account_ref\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyHttpResponse<String> response = Unirest.post("https://api.catenatelematics.com/v2/orgs/tms-invitations")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"tms_account_ref\": \"<string>\"\n}")
.asString();using RestSharp;
var options = new RestClientOptions("https://api.catenatelematics.com/v2/orgs/tms-invitations");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
request.AddJsonBody("{\n \"tms_account_ref\": \"<string>\"\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.catenatelematics.com/v2/orgs/tms-invitations",
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([
'tms_account_ref' => '<string>'
]),
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;
}{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z",
"magic_link": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"expires_in_hours": 123,
"status": "active",
"tms_account_ref": "<string>",
"partner_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"partner_slug": "<string>",
"accepted_at": "2023-11-07T05:31:56Z",
"accepted_by": "<string>",
"pre_registration_access_token": "<string>",
"pre_registration_refresh_token": "<string>",
"decline_reason": "<string>",
"declined_at": "2023-11-07T05:31:56Z",
"limit_tms": [
"<string>"
],
"exclude_tms": [
"<string>"
],
"permissions": {},
"success_redirect_url": "<string>",
"failure_redirect_url": "<string>",
"callback_url": "<string>",
"tms_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z",
"magic_link": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"expires_in_hours": 123,
"status": "active",
"tms_account_ref": "<string>",
"partner_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"partner_slug": "<string>",
"accepted_at": "2023-11-07T05:31:56Z",
"accepted_by": "<string>",
"pre_registration_access_token": "<string>",
"pre_registration_refresh_token": "<string>",
"decline_reason": "<string>",
"declined_at": "2023-11-07T05:31:56Z",
"limit_tms": [
"<string>"
],
"exclude_tms": [
"<string>"
],
"permissions": {},
"success_redirect_url": "<string>",
"failure_redirect_url": "<string>",
"callback_url": "<string>",
"tms_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"code": 400,
"message": "Bad Request",
"detail": "<string>"
}{
"code": 401,
"message": "Unauthorized",
"detail": "<string>"
}{
"code": 403,
"message": "Forbidden",
"detail": "<string>"
}{
"code": 404,
"message": "Not Found",
"detail": "<string>"
}{
"code": 405,
"message": "Method Not Allowed",
"detail": "<string>"
}{
"code": 409,
"message": "Conflict",
"detail": "<string>"
}{
"code": 422,
"message": "Invalid Request Body",
"detail": [
{
"path": "<string>",
"input": "<string>",
"message": "<string>",
"error_type": "<string>"
}
]
}{
"code": 429,
"message": "Too Many Requests",
"detail": {
"retry_after_seconds": 123,
"message": "<string>"
}
}{
"message": "Internal Server Error"
}Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Body
API model for creating a TMS account invitation
Your internal identifier for the TMS account. Use this to map Catena TMS accounts back to your system. This value will be returned in webhooks and redirect URLs.
Restrict which transportation management systems the TMS account can connect to. Useful if you only need data from specific TMSs. If omitted, all available TMSs are shown. Cannot be combined with exclude_tms.
Exclude specific transportation management systems from the ones shown to the TMS account. Useful if you want the TMS account to have access to every TMS except a few. Cannot be combined with limit_tms.
Defines which TMS-sourced resources (loads, shipments, carriers, etc.) the TMS account must grant access to and the permission level for each. If omitted, we will request READ permissions for all resources.
Show child attributes
Show child attributes
The URL to redirect the user to after onboarding successfully on Catena Connect. Available query parameters: invitation_id, tms_account_ref.
1 - 2083The URL to redirect the user to after failing to onboard on Catena Connect (i.e. declining an invitation, opening an expired invitation, etc). Available query parameters: invitation_id, tms_account_ref.
1 - 2083Your webhook endpoint to receive real-time notifications for invitation acceptance, TMS share agreement creation, and connection status updates. Must be HTTPS.
1 - 2083How long the invitation link remains valid (1-672 hours). Default is 72 hours.
1 <= x <= 672Response
Existing invitation refreshed (already exists for this tms_account_ref)
API model for reading a TMS account invitation
Unique invitation identifier
When the invitation was created
The magic link used to accept the invitation. Share this URL with the TMS account to begin onboarding.
The expiration date and time of the invitation
The number of hours the invitation is valid for.
The current status of the invitation (active, accepted, declined, expired, or deleted)
active, accepted, declined, expired, deleted Your internal identifier for the TMS account. Use this to map Catena TMS accounts back to your system.
Your organization ID requesting access to TMS account data
The slug of your organization
The date and time the invitation was accepted. Null if not accepted.
Identifier of who accepted the invitation on behalf of the TMS account. Null if not accepted.
The JWT token used to pre-register the TMS account. It allows the TMS account to create connections after accepting the invitation even without registering a user. Value is set after the invitation is accepted.
The refresh token used to pre-register the TMS account. It allows the TMS account to create connections after accepting the invitation even without registering a user. Value is set after the invitation is accepted.
The reason provided for declining the invitation. Null if invitation was not declined.
The date the invitation was declined. Null if invitation was not declined.
Restrict which transportation management systems the TMS account can connect to.
Exclude specific transportation management systems from the ones shown to the TMS account.
Defines which TMS-sourced resources (loads, shipments, carriers, etc.) the TMS account must grant access to and the permission level for each.
Show child attributes
Show child attributes
The URL to redirect the user to after onboarding successfully on Catena Connect. Available query parameters: invitation_id, tms_account_ref.
1 - 2083The URL to redirect the user to after failing to onboard on Catena Connect (i.e. declining an invitation, opening an expired invitation, etc). Available query parameters: invitation_id, tms_account_ref.
1 - 2083Your webhook endpoint to receive real-time notifications for invitation acceptance, TMS share agreement creation, and connection status updates. Must be HTTPS.
1 - 2083The Catena TMS account ID created after accepting the invitation. Null if invitation has not been accepted.
Was this page helpful?