A production carrier integration isn't one system. It's five, stacked.

Most teams that set out to build carrier connectivity in-house picture the integration as one layer - the API client. That's the layer that shows up in the architecture diagram on the kickoff deck. It's not the layer that wakes someone up at 3am. The real shape is five layers, each absorbing a different class of failure, each capable of degrading silently for weeks before anything obvious moves on the dashboard.

The reason in-house builds fall over in production isn't that any single one of these layers is hard to build. It's that the thinnest layer in your stack defines the failure mode you'll spend the next year debugging.

Layer 1 — Authentication and session management

What this layer absorbs: every way a carrier proves you're allowed to talk to them.

Across our portfolio we've integrated against OAuth2, custom token exchanges, mutual TLS, IP allowlists, portal-cookie hybrids, and broker-code provisioning models that range from "self-served via API" to "manual carrier-side approval per agency." The variance isn't the cost. The lack of warning when one of those variances applies to your next integration is the cost.

Failures here don't look like outages. They look like a quote that mysteriously doesn't quote. A few weeks back our auth adapter on a Nationwide BOP submission built the request headers but didn't attach the bearer token. Nationwide did the right thing — a clean 401 with a descriptive body. Layer 1 is almost always the problem, until it isn't.

Layer 2 — Request transformation

What this layer absorbs: turning one canonical application into thirty different carrier dialects.

We covered this in depth in Part 4 - the canonical schema, NAICS↔NCCI mappings, payroll conventions, decline taxonomies, the recurring discovery that one carrier's "restaurant" is another carrier's hard decline. The mapper is one layer of the stack, not the whole stack. But it touches every layer above and below it. If the mapper drops a field, Layer 1 sends a request the carrier won't accept, Layer 3 retries it, Layer 4 normalizes the rejection into the wrong error class, Layer 5 audits the misfire. One thin layer compounds through four others.

Layer 3 — Transport, retry, and idempotency

What this layer absorbs: the network being a network, and the carrier's API being a moving target.

This is where the post earns its title. Idempotency is the whole game. The transport layer has to assume that any single request can be sent more than once — by retry logic on our side, by an HTTP client doing automatic redirects, by an operator replaying a failed request, by a webhook redelivery on the carrier side. The question isn't whether a retry will happen. It's whether your retry layer understands what it's actually retrying.

A few months back we shipped a bind through Coterie. Coterie runs payment through Stripe, which means the integration pulls a single-use Stripe token before calling bind. The bind call timed out. Our retry layer did what we'd built it to do — fired a second attempt with the same payload. Stripe, doing what it's built to do, returned token_already_used. Our retry layer had no idea what a single-use token was; it saw a 4xx and surfaced it.

The fix took twenty minutes. The root cause was older than the bug. Our retry layer was idempotent in the way we meant it — same payload, same outcome — not in the way Stripe meant it, which is that some fields in that payload expire after a single use. Carriers that ship modern payment APIs are giving you a gift here. They force you to build a retry layer that understands which fields in a request are replayable and which aren't. If your stack treats every retry as "send the same bytes again," you'll find this bug. The only question is which carrier finds it for you first.

The bind side of this layer needs the same discipline at a higher level. Our BIND_IN_PROGRESS lock prevents a duplicate bind request from firing while a previous bind is mid-flight. Without it, a slow carrier and a refreshed browser tab is a double policy. With it, a slow carrier is just a slow carrier.

A few patterns we've made peace with at this layer:

• Some carriers mutate their own quote ID on every response, so you cannot key idempotency on the carrier's identifier.
• Some carriers expose tens of thousands of class-code-and-state combinations behind an API that crashes its own server midway through a full pull. Retry logic at this layer has to detect partial failure and resume from the gap.
• Some carriers' quote endpoints run slow enough under load that the retry layer has to distinguish a slow success from a real timeout — a thirty-second response that eventually returns 200 is not a candidate for retry.

None of these are anyone's fault. They're the shape of the world. Layer 3 has to absorb them.

Layer 4 — Response normalization and error classification

What this layer absorbs: every way thirty carriers say "no."

The temptation here is to treat error classification as a UI problem. It isn't. It's an alerting problem. The difference between a legitimate decline (the carrier did its job, the risk is out of appetite) and an internal failure (something in our stack is broken) is the difference between an INFO log and a page to oncall. Conflate the two and you either drown oncall in noise or you go silent on real production incidents. Both have a half-life.

