Insurance

Overview

This guide covers best practices for integrating Terminal into commercial auto insurance workflows. It’s organized into key implementation areas that map to the insurance policy lifecycle:

What This Guide Covers

This guide walks through the complete insurance workflow with Terminal. Depending on your use case, some sections may be optional:

Section	Description	When to Use
Pre-Bind / Underwriting	Connecting fleets and accessing historical data for risk assessment	If you’re evaluating telematics data before binding policies
Connection Lifecycle	Handling connection events, disconnections, and compliance monitoring	All implementations—critical for maintaining data access
Policy Binding Transition	Switching from manual to automatic sync when a policy is bound	If you start with underwriting and transition to ongoing monitoring
Data Ingestion	S3 delivery and API options for getting data into your systems	All implementations—choose based on volume and architecture
First Notice of Loss & Claims	Accessing crash reports, camera footage, and safety events for claims	If you handle claims investigation or FNOL workflows
Offboarding	Archiving connections when quotes are rejected or policies cancelled	All implementations—for clean lifecycle management

Pre-Bind / Underwriting

The first step in processing telematics data for underwriting is obtaining consent from the fleet. Terminal’s Link component handles the consent flow and authorization with the telematics provider.

Connecting Fleets with Terminal Link

Use Terminal Link to guide fleets through connecting their telematics provider. During underwriting, use Manual sync mode to control costs—you only sync data when needed for risk assessment.

View implementation options

Hosted Flow
React SDK
JavaScript SDK

The hosted flow is a URL you can send directly to fleets via email, SMS, or any messaging channel:

https://link.withterminal.com/?syncMode=manual&backfill_days=90&tags=app-7689&key={PUBLISHABLE_KEY}

The React SDK can be embedded in your digital onboarding flow if you have one and use React.

const terminal = useTerminalLink({
  publishableKey: process.env.REACT_APP_TERMINAL_PUBLISHABLE_KEY,
  onSuccess: exchangeToken,
  params: {
    syncMode: 'manual',
    backfill: { days: 90 }, // Your backfill period
    tags: ['app-7689'], // Your application/submission number
  },
});

The JavaScript SDK can be embedded in your digital onboarding flow if you have one.

TerminalLink.initialize({
  publishableKey: process.env.TERMINAL_PUBLISHABLE_KEY,
  onSuccess: (result) => exchangePublicToken(result.publicToken),
  params: {
    syncMode: 'manual',
    backfill: { days: 90 }, // Your backfill period
    tags: ['app-7689'], // Your application/submission number
  },
}).open();

Use tags to associate connections with your internal identifiers like application numbers (app-7689) or policy numbers (policy-1234).

Configuring Historical Data for Underwriting

To assess risk, you’ll typically need historical telematics data. The backfill period determines how much historical data Terminal retrieves from the provider. You can configure backfill in two ways:

Per-link: Set backfill_days or backfill.days when creating the connection (shown above)
Application-level default: Configure a default backfill period in your Terminal dashboard settings

Historical data availability varies by provider. See Supported Providers for details on history available for backfill.

For details on how to access backfilled data once the connection is established, see the Data Ingestion section below.

Connection Lifecycle

Managing connection events is critical for insurance workflows. Use webhooks to automate responses to connection state changes.

Handling Connection Completion

When a fleet successfully connects their telematics provider, Terminal sends a connection.completed webhook. Use this to:

Record that the fleet has connected telematics for the quote
Update your internal systems with the connection details
Send a confirmation to the fleet

View code

// Webhook handler for connection.completed
app.post('/webhooks/terminal', async (req, res) => {
  const event = req.body;

  if (event.type === 'connection.completed') {
    const { connection } = event.detail;

    // Find application number from tags (e.g., 'app-7689')
    const appTag = connection.tags?.find((t) => t.startsWith('app-'));
    const applicationNumber = appTag?.replace('app-', '');

    // Record that fleet has connected telematics
    await recordTelematicsConnected({
      applicationNumber,
      connectionId: connection.id,
      provider: connection.provider.name,
      connectedAt: event.timestamp,
    });

    // Notify your team or the fleet
    await notifyQuoteTeam({
      applicationNumber,
      message: 'Fleet has connected telematics - ready for underwriting',
    });

    // Optionally send confirmation to the fleet
    await sendFleetConfirmation({
      email: getFleetEmail(applicationNumber),
      subject: 'Telematics Connected Successfully',
      message:
        'Your telematics data is now connected for your insurance quote.',
    });
  }

  res.status(200).send('OK');
});

