> ## 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. # Platform Concepts > Understand key concepts for integrating with the Catena Telematics API 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 ```mermaid theme={null} flowchart LR partner[["Partner
(You)"]] fleet[["Fleet"]] tsp[["TSP"]] catena["Catena Platform"] partner -->|"Creates"| invitation["Invitation"] invitation -->|"Sent to"| fleet fleet -->|"Accepts, Creates"| share_agreement["Share Agreement"] fleet -->|"Authorizes"| connection["Connection"] connection -->|"Links to"| tsp catena -->|"Schedules"| schedule["Schedule"] schedule -->|"Runs"| execution["Execution"] execution -->|"Fetches Data"| tsp catena -->|"Delivers Data"| partner style partner fill:#dc3545,stroke:none,color:#ffffff style fleet fill:#ffc107,stroke:none,color:#00354d style tsp fill:#28a745,stroke:none,color:#ffffff style catena fill:#0083bf,stroke:none,color:#ffffff style invitation fill:#00bae6,stroke:none,color:#ffffff style share_agreement fill:#00bae6,stroke:none,color:#ffffff style connection fill:#00bae6,stroke:none,color:#ffffff style schedule fill:#00bae6,stroke:none,color:#ffffff style execution fill:#00bae6,stroke:none,color:#ffffff ``` *** 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 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 ```mermaid theme={null} flowchart LR partner[["Partner"]] fleet[["Fleet"]] partner -->|"Creates"| invitation["Invitation
(magic link)"] invitation -->|"Sends"| fleet fleet -->|"Opens link"| onboarding["Catena Connect
Onboarding"] onboarding -->|"Creates"| share_agreement["Share Agreement"] onboarding -->|"Creates"| connection["Connection(s)"] onboarding -->|"Redirects back"| partner style partner fill:#dc3545,stroke:none,color:#ffffff style fleet fill:#ffc107,stroke:none,color:#00354d style invitation fill:#00bae6,stroke:none,color:#ffffff style onboarding fill:#e8f4f8,stroke:#0083bf,stroke-width:2px,color:#00354d style share_agreement fill:#00bae6,stroke:none,color:#ffffff style connection fill:#00bae6,stroke:none,color:#ffffff ``` *** 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](/api-reference/organizations-api) to create invitations programmatically. 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 ```mermaid theme={null} flowchart LR fleet[["Fleet"]] connection1["Connection
(Samsara)"] connection2["Connection
(Motive)"] samsara[["Samsara API"]] motive[["Motive API"]] fleet -->|"Authorizes"| connection1 fleet -->|"Authorizes"| connection2 connection1 -->|"Authenticates with"| samsara connection2 -->|"Authenticates with"| motive style fleet fill:#ffc107,stroke:none,color:#00354d style connection1 fill:#00bae6,stroke:none,color:#ffffff style connection2 fill:#00bae6,stroke:none,color:#ffffff style samsara fill:#28a745,stroke:none,color:#ffffff style motive fill:#28a745,stroke:none,color:#ffffff ``` *** 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](/recipes/filtering-requests) guide. *** ## Data Ingestion Flow ```mermaid theme={null} flowchart LR schedule["Schedule"] execution["Execution"] tsp[["TSP API"]] database[("Telematics
Database")] api["Telematics API"] webhook["Webhook"] partner[["Partner"]] schedule -->|"Triggers"| execution execution <-->|"Fetches data"| tsp execution -->|"Normalizes & stores"| database execution --> webhook webhook -->|"Delivers"| partner partner <-->|"Queries"| api api <--> database style schedule fill:#00bae6,stroke:none,color:#ffffff style execution fill:#0083bf,stroke:none,color:#ffffff style tsp fill:#28a745,stroke:none,color:#ffffff style database fill:#00354d,stroke:none,color:#ffffff style api fill:#0083bf,stroke:none,color:#ffffff style webhook fill:#00bae6,stroke:none,color:#ffffff style partner fill:#dc3545,stroke:none,color:#ffffff ``` *** 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](/api-reference/webhooks/overview) instead of relying on schedule polling our Telematics API. 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: 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. Catena automatically sets up schedules to fetch data from each connected TSP based on the share agreement scopes. Schedules trigger executions that fetch, normalize, and store telematics data from the TSP APIs. Query the Telematics API to retrieve data, or subscribe to webhooks for real-time notifications when data changes.