Our internal contract is strict. Legitimate declines log at INFO. ERROR is reserved for unhandled failures. The error-taxonomy mapping itself lives in a database-backed model — carrier, status code, carrier error conditions, our internal quote type, our error message, whether to retry. We keep it in a table, not in code, so we can add a new error class for a carrier's mid-integration change without a redeploy.

The hard cases are the carriers whose decline taxonomy isn't structured to begin with. USLI returns decline reasons across three different response fields in different combinations. GAIG requires iterating through every answer in the request to figure out which one tripped a rule. Each of these forces Layer 4 to carry weight that the carrier's API hasn't carried for itself.

Layer 5 — Audit logging and replay

What this layer absorbs: time.

Every request/response pair needs to be replayable for years. Carrier disputes — our records show no such quote — get resolved by replaying the exact payload we sent and the exact response we received. Compliance audits, post-incident root cause analysis, and retroactive bug fixes all live in the same store.

The reason this layer matters more than it looks: it's the only layer that can save you when the layer above it fails. A Hiscox quote had been sitting in a customer's session for three weeks. Hiscox returned a 422 with an empty body — the quote had expired, which is reasonable carrier behavior. Layer 4 saw the 422 and threw. The only reason the customer didn't see a hard error is that Layer 5 had already stored the bridgingLink from the original quote response. We fell back to the stored link. The customer kept moving. Layer 5 caught what Layer 4 dropped.

Coalition deserves a positive callout here. Their webhook contract documents idempotency, defines the event lifecycle explicitly, and ships a replay endpoint that re-consumes any event by ID. That's the kind of carrier-side design that lets the integrator's audit layer stay simple.

Observability across the stack

Each of these layers needs its own observability hooks. Auth-failure rate at Layer 1. Retry exhaustion and idempotency-key collisions at Layer 3. ERROR-rate vs. INFO-rate divergence at Layer 4. Audit-write success rate at Layer 5. Aggregate "quote success rate" alone tells you nothing — by the time it moves, three layers have already silently degraded.

We'll go deep on monitoring in Part 9. The framing here is that monitoring isn't a sixth layer bolted on top of the stack. It's a property each layer ships with. If a layer can't tell you whether it's healthy, it isn't a layer. It's an outage waiting to be discovered.

The thinnest layer wins

A stack is only as strong as its thinnest layer. Most in-house carrier integrations ship four solid layers and one thin one. The thin one is the only one anyone remembers — because it's where every production incident eventually traces back to.

The reason this matters for the build-vs-buy decision isn't that any single one of these layers is hard. It's that building all five well, at the same time, while adding new carriers, and keeping the layers consistent across the integrations you already shipped — that's the work. It doesn't end. It compounds.

For the full lifecycle, see Anatomy of a Carrier Integration.

Carrier API integrations are hard work. Anyone who's built one against a SOAP service over mutual TLS, chased an idempotency rule through three retry layers, or reverse-engineered a date format from production declines knows that. The hard parts engineers expect — auth, transport, error handling, retries, sandbox quirks — are bounded. They have finished states. A team can scope them, build them, and move on.

The translation layer underneath the API doesn't behave that way. Every carrier has a different mental model of the same business — different class-code taxonomies, different appetite logic, different decline shapes — and the translation layer between their model and yours is a permanent piece of software that keeps moving after launch.

It's the part of the integration that doesn't show up in any in-house build estimate. It's also the part that doesn't end.

Class codes carry the rest of the model

When we describe a small-business risk to a carrier — a 12-person restaurant in Pinellas County, Florida, $1.2M revenue, no liquor — the structure that varies most across carriers, drifts most after launch, and drives the most production incidents we triage is the class code.

Three reasons class codes are especially hard.

Multiple, mismatched taxonomies layered on top of each other. Workers' comp programs map onto NCCI. General liability programs map onto SIC or NAICS. Almost every carrier sits a proprietary classification on top of one or more of those, and the proprietary layer is rarely shaped like the public taxonomy underneath. Some carriers ship four-digit numeric codes. Some ship alphanumeric codes with suffix variants — 6006F and the like — that signal state-specific overrides. Some ship multi-layer hierarchies: industry → sub-industry → class description keyword → class description id. Resolving a single agent selection into the right carrier-internal code can require four lookups.

