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.catena.eu/?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"
}

Documentation Index

Fetch the complete documentation index at: https://docs.catenatelematics.com/llms.txt

Use this file to discover all available pages before exploring further.

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)