Skip to main content
Understanding these core concepts is essential for building successful integrations with the Catena platform. These entities form the foundation of how fleets connect to telematics providers and share data with partners.

​
Business Flow

Partner

Your organization—the customer using Catena’s API to access fleet telematics data.Key Points:
  • Create invitations to onboard fleet companies
  • Receive data from fleets that have authorized sharing
  • Each partner has unique API credentials and access controls

Fleet

A trucking or logistics company that operates commercial vehicles with telematics devices.Key Points:
  • Own the telematics data generated by their vehicles
  • Control which partners can access their data
  • Can connect to multiple telematics providers

​
Invitation Flow

Invitation

A unique magic link created by partners to invite fleet companies to share their telematics data.How It Works:
  1. Partner creates an invitation with a time-limited magic link
  2. Partner directs fleet to the magic link (in-app, email, etc.)
  3. Fleet opens the link and enters Catena Connect onboarding
  4. Onboarding automatically creates a Share Agreement
  5. Onboarding creates Connection(s) after fleet provides TSP credentials
  6. Fleet is redirected back to partner’s application
Key Points:
  • Single-use links that expire after a set period
  • One fleet per invitation
  • Can be customized with success/failure redirect URLs
  • A callback URL (webhooks) can be configured to notify partners of fleet interaction with the invitation
  • Magic link handles authentication securely
  • Catena Connect can be white-labeled to match partner branding
Use the Organizations API to create invitations programmatically.

Share Agreement

A data sharing contract automatically created during onboarding that defines which telematics data types the partner can access.Examples of Data Scopes:
  • vehicles - Vehicle information (VIN, make, model, year)
  • drivers - Driver profiles and assignments
  • vehicle_locations - Real-time and historical GPS data
  • hos_events - Hours of Service duty status changes
  • … and more
Key Points:
  • Created automatically when fleet opens invitation link
  • Acts as access control for all API requests and webhooks
  • Fleets maintain full control over shared data
  • Persists until explicitly revoked
All API requests automatically filter data based on active share agreements. You’ll only receive data from authorized fleets.
Map Catena’s fleet_id to your internal fleet_ref by querying the share agreements endpoint.

​
Connection Flow

Connection

A link between a fleet and a telematics service provider (TSP) that contains the authentication credentials needed to fetch the fleet’s data.How It Works:
  1. Fleet provides TSP credentials during onboarding
  2. Catena validates credentials with the TSP’s API
  3. Connection is created and credentials are encrypted
  4. Catena uses the connection to authenticate data ingestion requests
Key Points:
  • Fleets can have multiple connections
  • Credentials are encrypted and securely stored
  • Connections enable automatic data synchronization
  • Each connection links to exactly one TSP
Learn when to use fleet_ref vs. connection_id in the Filter & Query Data guide.

​
Data Ingestion Flow

Schedule

An automated task that fetches telematics data from a TSP on a recurring basis.How It Works:
  • Created automatically when a connection is established
  • Runs at defined intervals based on data type
  • Triggers executions that perform the actual data fetch
Key Points:
  • Different data types have different polling frequencies
  • Schedules are managed automatically by Catena
  • Location data typically updates every minute
  • Metadata (vehicles, drivers) updates less frequently
Check ingestion frequency: Query the List Schedules endpoint filtered by connection_id to see the exact polling frequency for each resource type and fleet.
Real-Time Updates: For instant notifications when data changes, use webhooks instead of relying on schedule polling our Telematics API.

Execution

A single run of a schedule that fetches and processes telematics data from a TSP.How It Works:
  1. Schedule triggers an execution at the specified interval
  2. Execution authenticates with the TSP using the connection credentials
  3. Data is fetched from the TSP API
  4. Data is normalized into Catena’s unified format
  5. Data is stored in the telematics database
  6. Events are emitted for webhook subscriptions
  7. Partners receive notifications if they have active webhooks
  8. Partners can query the Telematics API for the latest data
Key Points:
  • Each execution fetches data for a specific time window
  • Failed executions are retried automatically with built-in rate limiting against TSP APIs
  • Execution history is available for troubleshooting
  • Multiple executions can run concurrently for different schedules

​
Putting It All Together

Here’s how these concepts work together in a typical integration:
1

Partner Onboards Fleet

You create an invitation and send it to a fleet company. The fleet accepts and authorizes connections to their telematics providers, creating a share agreement.
2

Catena Creates Schedules

Catena automatically sets up schedules to fetch data from each connected TSP based on the share agreement scopes.
3

Executions Run Automatically

Schedules trigger executions that fetch, normalize, and store telematics data from the TSP APIs.
4

You Access the Data

Query the Telematics API to retrieve data, or subscribe to webhooks for real-time notifications when data changes.