Handling Disconnections

When a connection becomes disconnected (credentials expire, provider access revoked, etc.), Terminal sends a connection.disconnected webhook. For active policies, this creates a compliance gap—notify the fleet promptly to reconnect.

View code

if (event.type === 'connection.disconnected') {
  const { connection } = event.detail;

  // Check if this is an active policy (automatic sync = post-bind)
  if (connection.syncMode === 'automatic') {
    // Find policy number from tags (e.g., 'policy-1234')
    const policyTag = connection.tags?.find((t) => t.startsWith('policy-'));
    const policyNumber = policyTag?.replace('policy-', '');

    // Send urgent notification to insured with reconnection link
    await notifyInsured({
      email: getInsuredEmail(policyNumber),
      subject: 'Action Required: Reconnect Your Telematics',
      body: 'Your telematics connection has been disconnected. Please reconnect to stay compliant with your policy.',
      reconnectUrl: connection.linkUrl,
      priority: 'high',
    });

    // Flag the policy for compliance review
    await flagPolicyForReview({
      policyNumber,
      reason: 'telematics_disconnected',
    });
  }
}

Key Webhook Events for Insurance

Event	Trigger	Recommended Action
`connection.completed`	Fleet completes telematics connection	Record connection, notify team/fleet
`connection.disconnected`	Connection credentials become invalid	Notify insured to reconnect for compliance
`connection.reconnected`	Previously disconnected connection restored	Resume monitoring, clear compliance flags

See the Webhooks Guide for setup instructions and the Webhook Events Reference for detailed payload schemas.

Policy Binding Transition

When a quote is accepted and the policy is bound, transition the connection from Manual to Automatic sync mode. This enables continuous data synchronization for ongoing risk monitoring and claims support.

View code

curl --request PATCH \
  --url https://api.withterminal.com/tsp/v1/connections/current \
  --header 'Authorization: Bearer {SECRET_KEY}' \
  --header 'Connection-Token: {CONNECTION_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "syncMode": "automatic",
    "tags": ["policy-1234"]
  }'

This API call:

Switches sync mode from manual to automatic for continuous data updates
Adds a policy tag to the connection for future reference (the application tag remains)

Example: Policy Binding Workflow

View code

