Skip to main content
POST
/
v2
/
orgs
/
invitations
Create Invitation
curl --request POST \
  --url https://api.catenatelematics.com/v2/orgs/invitations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
{
  "accepted_at": "2025-12-11T14:22:00Z",
  "callback_url": "https://api.example.com/webhooks/catena",
  "created_at": "2025-12-11T10:30:00Z",
  "expires_at": "2025-12-12T10:30:00Z",
  "expires_in_hours": 24,
  "failure_redirect_url": "https://app.example.com/onboarding/failure",
  "fleet_id": "98765432-10fe-dcba-9876-543210fedcba",
  "fleet_name": "Swift Transport LLC",
  "fleet_ref": "FLEET-12345",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "limit_tsps": [
    "samsara",
    "geotab"
  ],
  "magic_link": "https://connect.catenatelematics.com/?invite=01234567-89ab-cdef-0123-456789abcdef",
  "partner_id": "11223344-5566-7788-99aa-bbccddeeff00",
  "partner_slug": "acme-logistics",
  "permissions": {
    "hos_events": "read",
    "user": "read_write",
    "vehicle": "read_write",
    "vehicle_location": "read"
  },
  "pre_registration_access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "pre_registration_refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "status": "accepted",
  "success_redirect_url": "https://app.example.com/onboarding/success"
}

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 fleet invitation

​
fleet_ref
string
required

Your internal fleet identifier. Use this to map Catena fleets back to your system. This value will be returned in webhooks and redirect URLs.

​
fleet_name
string | null

Pre-populate the fleet name during onboarding. The fleet can modify this during acceptance. Only letters, numbers, and spaces are allowed.

​
fleet_email
string<email> | null

Pre-populate the fleet contact email. Optional but recommended for faster onboarding.

​
fleet_regulatory_id
string | null

Pre-populate the fleet's regulatory identifier (e.g., DOT number, EASA ID). Helps with fleet verification.

​
fleet_regulatory_id_type
string | null

Pre-populate the type of regulatory ID provided (e.g., DOT, EASA, MC). Required if regulatory_id is set.

​
fleet_phone
string<phone> | null

Pre-populate the phone number of the fleet

​
fleet_website
string<uri> | null

Pre-populate the website of the fleet

Required string length: 1 - 2083
​
fleet_country_code
string | null

Pre-populate the country code of the fleet

Pattern: ^\w{3}$
​
success_redirect_url
string<uri> | null

The URL to redirect the user to after onboarding successfully on Catena Connect. Available query parameters: invitation_id, fleet_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, fleet_ref.

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

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

Required string length: 1 - 2083
​
limit_tsps
string[] | null

Restrict which telematics providers the fleet can connect to. Useful if you only need data from specific TSPs. If omitted, all available TSPs are shown.

​
permissions
Required Permissions · object

Defines which resources (vehicle, locations, users, etc.) the fleet must grant access to and the permission level (read, write) for each. If omitted, we will require READ permissions for all resources.

​
expires_in_hours
integer
default:24

How long the invitation link remains valid (1-672 hours). Default is 24 hours. Consider longer durations for email campaigns.

Required range: 1 <= x <= 672
​
partner_provided_fleet_name
string | null
deprecated

Deprecated: Use fleet_name instead. Pre-populate the fleet name during onboarding.

​
partner_provided_fleet_email
string<email> | null
deprecated

Deprecated: Use fleet_email instead. Pre-populate the fleet contact email.

​
partner_provided_fleet_regulatory_id
string | null
deprecated

Deprecated: Use fleet_regulatory_id instead. Pre-populate the fleet's regulatory identifier.

​
partner_provided_fleet_regulatory_id_type
string | null
deprecated

Deprecated: Use fleet_regulatory_id_type instead. Pre-populate the type of regulatory ID.

​
partner_provided_fleet_phone
string<phone> | null
deprecated

Deprecated: Use fleet_phone instead. Pre-populate the phone number of the fleet.

​
partner_provided_fleet_website
string<uri> | null
deprecated

Deprecated: Use fleet_website instead. Pre-populate the website of the fleet.

Required string length: 1 - 2083
​
partner_provided_fleet_country_code
string | null
deprecated

Deprecated: Use fleet_country_code instead. Pre-populate the country code of the fleet.

Pattern: ^\w{3}$

Response

Existing invitation refreshed (already exists for this fleet_ref)

API model for reading a fleet invitation

Contains the complete invitation state including acceptance/decline status. Use this to track invitation lifecycle and retrieve tokens for accepted invitations.

​
id
string<uuid>
required

Unique invitation identifier

​
created_at
string<date-time>
required

When the invitation was created

​
magic_link
string
required

The magic link that is used to open Catena Connect and accept the invitation. Share this URL with the fleet 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, or expired)

Available options:
active,
accepted,
declined,
expired,
deleted
​
fleet_name
string | null
required

Pre-populate the fleet name during onboarding. The fleet can modify this during acceptance.

​
accepted_at
string<date-time> | null
required

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

​
pre_registration_access_token
string | null
required

The JWT token used to pre-register the fleet. It allows the fleet 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 fleet. It allows the fleet to create connections after accepting the invitation even without registering a user. Value is set after the invitation is accepted.

​
callback_url
string<uri> | null
required

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

Required string length: 1 - 2083
​
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, fleet_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, fleet_ref.

Required string length: 1 - 2083
​
limit_tsps
string[] | null
required

Restrict which telematics providers the fleet can connect to. Useful if you only need data from specific TSPs. If omitted, all available TSPs are shown.

​
partner_slug
string | null
required

The slug of your organization

​
partner_id
string<uuid>
required

Your organization ID requesting access to fleet data

​
decline_reason
string | null
required

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

​
declined_at
string<date-time> | null
required

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

​
fleet_ref
string
required

Your internal fleet identifier. Use this to map Catena fleets back to your system. This value will be returned in webhooks and redirect URLs.

​
permissions
Required Permissions · object
required

Defines which resources (vehicle, locations, users, etc.) the fleet must grant access to and the permission level (read, write) for each.

​
fleet_email
string<email> | null
required

The contact email for the fleet.

​
fleet_regulatory_id
string | null
required

The fleet's regulatory identifier (e.g., DOT number).

​
fleet_regulatory_id_type
string | null
required

The type of regulatory ID (e.g., 'DOT', 'MC').

​
fleet_phone
string | null
required

The phone number for the fleet.

​
fleet_website
string | null
required

The website URL for the fleet.

​
fleet_country_code
string | null
required

The ISO 3166-1 alpha-3 country code for the fleet.

​
partner_provided_fleet_name
string | null
required
deprecated

Deprecated: Use fleet_name instead.

​
partner_provided_fleet_email
string<email> | null
required
deprecated

Deprecated: Use fleet_email instead.

​
partner_provided_fleet_regulatory_id
string | null
required
deprecated

Deprecated: Use fleet_regulatory_id instead.

​
partner_provided_fleet_regulatory_id_type
string | null
required
deprecated

Deprecated: Use fleet_regulatory_id_type instead.

​
partner_provided_fleet_phone
string | null
required
deprecated

Deprecated: Use fleet_phone instead.

​
partner_provided_fleet_website
string | null
required
deprecated

Deprecated: Use fleet_website instead.

​
partner_provided_fleet_country_code
string | null
required
deprecated

Deprecated: Use fleet_country_code instead.

​
fleet_id
string<uuid> | null

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