Fleet Management

OpenInsure's fleet management module covers the full lifecycle of commercial motor carrier underwriting data. It integrates with the FMCSA SAFER system for authority verification and CSA scoring, the NHTSA vPIC database for VIN decoding, and ELD telematics providers for real-time safety event ingestion.

Motor Carriers

Motor carriers are the central entity in trucking insurance. Each carrier record stores FMCSA authority data, operating status, fleet size, cargo types, and SAFER ratings.

Create a Motor Carrier

POST /v1/motor-carriers
Authorization: Bearer <token>
Content-Type: application/json

{
  "legalName": "Acme Freight LLC",
  "dbaName": "Acme Express",
  "usdotNumber": "1234567",
  "mcNumber": "MC-987654",
  "primaryState": "TX",
  "carrierType": "for_hire",
  "operatingAuthority": "interstate",
  "totalPowerUnits": 45,
  "totalDrivers": 52,
  "operations": ["property", "household_goods"],
  "cargoCarried": ["general_freight", "machinery"]
}

Carrier types: for_hire, private, exempt, owner_operator, lease_operator.

Operating authority: interstate, intrastate, dual, exempt, unknown.

List Motor Carriers

GET /v1/motor-carriers?page=1&limit=25

Returns a paginated list of carriers for the caller's organization, ordered by most recently created. The response includes meta.total and meta.pages for pagination controls.

Get Carrier Details

GET /v1/motor-carriers/:id

Returns the carrier record along with all associated intrastate permits.

FMCSA Integration

The platform queries the FMCSA SAFER API in real time to verify carrier authority, retrieve CSA safety scores, and detect chameleon companies (carriers that reincorporate to evade safety records).

DOT Number Lookup

POST /v1/motor-carriers/lookup
Content-Type: application/json

{
  "dotNumber": "1234567",
  "insuredName": "Acme Freight LLC"
}

Response:

{
  "dotNumber": "1234567",
  "carrierName": "ACME FREIGHT LLC",
  "authorityStatus": "authorized",
  "operatingStatus": "AUTHORIZED FOR PROPERTY",
  "operatingAuthority": "interstate",
  "csaScore": 24,
  "nameMismatch": false,
  "warning": null,
  "fmcsaStatus": "authorized"
}

When insuredName is provided, the system compares it against the FMCSA-registered name. A mismatch triggers a nameMismatch: true flag and a chameleon company warning. This is a critical underwriting red flag — it may indicate a carrier has reincorporated under a new name to shed a poor safety record.

RESTful DOT Lookup

GET /v1/motor-carriers/dot/1234567

Same data as the POST lookup but as a simple GET endpoint. Available to both underwriters and producers.

FMCSA Authority Status

Status	Description
authorized	Active operating authority
revoked	Authority revoked by FMCSA
inactive	Authority is inactive
pending	Application pending
out_of_service	Carrier placed out of service
none	No authority on file

SMS Safety Summary

GET /v1/motor-carriers/dot/1234567/sms-summary

Returns detailed FMCSA Safety Measurement System data including inspection history, crash records, OOS (out-of-service) rates, and violation breakdowns.

{
  "dotNumber": "1234567",
  "carrierName": "ACME FREIGHT LLC",
  "csaScore": 24,
  "totalInspections": 12,
  "totalViolations": 3,
  "totalOosOrders": 1,
  "totalCrashes": 0,
  "totalFatalities": 0,
  "oosRate": 8.33,
  "violationRate": 25.0,
  "inspections": [...],
  "crashes": [],
  "fetchedAt": "2026-03-24T14:00:00Z"
}

The API fetches inspection and crash data from the FMCSA SMS endpoints (/inspections and /crashes) in parallel, normalizes the response, and computes aggregate statistics.

Intrastate Permits

Carriers operating within a single state require intrastate permits. The platform tracks permits per carrier with compliance metadata.

Create a Permit

POST /v1/motor-carriers/:id/permits
Content-Type: application/json

