> ## 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.

# v2.0.1 - Documentation & Examples Enhancement

> Added comprehensive examples and improved documentation clarity

**Released 11th December 2025**

This patch release focuses on improving API documentation with comprehensive examples for all major schemas and clarifying field descriptions. No functional API behavior has changed.

<Check>
  **Documentation Update:** This is a non-breaking release that enhances developer experience through better examples and clearer descriptions.
</Check>

## Schema Examples Added

<AccordionGroup>
  <Accordion title="Fleet Schema Examples" icon="truck">
    Added realistic example data for `FleetRead` schema showing all available fields:

    ```json theme={null}
    {
      "id": "98765432-10fe-dcba-9876-543210fedcba",
      "name": "Swift Transport LLC",
      "display_name": "Swift Transport",
      "dba_name": "Swift Logistics",
      "legal_name": "Swift Transport LLC",
      "description": "Regional freight carrier specializing in temperature-controlled transport",
      "address": "1234 Industrial Pkwy",
      "city": "San Francisco",
      "province": "California",
      "postal_code": "94107",
      "country_code": "USA",
      "registered_email": "operations@swifttransport.com",
      "registered_phone": "+14155551234",
      "registered_fax": "+14155551235",
      "regulatory_id": "1234567",
      "regulatory_id_type": "DOT",
      "regulatory_id_status": "ACTIVE",
      "regulatory_id_date": "2020-03-15",
      "websites": ["https://swifttransport.com", "https://swiftlogistics.com"],
      "created_at": "2025-12-10T08:15:00Z",
      "updated_at": "2025-12-11T14:30:00Z"
    }
    ```

    <Tip>
      Use these examples as templates when testing fleet data integration.
    </Tip>
  </Accordion>

  <Accordion title="Invitation Schema Examples" icon="envelope">
    Added comprehensive examples for invitation workflows:

    **InvitationCreate:**

    ```json theme={null}
    {
      "partner_provided_fleet_name": "Swift Transport LLC",
      "partner_provided_fleet_email": "operations@swifttransport.com",
      "partner_provided_fleet_phone": "+14155551234",
      "partner_provided_fleet_regulatory_id": "1234567",
      "partner_provided_fleet_regulatory_id_type": "DOT",
      "partner_provided_fleet_country_code": "USA",
      "partner_provided_fleet_website": "https://swifttransport.com",
      "fleet_ref": "FLEET-12345",
      "expires_in_hours": 24,
      "limit_tsps": ["samsara", "geotab"],
      "callback_url": "https://api.example.com/webhooks/catena",
      "success_redirect_url": "https://app.example.com/onboarding/success",
      "failure_redirect_url": "https://app.example.com/onboarding/failure"
    }
    ```

    **InvitationRead:**

    ```json theme={null}
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "partner_id": "11223344-5566-7788-99aa-bbccddeeff00",
      "partner_slug": "acme-logistics",
      "fleet_id": "98765432-10fe-dcba-9876-543210fedcba",
      "fleet_ref": "FLEET-12345",
      "partner_provided_fleet_name": "Swift Transport LLC",
      "status": "ACCEPTED",
      "magic_link": "https://connect.catena.eu/?invite=01234567-89ab-cdef-0123-456789abcdef",
      "expires_in_hours": 24,
      "expires_at": "2025-12-12T10:30:00Z",
      "created_at": "2025-12-11T10:30:00Z",
      "accepted_at": "2025-12-11T14:22:00Z",
      "limit_tsps": ["samsara", "geotab"],
      "callback_url": "https://api.example.com/webhooks/catena",
      "success_redirect_url": "https://app.example.com/onboarding/success",
      "failure_redirect_url": "https://app.example.com/onboarding/failure",
      "pre_registration_access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "pre_registration_refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
    ```

    **InvitationAccept:**

    ```json theme={null}
    {
      "fleet_name": "Swift Transport LLC",
      "fleet_email": "operations@swifttransport.com",
      "fleet_phone": "+14155551234",
      "fleet_regulatory_id": "1234567",
      "fleet_regulatory_id_type": "DOT",
      "fleet_country_code": "USA",
      "fleet_website": "https://swifttransport.com"
    }
    ```
  </Accordion>

  <Accordion title="Share Agreement Examples" icon="handshake">
    Added examples for share agreement schemas:

    **ShareAgreementRead:**

    ```json theme={null}
    {
      "id": "22334455-6677-8899-aabb-ccddeeff0011",
      "partner_id": "11223344-5566-7788-99aa-bbccddeeff00",
      "fleet_id": "98765432-10fe-dcba-9876-543210fedcba",
      "fleet_ref": "FLEET-12345",
      "invitation_id": "01234567-89ab-cdef-0123-456789abcdef",
      "status": "active",
      "effective_date": "2025-12-11T14:22:00Z",
      "scopes": {
        "user": "read",
        "vehicle": "read-write",
        "vehicle-location": "read-write",
        "hos-events": "read"
      }
    }
    ```

    **ShareAgreementUpdate:**

    ```json theme={null}
    {
      "status": "cancelled",
      "fleet_ref": "FLEET-12345",
      "effective_date": "2025-12-15T00:00:00Z",
      "expiration_date": "2026-12-15T00:00:00Z"
    }
    ```
  </Accordion>

  <Accordion title="Partner & TSP Examples" icon="building">
    Added examples for partner and TSP schemas:

    **PartnerRead:**

    ```json theme={null}
    {
      "id": "11223344-5566-7788-99aa-bbccddeeff00",
      "name": "Acme Logistics",
      "slug": "acme-logistics",
      "description": "AI-powered route optimization and fleet intelligence platform",
      "categories": [
        "Operations & Dispatch",
        "Visibility & Logistics",
        "Data & Connectivity"
      ],
      "websites": ["https://acmelogistics.com", "https://acme.io"],
      "is_sandbox": false,
      "created_at": "2024-06-01T10:00:00Z",
      "updated_at": "2025-12-01T15:30:00Z"
    }
    ```

    **TspRead:**

    ```json theme={null}
    {
      "id": "11223344-5566-7788-99aa-bbccddeeff00",
      "name": "Samsara",
      "slug": "samsara",
      "source_name": "samsara",
      "description": "Connected operations platform for fleet management and industrial operations",
      "conn_type": "oauth2",
      "status": "active",
      "websites": ["https://www.samsara.com"],
      "is_sandbox": false,
      "created_at": "2024-01-15T09:00:00Z",
      "updated_at": "2025-11-20T16:45:00Z"
    }
    ```
  </Accordion>