Many-to-many, not one-to-one. The cleanest version of the problem assumes one agent-facing code maps to one internal code. The actual version is many-to-many. The same agent-facing code resolves to different internal codes depending on state, occupancy type, and SIC. The same internal code maps back to multiple agent-facing codes. Carriers handle this internally with rule engines the integrator never sees — only the resulting quote, or the resulting decline.

Chains and loops. Some carriers' class-code structures don't terminate cleanly. Selecting one code pulls in secondary and reclass codes that can chain or loop back. A UWQ answer can replace the primary class with a different one, which brings its own full set of secondary codes, recursively. One selection becomes ten.

The class code is also the load-bearing input for everything downstream. It determines which underwriting questions apply. The UWQ answers determine appetite. Appetite determines whether a quote comes back at all. Drift in the class-code layer cascades through the chain. The other dimensions of the data model — legal entity types, payroll conventions, limits, decline reasons, broker codes — each carry their own variance and each eventually demand their own normalization rule. They're satellites around the class-code problem.

One carrier's "restaurant" is another carrier's "food service — limited" and a third carrier's decline

"Out of appetite" hides a lot of structure. Appetite isn't a flat list of allowed industries. It's a function of class code, state, occupancy type, revenue band, prior losses, and a per-carrier set of guardrails. The class-code mapping is the input to that function. When the mapping drifts, the function silently returns a different answer.

This is the part that doesn't show up in any in-house build estimate. The visible work is the mapping — somebody sits down with a carrier's reference data and builds the lookup table. The hidden work is everything that comes after: detecting that the carrier updated their internal classification last Thursday, regenerating the canonical mapping, replaying in-flight applications, and shipping the change before customers see a wrongly declined quote.

[!note]

Inline diagram (Mermaid, first-pass): how a single agent-facing selection resolves through state lookup, occupancy modifier, NAICS cross-check, carrier-internal code, and appetite — with the silent-decline failure mode branching off when any link drifts.

‍

A typical integration, not an exceptional one

One carrier we integrate with — a large multi-line national writer — maintains a many-to-many mapping between the class codes their agents see and the codes their pricing engine uses internally. The visible code is one field. The internal resolution is three: a lessorsClassCode, a proxyClassCode, and a program assignment, each computed from a combination of state, occupancy type, and SIC. The same agent-facing code resolves to different internal codes depending on the fact pattern. The same internal code maps back to multiple agent-facing codes.

When we built the integration, the carrier shared their internal taxonomy as a spreadsheet. The mapping didn't quite line up with the API's actual behavior — there were resolution rules in the pricing engine that weren't in the documentation. We discovered them in production, one wrongly declined quote at a time, until our error patterns surfaced enough signal that we could reverse-engineer the missing pieces and submit a corrected mapping back to the carrier for review.

That isn't a story about a bad integration. It's a story about a typical one. Across our 60+ live integrations, every one has a version of it. Some carriers ship a single flat code list and the work is just to keep it current. Some carriers ship recursive structures where one class-code selection pulls in secondary and reclass codes that cascade further. Some carriers ship no NAICS↔internal mapping at all and expect the integrator to build it, get it reviewed, and own it forever.

The pattern is the same in every case: the integrator builds and maintains the cross-carrier translation layer that the carriers themselves don't.

The canonical model

There's a trap in-house teams fall into early: treat each carrier integration as its own self-contained system. Pass the carrier's fields through into the application as-is and let the UI render whatever the carrier sent.

It works for the first carrier. It collapses on the second.

By the third carrier, every product surface — quote display, application rehydration, comparison views, broker-facing dashboards — has carrier-specific conditional logic threaded through it. Every change to any carrier ripples into every surface. The translation layer that wasn't built upfront ends up implicitly built everywhere, in pieces, without versioning.

A canonical model is the alternative. One internal representation of an application — class code, entity type, location, payroll, prior losses, UWQ answers — that everything in the platform consumes. Carrier-specific adapters translate the canonical model into and out of each carrier's shape. The rest of the platform stops caring which carrier is on the other end.

The canonical model isn't a schema. It's a contract — between the integration team and the rest of the engineering org — that says: this is the shape of the world; if a carrier disagrees, the disagreement lives in the adapter, not in the product.

The canonical model extends past application data into underwriting question normalization, where the same translation problem repeats with even more shape variance. Part 6 of this series goes deep on UWQ.

Versioning the canonical model

A canonical model that doesn't version is a fossil. Across our live portfolio, something changes on the carrier side roughly every week — a new class code appears in a quote response that wasn't in last Friday's reference data, an underwriting question's applicability shifts, a payload field becomes required. None of it arrives with a changelog.