{
  "state": "TX",
  "permitType": "intrastate_property",
  "permitNumber": "TX-INS-2026-1234",
  "requiresStateDotNumber": true,
  "stateDotNumber": "TX-DOT-5678",
  "annualFeeCents": 15000,
  "mileageTaxRequired": true,
  "fuelTaxRequired": true,
  "status": "active",
  "effectiveDate": "2026-01-01T00:00:00Z",
  "expirationDate": "2027-01-01T00:00:00Z"
}

Permit status values: pending, active, expired, revoked.

List Permits

GET /v1/motor-carriers/:id/permits

Returns up to 200 permits for the carrier, ordered by most recently created.

Vehicle Inventory

Vehicles are tracked on the fleet schedule and linked to both submissions and policies.

Create a Vehicle

POST /v1/vehicles
Content-Type: application/json

{
  "orgId": "550e8400-...",
  "submissionId": "7c9e6679-...",
  "vin": "1HGBH41JXMN109186",
  "year": 2024,
  "make": "Peterbilt",
  "model": "579",
  "vehicleType": "tractor",
  "gvwr": 80000,
  "cargoType": "general_freight",
  "lienholder": "Fleet Capital Finance"
}

Vehicle types: tractor, straight_truck, trailer, pickup.

VIN Duplicate Check

POST /v1/vehicles/vin-check
Content-Type: application/json

{
  "vin": "1HGBH41JXMN109186",
  "orgId": "550e8400-..."
}

Returns { "valid": true } if the VIN is unique within the organization, or { "valid": false, "error": "VIN ... is already registered" } if a duplicate exists. When updating a vehicle, pass vehicleId to exclude the current record from the check.

VIN Decoding

The platform uses the NHTSA vPIC (Vehicle Product Information Catalog) API for VIN decoding. Results are cached in Cloudflare KV to avoid redundant lookups.

Single VIN Decode

POST /v1/vehicles/decode
Content-Type: application/json

{ "vin": "1HGBH41JXMN109186" }

Returns year, make, model, engine details, plant info, safety equipment, and more from the NHTSA database.

Batch VIN Decode

POST /v1/vehicles/decode-batch
Content-Type: application/json

{
  "vins": [
    "1HGBH41JXMN109186",
    "3AKJHHDR5LSLU7890"
  ]
}

Decodes up to 50 VINs in a single call using the NHTSA DecodeVINValuesBatch endpoint. Cached results are returned from KV; only uncached VINs hit the upstream API.

Full VIN Lookup

POST /v1/vehicles/lookup
Content-Type: application/json

{ "vin": "1HGBH41JXMN109186" }

Combines VIN decode with NHTSA safety profile data (recalls, complaints, NCAP crash rating) in a single call. This is the recommended endpoint for underwriting workflows that need the complete vehicle picture.

Driver Records

Drivers are tracked with CDL class, license details, and years of experience.

Create a Driver

POST /v1/drivers
Content-Type: application/json

{
  "orgId": "550e8400-...",
  "submissionId": "7c9e6679-...",
  "firstName": "John",
  "lastName": "Rivera",
  "dob": "1985-06-15",
  "licenseNumber": "DL12345678",
  "licenseState": "TX",
  "cdlClass": "A",
  "yearsExperience": 12,
  "hiredDate": "2023-01-15"
}

CDL classes: A, B, C, none.

License Duplicate Check

POST /v1/drivers/license-check
Content-Type: application/json

{
  "license_number": "DL12345678",
  "license_state": "TX",
  "orgId": "550e8400-..."
}

Validates that the license number and state combination is unique within the organization.

MVR Pull

POST /v1/drivers/:id/mvr

Enqueues an asynchronous motor vehicle record (MVR) pull via Cloudflare Queues. The driver's mvrStatus is set to pending immediately, and the system dispatches a driver.mvr_requested event with the driver's license details. The MVR vendor integration processes the queue message and updates the driver record with violation history.

VIN Reconciliation Queue

The VIN reconciliation queue surfaces mismatches between policy vehicle schedules and real-world registrations detected by the monthly VIN sync cron job. Underwriters review and resolve each item.

Mismatch Types

