Skip to main content
POST
Create Tms Invitation

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

API model for creating a TMS account invitation

tms_account_ref
string
required

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.

limit_tms
string[] | null

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_tms
string[] | null

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.

permissions
Required Permissions · object | null

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.

success_redirect_url
string<uri> | null

The URL to redirect the user to after onboarding successfully on Catena Connect. Available query parameters: invitation_id, tms_account_ref.

Required string length: 1 - 2083
failure_redirect_url
string<uri> | null

The 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.

Required string length: 1 - 2083
callback_url
string<uri> | null

Your webhook endpoint to receive real-time notifications for invitation acceptance, TMS share agreement creation, and connection status updates. Must be HTTPS.

Required string length: 1 - 2083
expires_in_hours
integer
default:72

How long the invitation link remains valid (1-672 hours). Default is 72 hours.

Required range: 1 <= x <= 672

Response

Existing invitation refreshed (already exists for this tms_account_ref)

API model for reading a TMS account invitation

id
string<uuid>
required

Unique invitation identifier

created_at
string<date-time>
required

When the invitation was created

The magic link used to accept the invitation. Share this URL with the TMS account to begin onboarding.

expires_at
string<date-time>
required

The expiration date and time of the invitation

expires_in_hours
integer
required

The number of hours the invitation is valid for.

status
enum<string>
required

The current status of the invitation (active, accepted, declined, expired, or deleted)

Available options:
active,
accepted,
declined,
expired,
deleted
tms_account_ref
string
required

Your internal identifier for the TMS account. Use this to map Catena TMS accounts back to your system.

partner_id
string<uuid>
required

Your organization ID requesting access to TMS account data

partner_slug
string | null
required

The slug of your organization

accepted_at
string<date-time> | null
required

The date and time the invitation was accepted. Null if not accepted.

accepted_by
string | null
required

Identifier of who accepted the invitation on behalf of the TMS account. Null if not accepted.

pre_registration_access_token
string | null
required

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.

pre_registration_refresh_token
string | null
required

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.

decline_reason
string | null
required

The reason provided for declining the invitation. Null if invitation was not declined.

declined_at
string<date-time> | null
required

The date the invitation was declined. Null if invitation was not declined.

limit_tms
string[] | null
required

Restrict which transportation management systems the TMS account can connect to.

exclude_tms
string[] | null
required

Exclude specific transportation management systems from the ones shown to the TMS account.

permissions
Required Permissions · object
required

Defines which TMS-sourced resources (loads, shipments, carriers, etc.) the TMS account must grant access to and the permission level for each.

success_redirect_url
string<uri> | null
required

The URL to redirect the user to after onboarding successfully on Catena Connect. Available query parameters: invitation_id, tms_account_ref.

Required string length: 1 - 2083
failure_redirect_url
string<uri> | null
required

The 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.

Required string length: 1 - 2083
callback_url
string<uri> | null
required

Your webhook endpoint to receive real-time notifications for invitation acceptance, TMS share agreement creation, and connection status updates. Must be HTTPS.

Required string length: 1 - 2083
tms_account_id
string<uuid> | null

The Catena TMS account ID created after accepting the invitation. Null if invitation has not been accepted.