async function bindPolicy(applicationNumber: string, policyNumber: string) {
  // Find the connection by application tag
  const connections = await fetch(
    `https://api.withterminal.com/tsp/v1/connections?tag=app-${applicationNumber}`,
    { headers: { Authorization: `Bearer ${SECRET_KEY}` } },
  );

  const connection = connections.data[0];

  // Transition connection for post-bind monitoring
  await fetch('https://api.withterminal.com/tsp/v1/connections/current', {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${SECRET_KEY}`,
      'Connection-Token': connection.token,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      syncMode: 'automatic',
      tags: [...connection.tags, `policy-${policyNumber}`], // Add policy tag
    }),
  });

  // Record the transition in your system
  await recordPolicyBound({
    applicationNumber,
    policyNumber,
    connectionId: connection.id,
    boundAt: new Date().toISOString(),
  });
}

Post-Bind Monitoring

With automatic sync enabled, Terminal continuously updates connection data. Use this for: Ongoing Risk Monitoring

Monitor safety events for policy risk assessment
Track driver behavior trends over the policy period
Identify high-risk vehicles or drivers

Claims Support

Access historical vehicle locations for incident verification
Review driver HOS logs around claim dates
Retrieve safety event footage via camera media endpoints

Data Ingestion

Terminal provides two methods for ingesting telematics data into your systems. Both support initial backfills (historical data after connection) and incremental updates (ongoing data).

Option 1: Data Delivery (Recommended for Insurance)

For insurance use cases, we recommend using S3 Data Delivery. This approach:

Simplifies pipeline architecture: Data arrives in your S3 bucket automatically
Handles scale efficiently: Batch deliveries are more efficient than individual API calls
Provides complete data ownership: All data is stored in your AWS account
Supports both backfills and incremental updates: Automatic triggers for both scenarios

How Data Delivery Works

Initial Backfill: When a connection completes its first sync, Terminal automatically triggers a delivery of all historical data (based on your configured backfill period) to your S3 bucket. Incremental Updates: On your configured schedule (hourly, daily, etc.), Terminal delivers all new and updated data across your connections.

Handling Delivery Events

Listen for delivery webhooks to trigger your data processing pipeline:

View code

if (event.type === 'delivery.completed') {
  const { delivery, destination } = event.detail;

  // Trigger ETL pipeline to process new S3 objects
  await triggerETLPipeline({
    deliveryId: delivery.id,
    connectionIds: delivery.connectionIds,
    destinationId: destination.id,
    // Data is already in your S3 bucket
  });
}

Configure your S3 destination with daily scheduled deliveries for post-bind monitoring. The initial backfill happens automatically when connections complete their first sync.

Option 2: API

For more control over data access or lower-volume use cases, query the API directly. The API approach gives you flexibility to fetch exactly the data you need, when you need it. Backfill Data: After a connection completes its first sync, query endpoints like /vehicles, /safety/events, and /trips with date filters to retrieve historical data for underwriting risk assessment. Incremental Updates: For ongoing monitoring, use the modifiedAfter query parameter to fetch only new or updated records since your last sync. This is efficient for keeping your systems in sync without re-fetching all data. For complete implementation details, code examples, and best practices for API-based data syncing, see the How to Sync Data guide.

First Notice of Loss & Claims Investigation

When a claim is filed, Terminal provides access to critical data for First Notice of Loss (FNOL) and claims investigation workflows. This includes crash detection, camera footage, and detailed safety event data.

Safety Events & Crash Reports

Terminal’s Safety Events capture incidents detected by telematics devices, including harsh braking, collisions, speeding, and other driver behavior events. These events are invaluable for claims investigation. For a deeper dive on crash detection capabilities and provider support, see Crash Reports. Key capabilities:

Crash detection: Many telematics providers detect collisions and report them as safety events with severity indicators
Event details: Access timestamp, location, speed, and g-force data for each event
Driver context: Link events to specific drivers and vehicles

Accessing safety events via API:

View code

// Get safety events for a specific vehicle around a claim date
const claimDate = '2024-03-15';
const startDate = new Date(claimDate);
startDate.setDate(startDate.getDate() - 1); // Day before
const endDate = new Date(claimDate);
endDate.setDate(endDate.getDate() + 1); // Day after

const safetyEvents = await fetch(
  `https://api.withterminal.com/tsp/v1/safety/events?vehicleIds=${vehicleId}&startedAfter=${startDate.toISOString()}&startedBefore=${endDate.toISOString()}`,
  {
    headers: {
      Authorization: `Bearer ${SECRET_KEY}`,
      'Connection-Token': connectionToken,
    },
  },
);

// Filter for crash events
const crashEvents = safetyEvents.data.filter((event) =>
  ['crash', 'near_crash'].includes(event.type),
);

Camera Media

For connections with camera-equipped telematics devices, Terminal provides access to video footage and images captured during safety events. This is critical for accident reconstruction and liability determination. Key capabilities:

Event footage: Video clips captured before, during, and after safety events
Multiple camera views: Access road-facing, driver-facing, and cabin camera footage when available
Timestamp correlation: Camera media is linked to specific safety events for easy retrieval

Accessing camera media via API:

View code

// Get camera media for a specific safety event
const cameraMedia = await fetch(
  `https://api.withterminal.com/tsp/v1/safety/events/${safetyEventId}/camera-media`,
  {
    headers: {
      Authorization: `Bearer ${SECRET_KEY}`,
      'Connection-Token': connectionToken,
    },
  },
);

// Access media URLs for review
const media = await cameraMedia.json();

if (media.frontFacing?.videoUrl) {
  console.log(`Front-facing camera: ${media.frontFacing.videoUrl}`);
}

if (media.rearFacing?.videoUrl) {
  console.log(`Rear-facing camera: ${media.rearFacing.videoUrl}`);
}

Camera media availability depends on the telematics provider and device capabilities. See Camera Media for details on the data model.

Safety Event Webhooks

Subscribe to safety_event.added webhooks to receive real-time notifications when new safety events are recorded. This enables proactive claims handling—you can be notified of potential incidents before a claim is even filed.

View code

// Webhook handler for safety_event.added
if (event.type === 'safety_event.added') {
  const { safetyEvent, connection } = event.detail;

  // Check if this is a severe event that may indicate a claim
  const severeTypes = ['crash', 'near_crash'];
  const isSevere = severeTypes.includes(safetyEvent.type);

  if (isSevere) {
    // Find policy number from tags
    const policyTag = connection.tags?.find((t) => t.startsWith('policy-'));
    const policyNumber = policyTag?.replace('policy-', '');

    // Alert claims team of potential incident
    await alertClaimsTeam({
      policyNumber,
      eventType: safetyEvent.type,
      timestamp: safetyEvent.startedAt,
      vehicle: safetyEvent.vehicle,
      location: safetyEvent.startLocation,
      severity: 'high',
    });
  }
}

Dashboard Access

The Terminal dashboard provides a visual interface for reviewing safety events and camera media without writing code. Claims adjusters can:

Browse safety events: Filter by date, vehicle, driver, or event type
Watch camera footage: Play back video clips directly in the browser
Export data: Download event details and media for claims files
View event locations: See where incidents occurred on a map

This is particularly useful for claims teams who need quick access to telematics data without API integration.

Offboarding

When a quote is rejected or an account is cancelled, archive the connection to stop data syncing and clean up resources.

Archiving Connections

Mark a connection as archived when it’s no longer needed:

View code

curl --request PATCH \
  --url https://api.withterminal.com/tsp/v1/connections/current \
  --header 'Authorization: Bearer {SECRET_KEY}' \
  --header 'Connection-Token: {CONNECTION_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "archived"
  }'

Example: Quote Rejection Workflow

View code

async function handleQuoteRejected(applicationNumber: string) {
  // Find the connection by application tag
  const connections = await fetch(
    `https://api.withterminal.com/tsp/v1/connections?tag=app-${applicationNumber}`,
    { headers: { Authorization: `Bearer ${SECRET_KEY}` } },
  );

  const connection = connections.data[0];

  if (connection) {
    // Archive the connection
    await fetch('https://api.withterminal.com/tsp/v1/connections/current', {
      method: 'PATCH',
      headers: {
        Authorization: `Bearer ${SECRET_KEY}`,
        'Connection-Token': connection.token,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        status: 'archived',
      }),
    });

    // Record the archival in your system
    await recordConnectionArchived({
      applicationNumber,
      connectionId: connection.id,
      reason: 'quote_rejected',
      archivedAt: new Date().toISOString(),
    });
  }
}