Type	Description
unrated_exposure	Vehicle found in DOT records but not on the policy schedule
phantom_vehicle	Vehicle on the policy schedule but not found in DOT records

List Queue Items

GET /v1/vin-queue?orgId=550e8400-...&status=open&page=1&limit=25

Returns paginated queue items with joined policy data (policy number, insured name, DOT number). Items are sorted with open items first, then by detection date.

Resolve an Item

POST /v1/vin-queue/:id/resolve
Content-Type: application/json

{
  "action": "add_vehicle",
  "note": "Confirmed with producer — new tractor added to fleet last month",
  "resolvedBy": "usr_01J8..."
}

Resolution actions: add_vehicle (triggers an endorsement workflow event) or acknowledge_phantom (carrier sold/retired the unit). Resolving an unrated_exposure with add_vehicle emits a vin.endorsement_requested event to the queue for downstream endorsement processing.

Dismiss an Item

POST /v1/vin-queue/:id/dismiss
Content-Type: application/json

{
  "note": "Duplicate detection — same VIN flagged on prior review cycle",
  "dismissedBy": "usr_01J8..."
}

Dismissals require a minimum 10-character explanation for the audit trail.

Telematics Integration

OpenInsure ingests telematics data from ELD (Electronic Logging Device) providers and computes safety scores for fleet-level and per-driver risk assessment.

Supported ELD Providers

Provider	Integration Type
Samsara	Webhook
Motive	Webhook
Geotab	Webhook
KeepTruckin	Webhook
Omnitracs	Webhook

Register an ELD Connection

POST /v1/telematics/connections
Content-Type: application/json

{
  "orgId": "550e8400-...",
  "provider": "samsara",
  "apiKey": "samsara_api_...",
  "externalOrgId": "org_ext_123"
}

Safety Event Ingestion

POST /v1/telematics/events
Content-Type: application/json

{
  "orgId": "550e8400-...",
  "vehicleId": "veh_01J8...",
  "driverId": "drv_01J8...",
  "type": "hard_braking",
  "severity": "medium",
  "location": { "lat": 32.7767, "lng": -96.7970, "address": "I-35 near Dallas, TX" },
  "occurredAt": "2026-03-24T08:30:00Z"
}

Event types: hard_braking, harsh_turning, overspeed, crash_detected, lane_departure, tailgating, distracted_driving.

Severity levels: low, medium, high, critical.

Events can include a telematicsSnapshot (arbitrary JSON from the provider) and an r2VideoKey (link to dashcam footage stored in R2).

Trip Record Ingestion

POST /v1/telematics/trips
Content-Type: application/json

{
  "orgId": "550e8400-...",
  "vehicleId": "veh_01J8...",
  "driverId": "drv_01J8...",
  "startTime": "2026-03-24T06:00:00Z",
  "endTime": "2026-03-24T14:00:00Z",
  "milesDriven": 320,
  "stateBreakdown": { "TX": 200, "OK": 120 },
  "avgSpeed": 55,
  "maxSpeed": 72
}

The stateBreakdown field maps two-letter state codes to miles driven in each state, which feeds into state-level exposure calculations for rating.

Fleet Safety Score

GET /v1/telematics/fleet-score?orgId=550e8400-...&days=90

Computes an aggregate fleet safety score on a 0-100 scale based on weighted safety events per 10,000 miles driven over the specified period.

{
  "orgId": "550e8400-...",
  "periodDays": 90,
  "fleetScore": 82,
  "totalTrips": 1240,
  "totalMiles": 385000,
  "totalEvents": 47,
  "severityBreakdown": {
    "low": 28,
    "medium": 14,
    "high": 4,
    "critical": 1
  }
}

Scoring formula: Start at 100, subtract weighted events divided by miles (per 10k). Weights: critical = 15 points, high = 8, medium = 3, low = 1. A fleet with zero events scores 100.

Per-Driver Safety Scores

GET /v1/telematics/driver-scores?orgId=550e8400-...&days=90&limit=25

Returns individual driver safety scores ranked worst-first, using the same weighting formula as the fleet score but computed per driver. Each entry includes miles driven, trip count, and event breakdown by severity.