Skip to navigation
OrganizationsInvitations

Create Invitation

Create an invitation with a magic link to onboard a fleet.

Returns an invitation object with a unique ID that serves as the magic link token. Share this link with the fleet to begin the onboarding process. Once accepted, a share agreement is automatically created to enable data sharing.

Note: If an active, accepted, or declined invitation already exists for the same fleet_ref, the invitation is refreshed (expiration extended, tokens regenerated if accepted, reactivated if declined) and returned with status code 200 instead of 201.

Note: On refresh, limit_tsps and exclude_tsps are only updated when explicitly provided. Omitting them (or sending null) leaves the existing restriction on the invitation unchanged — it does not clear a previously set filter. To remove a limit_tsps/exclude_tsps restriction on refresh, you must explicitly pass an empty list, e.g. "limit_tsps": [].

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.
fleet_refstringRequired
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_namestring or nullOptional

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

fleet_emailstring or nullOptionalformat: "email"

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

fleet_regulatory_idstring or nullOptional

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

fleet_regulatory_id_typestring or nullOptional

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

fleet_phonestring or nullOptionalformat: "phone"

Pre-populate the phone number of the fleet

fleet_websitestring or nullOptionalformat: "uri"1-2083 characters

Pre-populate the website of the fleet

fleet_country_codestring or nullOptionalformat: "^\w{3}$"

Pre-populate the country code of the fleet

success_redirect_urlstring or nullOptionalformat: "uri"1-2083 characters

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

failure_redirect_urlstring or nullOptionalformat: "uri"1-2083 characters

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.

callback_urlstring or nullOptionalformat: "uri"1-2083 characters

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

limit_tspslist of strings or nullOptional

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. On refresh, this field is only updated when explicitly provided — omitting it leaves any existing restriction unchanged; pass an empty list ([]) to clear it. Cannot be combined with exclude_tsps.

exclude_tspslist of strings or nullOptional

Exclude specific telematics providers from the ones shown to the fleet. Useful if you want the fleet to have access to every TSP except a few. On refresh, this field is only updated when explicitly provided — omitting it leaves any existing restriction unchanged; pass an empty list ([]) to clear it. Cannot be combined with limit_tsps.

permissionsmap from strings to enums or nullOptional

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.

Allowed values:
expires_in_hoursintegerOptional1-672Defaults to 24

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

write_permissionslist of enums or nullOptional

Resources to request READ_WRITE access for, on top of the READ default for every other resource. Use this to bump a single resource (e.g. fuel_transaction) to read-write without having to enumerate every other resource. Cannot be combined with permissions — use permissions instead if you need an exact, narrower set of resources.

partner_provided_fleet_namestring or nullOptionalDeprecated

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

partner_provided_fleet_emailstring or nullOptionalformat: "email"Deprecated

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

partner_provided_fleet_regulatory_idstring or nullOptionalDeprecated

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

partner_provided_fleet_regulatory_id_typestring or nullOptionalDeprecated

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

partner_provided_fleet_phonestring or nullOptionalformat: "phone"Deprecated

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

partner_provided_fleet_websitestring or nullOptionalformat: "uri"1-2083 charactersDeprecated

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

partner_provided_fleet_country_codestring or nullOptionalformat: "^\w{3}$"Deprecated

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

Response

Existing invitation refreshed (already exists for this fleet_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, or expired)

Allowed values:
fleet_namestring or null

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

accepted_atdatetime or null
The date and time the invitation was accepted. Null if not accepted.
pre_registration_access_tokenstring or null

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

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_urlstring or nullformat: "uri"1-2083 characters

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

success_redirect_urlstring or nullformat: "uri"1-2083 characters

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

failure_redirect_urlstring or nullformat: "uri"1-2083 characters

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.

limit_tspslist of strings or 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.
exclude_tspslist of strings or null
Exclude specific telematics providers from the ones shown to the fleet. Useful if you want the fleet to have access to every TSP except a few.
partner_slugstring or null
The slug of your organization
partner_idstringformat: "uuid"
Your organization ID requesting access to fleet data
decline_reasonstring or null
The reason provided by the fleet for declining the invitation. Null if invitation was not declined.
declined_atdatetime or null
The date the invitation was declined by the fleet. Null if invitation was not declined.
fleet_refstring
Your internal fleet identifier. Use this to map Catena fleets back to your system. This value will be returned in webhooks and redirect URLs.
permissionsmap from strings to enums

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

Allowed values:
fleet_emailstring or nullformat: "email"
The contact email for the fleet.
fleet_regulatory_idstring or null

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

fleet_regulatory_id_typestring or null

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

fleet_phonestring or null
The phone number for the fleet.
fleet_websitestring or null
The website URL for the fleet.
fleet_country_codestring or null

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

partner_provided_fleet_namestring or nullRead-onlyDeprecated

Deprecated: Use fleet_name instead.

partner_provided_fleet_emailstring or nullRead-onlyformat: "email"Deprecated

Deprecated: Use fleet_email instead.

partner_provided_fleet_regulatory_idstring or nullRead-onlyDeprecated

Deprecated: Use fleet_regulatory_id instead.

partner_provided_fleet_regulatory_id_typestring or nullRead-onlyDeprecated

Deprecated: Use fleet_regulatory_id_type instead.

partner_provided_fleet_phonestring or nullRead-onlyDeprecated

Deprecated: Use fleet_phone instead.

partner_provided_fleet_websitestring or nullRead-onlyDeprecated

Deprecated: Use fleet_website instead.

partner_provided_fleet_country_codestring or nullRead-onlyDeprecated

Deprecated: Use fleet_country_code instead.

fleet_idstring or nullOptionalformat: "uuid"
The Catena fleet 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