Example: Policy Cancellation Workflow

View code

async function handlePolicyCancelled(policyNumber: string) {
  // Find the connection by policy tag
  const connections = await fetch(
    `https://api.withterminal.com/tsp/v1/connections?tag=policy-${policyNumber}`,
    { headers: { Authorization: `Bearer ${SECRET_KEY}` } },
  );

  const connection = connections.data[0];

  if (connection) {
    // Archive the connection
    await fetch('https://api.withterminal.com/tsp/v1/connections/current', {
      method: 'PATCH',
      headers: {
        Authorization: `Bearer ${SECRET_KEY}`,
        'Connection-Token': connection.token,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        status: 'archived',
      }),
    });

    // Record the archival in your system
    await recordConnectionArchived({
      policyNumber,
      connectionId: connection.id,
      reason: 'policy_cancelled',
      archivedAt: new Date().toISOString(),
    });
  }
}

Archiving a connection stops all data syncing and deliveries. The historical data remains available in your systems for reference but no new data will be collected.

Complete Webhook Reference

Here’s a summary of all webhook events relevant to insurance workflows:

Event	Trigger	Recommended Action
`connection.completed`	Fleet completes telematics connection	Record connection, notify team/fleet
`connection.disconnected`	Connection credentials become invalid	Notify insured with reconnection link
`connection.reconnected`	Previously disconnected connection restored	Resume data monitoring
`sync.completed`	Data sync finishes successfully	Trigger data ingestion (API approach)
`sync.failed`	Data sync encounters an error	Alert operations team
`delivery.completed`	S3 data delivery completes	Trigger ETL pipeline
`delivery.failed`	S3 delivery fails	Alert operations team
`vehicle.added`	New vehicle detected in fleet	Update or compare to policy
`vehicle.removed`	Vehicle removed from fleet	Update or compare to policy
`driver.added`	New driver detected in fleet	Update or compare to policy
`driver.removed`	Driver removed from fleet	Update or compare to policy
`safety_event.added`	New safety event recorded	Update risk assessment

