Skip to navigation
OrganizationsTMS Invitations

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.

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.
tms_account_refstringRequired
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_tmslist of strings or nullOptional

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_tmslist of strings or nullOptional

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.

permissionsmap from strings to enums or nullOptional

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.

Allowed values:
expires_in_hoursintegerOptional1-672Defaults to 24

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

Response

Existing invitation refreshed (already exists for this tms_account_ref)

idstringformat: "uuid"
Unique invitation identifier
created_atdatetime
When the invitation was created
expires_atdatetime
The expiration date and time of the invitation
expires_in_hoursinteger
The number of hours the invitation is valid for.
statusenum

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

Allowed values:
tms_account_refstring
Your internal identifier for the TMS account. Use this to map Catena TMS accounts back to your system.
partner_idstringformat: "uuid"
Your organization ID requesting access to TMS account data
partner_slugstring or null
The slug of your organization
accepted_atdatetime or null
The date and time the invitation was accepted. Null if not accepted.
accepted_bystring or null
Identifier of who accepted the invitation on behalf of the TMS account. Null if not accepted.
pre_registration_access_tokenstring or null

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_tokenstring or null

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_reasonstring or null
The reason provided for declining the invitation. Null if invitation was not declined.
declined_atdatetime or null
The date the invitation was declined. Null if invitation was not declined.
limit_tmslist of strings or null
Restrict which transportation management systems the TMS account can connect to.
exclude_tmslist of strings or null
Exclude specific transportation management systems from the ones shown to the TMS account.
permissionsmap from strings to enums

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

Allowed values:
tms_account_idstring or nullOptionalformat: "uuid"
The Catena TMS account ID created after accepting the invitation. Null if invitation has not been accepted.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
405
Method Not Allowed Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error