</AccordionGroup>

## Documentation Improvements

<AccordionGroup>
  <Accordion title="Invitation Expiration Extended" icon="clock">
    **Updated Field:** `InvitationCreate.expires_in_hours`

    **Before:**

    * Maximum: 168 hours (7 days)
    * Description: "How long the invitation link remains valid (1-168 hours)"

    **After:**

    * Maximum: 672 hours (28 days)
    * Description: "How long the invitation link remains valid (1-672 hours). Default is 24 hours. *Consider longer durations for email campaigns.*"

    <Tip>
      Use longer expiration times (up to 28 days) for email campaigns or when fleets need more time to complete onboarding.
    </Tip>
  </Accordion>

  <Accordion title="Share Agreement Status Clarification" icon="circle-info">
    **Updated Field:** `ShareAgreementUpdate.status`

    **Before:**

    * Description: "Current state: ACTIVE, PAUSED, CANCELLED, EXPIRED"

    **After:**

    * Description: "Current state: active (data access enabled), paused (temporarily disabled), cancelled (permanently ended), expired (past expiration\_date)"

    Clarified that status values use lowercase and added descriptions for each state.
  </Accordion>

  <Accordion title="Callback URL Documentation" icon="webhook">
    **Added Field:** `InvitationRead.callback_url`

    Previously undocumented in the read schema, now explicitly shown:

    * Type: URL (HTTPS required)
    * Description: "Your webhook endpoint to receive real-time notifications for invitation acceptance, share agreement creation, and connection status updates"

    <Warning>
      Callback URLs must use HTTPS for security. HTTP endpoints will be rejected.
    </Warning>
  </Accordion>
</AccordionGroup>

## Summary

This release enhances the developer experience by:

* Adding realistic examples to 7 major schemas
* Extending invitation expiration to 28 days
* Clarifying share agreement status values
* Documenting callback URL field

**No code changes required** - all updates are documentation-only improvements.

***

## Need Help?

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference/telematics-api">
    View complete endpoint documentation with current API structure
  </Card>

  <Card title="Contact Support" icon="life-ring" href="mailto:support@catenaclearing.io">
    Questions about migrating your integration? Our team is here to help
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.