Full Sequence Diagram

Next Steps

Set up webhooks for event-driven automation
Configure S3 delivery for automated data replication
Learn how to sync data for API-based ingestion patterns
Explore the API reference to query telematics data
Review custom identifiers for connection organization

About Us

Implementation Guides

Use Case Guides

Data Destinations

Terminal Platform

Advanced

Overview

What This Guide Covers

Pre-Bind / Underwriting

Connecting Fleets with Terminal Link

Configuring Historical Data for Underwriting

Connection Lifecycle

Handling Connection Completion

Handling Disconnections

Key Webhook Events for Insurance

Policy Binding Transition

Post-Bind Monitoring

Data Ingestion

Option 1: Data Delivery (Recommended for Insurance)

How Data Delivery Works

Handling Delivery Events

Option 2: API

First Notice of Loss & Claims Investigation

Safety Events & Crash Reports

Camera Media

Safety Event Webhooks

Dashboard Access

Offboarding

Archiving Connections

Complete Webhook Reference

Full Sequence Diagram

Next Steps

About Us

Implementation Guides

Use Case Guides

Data Destinations

Terminal Platform

Advanced

​Overview

​What This Guide Covers

​Pre-Bind / Underwriting

​Connecting Fleets with Terminal Link

​Configuring Historical Data for Underwriting

​Connection Lifecycle

​Handling Connection Completion

​Handling Disconnections

​Key Webhook Events for Insurance

​Policy Binding Transition

​Post-Bind Monitoring

​Data Ingestion

​Option 1: Data Delivery (Recommended for Insurance)

​How Data Delivery Works

​Handling Delivery Events

​Option 2: API

​First Notice of Loss & Claims Investigation

​Safety Events & Crash Reports

​Camera Media

​Safety Event Webhooks

​Dashboard Access

​Offboarding

​Archiving Connections

​Complete Webhook Reference

​Full Sequence Diagram

​Next Steps

Overview

What This Guide Covers

Pre-Bind / Underwriting

Connecting Fleets with Terminal Link

Configuring Historical Data for Underwriting

Connection Lifecycle

Handling Connection Completion

Handling Disconnections

Key Webhook Events for Insurance

Policy Binding Transition

Post-Bind Monitoring

Data Ingestion

Option 1: Data Delivery (Recommended for Insurance)

How Data Delivery Works

Handling Delivery Events

Option 2: API

First Notice of Loss & Claims Investigation

Safety Events & Crash Reports

Camera Media

Safety Event Webhooks

Dashboard Access

Offboarding

Archiving Connections

Complete Webhook Reference

Full Sequence Diagram

Next Steps