Carrier Gateway

The @openinsure/carrier package is the carrier integration layer. It handles appetite evaluation, concurrent multi-carrier submission routing, best-quote selection, and bordereaux SFTP export. It ships with a built-in database of 6 pre-configured carriers.

Carrier Profiles

Every carrier is described by a CarrierProfile:

interface CarrierProfile {
  id: string;
  name: string;
  naic: string;
  type: 'admitted' | 'surplus-lines' | 'reinsurer' | 'captive' | 'lloyds';
  amBestRating: AMBestRating; // 'A++' | 'A+' | 'A' | 'A-' | 'B++' | ...
  appetite: LineOfBusiness[]; // LOBs this carrier writes
  admittedStates: string[]; // 2-char state codes ('ALL' for nationwide)
  maxLimitPerRisk: number; // in dollars
  maxAggregateLimit: number;
  minPremium: number;
  requiresMGA: boolean; // MGA sponsorship required
}

Built-in Carrier Database

Six carriers are pre-configured in CARRIER_DB:

Carrier	Type	AM Best	Key LOBs	Max Limit
Lloyd’s Syndicate 2623	Surplus-lines	A	Cyber, Prof Liability, D&O, Crime	$50M
Travelers Commercial	Admitted (all US)	A++	GL, Property, Auto, WC, Umbrella	$25M
Beazley Specialty	Surplus-lines	A	Cyber, Prof Liability, Crime, EPL, D&O	$25M
Zurich North America	Admitted (most US)	A+	GL, WC, Auto, Prof Liability, D&O	$50M
Markel Specialty	Surplus-lines	A	GL, Prof Liability, D&O, Crime, Excess, Marine	$100M
Hiscox USA	Surplus-lines	A	Prof Liability, Cyber, D&O, EPL, Crime	$10M

Appetite Checking

`checkCarrierAppetite(carrier, input)`

Evaluates whether a carrier will write a given risk:

import { checkCarrierAppetite, CARRIER_DB } from '@openinsure/carrier';

const result = checkCarrierAppetite(CARRIER_DB[0], {
  lineOfBusiness: 'Cyber',
  state: 'CA',
  requestedLimit: 5_000_000,
  premium: 15_000,
});

// Returns: AppetiteCheckResult
// {
//   eligible: true,
//   score: 87,
//   reasons: [],
//   requiredEndorsements: ['CA surplus-lines stamp required'],
// }

Scoring formula:

60% weight: AM Best rating tier (A++ = 100, A+ = 95, A = 90, A- = 85, B++ = 75, …)
40% weight: Limit headroom (requestedLimit / maxLimitPerRisk, capped at 1.0)

A carrier scores 0 and is marked ineligible if:

LOB is not in carrier.appetite
State is not in carrier.admittedStates (and carrier is admitted-type)
requestedLimit > carrier.maxLimitPerRisk
premium < carrier.minPremium

`rankCarriers(carriers, input)`

Filters eligible carriers and sorts by appetite score descending:

const ranked = rankCarriers(Object.values(CARRIER_DB), input);
// [{ carrier, score, eligible, reasons }, ...]  — highest score first

`findCarrier(idOrNaic)`

Lookup a carrier by internal ID or NAIC code:

const carrier = findCarrier('26298'); // NAIC code
const carrier = findCarrier('travelers-commercial'); // internal ID

Multi-Carrier Gateway

The CarrierGateway routes submissions to one or more carriers concurrently and selects the best quote.

Single Carrier Submission

import { createCarrierGateway } from '@openinsure/carrier';

const gateway = createCarrierGateway();
const response = await gateway.submitToCarrier('travelers-commercial', {
  carrierId: 'travelers-commercial',
  submissionId: 'sub_abc123',
  lob: 'Commercial GL',
  state: 'NC',
  effectiveDate: '2026-07-01',
  expirationDate: '2027-07-01',
  insuredName: 'Acme Hardware LLC',
  requestedLimit: 1_000_000,
  deductible: 5_000,
  naics: '444130',
  premium: 4_800,
});

// response.status: 'quoted' | 'pending' | 'declined' | 'referred' | 'error'
// response.quotedPremium: 4650

Multi-Carrier Submission

Submit to multiple carriers concurrently with Promise.allSettled — one carrier timeout or error does not block the others:

const result = await gateway.submitToMultiple(
  ['travelers-commercial', 'zurich-na', 'markel-specialty'],
  request
);

// result.bestQuote — lowest premium quoted response
// result.responses — all carrier responses
// result.errors — any carriers that errored

Auto-Eligible Routing

Submit to all carriers that pass appetite checking automatically:

const result = await gateway.submitToEligible(request, CARRIER_DB);
// Runs checkCarrierAppetite() for each carrier, submits to eligible ones only

Response Status Values

Status	Description
`pending`	Submission received, awaiting underwriter review
`quoted`	Premium quoted — `quotedPremium` is populated
`declined`	Declined — `declineReason` is populated
`referred`	Referred to senior underwriter
`error`	Carrier API error or timeout

Bordereaux SFTP Export

`generateBordereauxCSV(records)`

Generates a pipe-delimited CSV for bordereaux submission to carriers or reinsurers:

import { generateBordereauxCSV } from '@openinsure/carrier';

const csv = generateBordereauxCSV([
  {
    policyNumber: 'GL-2026-00451',
    insuredName: 'Acme Hardware LLC',
    effectiveDate: '2026-01-01',
    expirationDate: '2027-01-01',
    grossPremium: 12_500,
    commissionAmount: 1_875,
    netPremium: 10_625,
    state: 'NC',
    lob: 'GL',
    transactionType: 'New Business',
  },
]);

`transmitBordereauxSftp(csvContent, fileName, config)`

Transmits a bordereaux CSV to a carrier’s SFTP endpoint:

const result = await transmitBordereauxSftp(csv, 'bordereaux-2026-03.csv', {
  host: 'sftp.carrier.com',
  port: 22,
  username: 'mga_user',
  privateKey: env.CARRIER_SFTP_KEY,
});

// { success: true, bytesTransferred: 4096, path: '/upload/bordereaux/bordereaux-2026-03.csv' }

Testing with Mock Adapters

The gateway ships mock adapters for testing without real carrier APIs:

import { createCarrierGateway, createMockAdapter } from '@openinsure/carrier';

const gateway = createCarrierGateway();
gateway.registerAdapter(
  'travelers-commercial',
  createMockAdapter('travelers-commercial', 'Travelers', { behavior: 'autoQuote', latencyMs: 200 })
);

// Behaviors: 'autoQuote' | 'declineAll' | 'refer'

All API integration tests use mock adapters — no real carrier API calls in CI.

MGA Overview

Delegated authority, program management, and bordereaux.

Reinsurance

Treaty cession, XOL, and aggregate calculations.