A versioning strategy has to handle three pressures.

Carrier-initiated changes with no deprecation window. A new class code appears in a Tuesday quote response that wasn't in Friday's reference data. The adapter has to detect, log, and decide: is this a known change to absorb, or a drift to alert on?

Internal canonical schema bumps for new carriers. Every new carrier surfaces edges the model hadn't anticipated. Alphanumeric class codes were one edge. Multi-layer industry hierarchies were another. The model has to evolve without breaking the contracts the rest of the platform depends on.

In-flight application backfills. When a common UWQ definition changes, every in-flight application that referenced the old definition has to be remapped to the new one. That migration is invisible to the carrier and invisible to the customer — and a single missed application is a silent decline.

This is the permanent data-ops function that doesn't show up in any in-house build estimate. It's not engineering work in the traditional sense — it's a discipline that sits between engineering, insurance domain expertise, and production monitoring. Most in-house teams don't build it because they don't yet know it's a category. They learn it the way we learned it: from the silent declines no one noticed until a customer escalated.

What this means for an in-house build

The build estimate for a carrier integration usually covers the API client. It rarely covers the canonical model, the per-carrier adapters, the versioning strategy, the drift detection, the backfill machinery, or the data-ops discipline to keep all of it current. Those aren't optional layers. They're the difference between an integration that works on launch day and one that still works six months later, after the carrier has quietly shipped two class-code updates and an appetite change.

We built our canonical schema because we got tired of losing these bets one regex at a time — if you're early enough in this work that you can still avoid finding out the hard way, that's the call to make now.

‍For the full lifecycle of a carrier integration — from first legal conversation through ongoing maintenance — see Part 1: Anatomy of a Carrier Integration.

Some carrier APIs are modern REST with a clean sandbox and a published OpenAPI spec. Some are SOAP envelopes wrapped around a mainframe. Some are a portal, a PDF, and a prayer. Knowing which one you're sitting in front of is the first technical skill of integration work — and it's a skill that's almost never taught.

Part 1 mapped the full lifecycle of a carrier integration. Part 2 covered the prerequisites. This post is about what to read when you sit across from a carrier and decide whether to commit.

What the rubric is — and what it isn't

Across nearly thirty live carrier integrations, the best predictor of integration pain isn't carrier size or engineering experience. It's how the carrier's API surface scores on a small number of axes we can usually read in the first technical meeting.

The rubric doesn't make a hard integration easy — every integration is a multi-month commitment, even with perfect documentation. What the rubric does is surface, in week one, where the next eight to twelve weeks of unplanned discovery are coming from.

The seven axes

1. Transport & auth

The green-flag answer is REST + JSON, a published OpenAPI spec, OAuth2 with refresh tokens, and broker-code provisioning that's either self-served via API or backed by a clear SLA. What we see is a wide spread — REST, SOAP, XML, JSON, GraphQL, and the occasional flat-file or PDF intake; OAuth, custom token exchanges, mutual TLS, IP allowlists, and portal-cookie hybrids; broker-code models that range from self-served APIs to manual approval, one agency at a time, forever. Within a single carrier, different lines of business often run on entirely different APIs. This read is the first thirty seconds of the kickoff call, and it sets the floor on everything else.

2. Sandbox fidelity

A high-scoring carrier ships a sandbox that mirrors production — parity on minimum premiums, appetite rules, and class-code data; reasonable uptime; a self-served path to a test agency. We've seen the opposite too. Some test environments run with multi-hour daily downtime windows. Other sandboxes silently accept payloads production rejects, because the appetite and class-code data in prod aren't replicated in test. Some carriers don't enforce backward compatibility, so the contract you tested against on Tuesday quietly differs on Thursday with no version bump. Sandbox fidelity determines whether your testing actually means anything.

3. Documentation quality & accuracy

The green-flag answer is an OpenAPI spec that compiles, sample payloads that run against the live API on the first try, and a single source of truth. What we've seen instead: Swagger specs with broken $ref pointers and missing schemas. Sample payloads where the documented date format was reversed from what the API actually required — caught only when quotes started silently declining. A documented exposure field that turned out to be the wrong field entirely. A carrier that told us mid-build that the API wasn't the source of truth after all, and to "use this Excel sheet" instead. This is one of the two highest-impact axes — documentation quality is the single best predictor of how much of the carrier's job your team is going to end up doing.

4. Additional-data delivery (class codes, appetite, UWQ)

The integration isn't just the quote API — it's the apparatus that converts whatever the carrier has (class codes, appetite, underwriting questions) into a structure your platform can use. The green-flag answer is programmatic endpoints, versioned and paginated. What we've seen instead: an Excel workbook for class codes; a Word doc for UWQs; a PDF for appetite. UWQ catalogs that arrive shaped like a list and behave like a graph. APIs that return tens of thousands of class-code-and-state combinations one at a time, with no bulk endpoint, on servers that don't always stay up for the full pull. The other highest-impact axis, routinely missed in build estimates. If the carrier ships this data as a spreadsheet, your team is building the converter — and the converter is real software.

5. Communication

A named technical contact who actually built the API. A Slack Connect or Teams channel. Response latency in hours, not weeks. The best carriers put their engineers in a shared channel — we ping a specific person about a specific endpoint and resolve in hours. The worst answer integration questions only in a weekly thirty-minute meeting, where every unblocker carries a five-day minimum wait. Frequently, the person on the call is a program manager, not the API's actual author. They guess at answers, and the integration pays for the guesses. The delta between Slack-tier and weekly-meeting-tier communication is worth two to four weeks on a typical integration.

6. Error taxonomy & decline reasons

The green-flag answer is a structured decline-reason object that separates out-of-appetite from premium-below-minimum from UWQ-validation from data-validation errors. What we've seen instead: every carrier expresses declines differently, and the shapes look right until you parse them. Some carriers ship reasons as free-text English requiring string-matching. Some carriers split reasons across multiple response fields that have to be assembled. Some carriers return reasons buried inside what looks like a successful quote response. We've built a carrier-by-carrier decline-reason normalization layer because no two carriers ship the same shape.

7. Versioning discipline & change notification

Semantic versioning. Release notes. Advance notice of breaking changes. A deprecation window. What we've seen instead: most carriers ship changes without announcing them. NCCI codes update mid-quarter. Underwriting questions get added or moved between payload groups. Payload shapes shift. The first signal anyone gets is the response to whatever the agent just submitted. One carrier we integrate with decommissioned its traditional BOP product entirely and forced every customer to migrate. This is the axis most predictive of ongoing maintenance load, not initial build time. A low score here doesn't make the integration take longer to ship — it makes the integration cost more every month after it ships, forever.

How to read the rubric in the kickoff call

Most of the rubric reads in the first technical meeting. Some signals are obvious; others require listening for what isn't said.

‍

What the rubric tells you about timeline

A high-rubric carrier, integrated by a competent in-house team starting from scratch, is a fourteen-to-sixteen-week build. That's not a low number — it's an industry-honest one. CoverForce ships the same carriers in eight to ten weeks because we've absorbed the cost upstream — canonical schema, retry/idempotency infrastructure, IP-allowlist proxy, UWQ engine, decline-reason normalization, all built carrier by carrier over years. The rubric transfers the diagnosis, not the ramp.

A low-rubric carrier doesn't shift the build by one or two weeks. It extends discovery alone to eight to twelve weeks before serious code is written. Documentation gaps become customer-facing declines. Missing data delivery becomes a parallel data-ops effort. Weak versioning becomes a perpetual monitoring tax. None of it shows up as a missed deadline.

Documentation quality and additional-data delivery are the two axes most predictive of total spend; versioning drives ongoing maintenance; communication quality decides whether discovery takes four weeks or twelve.

The view from the other seat

The same seven axes look very different from inside a carrier. Sandbox fidelity is the leading indicator of false declines in your customers' traffic — integrators discover the gap in your end customers' submissions, not in their own test environment. Documentation and data delivery are recruiting taxes; every Excel workbook shipped in lieu of a spec adds weeks to every integration partner you'll ever have. Versioning discipline is the silent killer — the carriers we ship fastest with are the ones who tell us before they change a class code, not after. Communication quality is whether an integration ships in twelve weeks or twenty-four; the carriers scoring highest here are the ones whose engineers, not their program managers, are in our Slack channel. The companion series goes deeper on the prescriptive side; this rubric is the diagnostic on-ramp.

Close

If you're sizing a build and want a second read on a specific carrier, we've already scored every major commercial API in the market. The rubric above is the one we use internally; the eight-to-ten-week integration timeline we ship at is the product of work we've already done. If you want to know what you'd actually be walking into on a given carrier, we're happy to share what we found.