This blog is written by AI for SEO
How to Build an Insurance Ontology: Policies, Claims, Customers
An insurance ontology is a written, machine-readable model of what your business means by policyholder, policy, coverage, claim, payment and broker, how those things link across your systems, and which rules must hold between them. You build it by listing the entities, picking a source of truth per field, matching the same customer across systems, and writing rules such as "a claim must fall inside the policy period". Helix Foundry can draft it over your data and load it into HelixDB.
The reason to bother is mundane. Policy admin says one thing, the claims system says another, the CRM has a third spelling of the customer's name, and someone's spreadsheet is the only place the broker's commission split lives. Any report or AI agent built on top inherits that mess. This guide covers the model, the matching problem, the rules, and how to build it in Foundry, with the trade-offs left in.
What an insurance ontology is for (the short answer first)
An insurance ontology exists so that a question spanning systems has one correct answer: "Which open claims sit on policies that lapsed before the loss date?" or "What have we paid this customer across all their policies?" Without a shared model, each answer is a hand-built join that only one analyst trusts.
In plain terms, an ontology is an agreed description of the things in a domain, how they relate, and the rules that govern them. A schema describes one database. An ontology describes the business, and the schemas map onto it. If you want the general method before the insurance specifics, our guide on how to build an ontology from scattered company data covers the steps in any industry.
Start from decisions, not tables. Write down five to ten questions the model must answer: claims leakage checks, renewal risk, broker performance, cross-sell, regulatory reporting. Every entity and link you add should serve one of them. If it doesn't, leave it out for now.
The entities and links: policyholder, policy, coverage, claim, payment, broker
Six entities carry most of the weight. Define each in one sentence before you touch a connector.
Policyholder: the person or organisation that holds the contract. Distinct from an insured party or a beneficiary if your lines of business need that split.
Policy: the contract, with an effective date, an expiry date and a status.
Coverage: a specific protection under a policy, with a limit and a deductible. A home policy might carry buildings, contents and liability coverages.
Claim: a request for payment for a loss, with a loss date, a reported date and a status.
Payment: money moving in either direction, premium in or claim payout out. Keep the direction as a field, not two unrelated tables.
Broker: the intermediary who placed the policy, with a commission arrangement.
The links matter more than the boxes. A policyholder holds policies. A policy has coverages. A claim is made under a coverage, which puts it on a policy and therefore a policyholder. A payment settles either a premium on a policy or a claim. A broker places policies.
Two modelling choices to settle early. First, link claims to coverages, not just to policies, because "was this loss covered" is a coverage question. Second, pick a source of truth per field: policy admin owns policy dates and status, the claims system owns claim status and reserves, the CRM owns contact details, and the finance system owns payment amounts. Where two systems own the same field, decide which wins and record it. A spreadsheet is rarely the winner, but it's often the only holder of something real, such as a broker's negotiated terms, so map it as a source instead of ignoring it.
Matching one customer across policy admin, claims, CRM and spreadsheets
The same customer is "Dana Whitfield" in policy admin, "WHITFIELD, D" in claims, "Dana W." in the CRM, and a row in a broker's spreadsheet with a typo in the postcode. Four systems, four IDs, one person. This is entity resolution, and it's where most insurance data projects quietly fail.
A workable approach has three layers.
Hard keys first. Match on identifiers that should agree: policy number, tax or national ID where you're allowed to hold it, an email address, a date of birth plus postcode. Hard-key matches are high confidence.
Soft matches second. Normalised name, address and phone get you candidate pairs. Treat these as proposals, not facts.
A review path for the middle. Anything between "certainly the same" and "certainly different" goes to a person. Don't let a fuzzy score silently merge two policyholders. A wrong merge is worse than a missed one, because it attaches one person's claims to another's record.
Keep the original IDs on the merged entity, so you can always walk back to the policy admin record, the claims record and the CRM contact. For the technical detail on this problem in graphs, see entity resolution for knowledge graphs built by an LLM.
Rules that make it trustworthy: a claim must fall inside the policy period
Rules turn a pile of linked records into something you can trust. The canonical insurance rule is that a claim's loss date must fall between the policy's effective and expiry dates. When it doesn't, you have either a data error, a late-reported claim on a claims-made policy, or a genuine coverage question. All three deserve a human look.
Write rules as plain statements first, then encode them:
A claim's loss date must fall inside the effective and expiry dates of the policy it is made under.
A claim must be made under a coverage that exists on that policy.
A claim payout must not exceed the coverage limit.
A policy must have exactly one policyholder of record and at most one placing broker.
A payment must settle either a premium or a claim, never neither.
Two habits keep rules useful. Keep evidence for every value, so when a rule flags a claim you can see which system and which row said what. And route violations to review instead of auto-fixing them. A rule that quietly rewrites a loss date to make itself pass has destroyed the very thing you wanted to audit.
Build it in Helix Foundry: clone, docker compose, or Helix Cloud
Helix Foundry connects your databases, tools and documents, has an ontology agent draft one ontology over them, and loads it into HelixDB as one connected graph you can explore and ask questions of. Every value is traced to the row or document quote it came from. HelixDB is the open-source graph-vector database underneath, and Foundry is the app on top.
To run it on your computer you need Docker with Compose v2, ports 3000 and 8333 free, and room for a few GB of images on first start:
git clone https://github.com/helixdb/helix-foundry.git
cd helix-foundry
docker compose up -d --waitThen open http://localhost:3000. The local install has no OAuth sign-in, but it authenticates its single owner with a site token; it is intended for one person on their own computer and should not be exposed. If you'd rather not run it yourself, use Helix Cloud at foundry.helix-db.com and choose Set up with your agent.
The flow for insurance follows the Foundry quickstart:
Connect data. Foundry connects data from your systems and takes documents such as policy wordings or adjuster notes. Point it at the database behind policy admin, the claims store, and the CRM export. Spreadsheets can come in as files from a source such as S3, or be pushed from your app to an API source. Connect data covers adding a source, testing it and syncing its tables.
Generate an ontology. Foundry drafts types, links and mappings from your synced tables. Each generation creates a new, immutable version. Review its types, links, mappings, rules and sources, then make it current before loading.
Load and explore. The current version loads into HelixDB as a graph. Browse it, and ask questions in plain language, such as which claims sit on policies outside their period.
Wire in your agent. Connect an agent through the Helix MCP so the agent works against the ontology instead of raw tables.
Foundry never writes to your sources, which matters when the sources are a live policy admin system. Be aware of how the AI step works: a generation sends your synced tables, plus up to five of the newest documents of each set it picks, to Foundry's agent, which drafts the version. Decide whether that's acceptable for your data before connecting policyholder records, and start with a representative slice.
The hard parts: self-healing, correct links and schema change
A first draft is a weekend. Running the ontology for a year is the real work, and three problems show up every time.
Drift and self-healing. Policy admin gets a new field, a CRM export changes a column name, a broker starts sending a different spreadsheet layout. Foundry's self-healing audits a current load for missing links, mapping gaps and source drift. Findings are surfaced for review, not silently applied, which is the behaviour you want in an insurer: someone approves the change.
Correct links. A wrong link is worse than a missing one. If a claim attaches to the wrong policy, every downstream number is quietly wrong. Because every value is traced to its source row or document quote, you can check a suspicious link against the evidence instead of trusting the graph. Rules, like the policy-period check above, catch the links that can't be right.
Schema change. New lines of business bring new coverage types, and a new regulation adds a field. To revise a draft in Foundry, you stage edits and preview them, and creating the revision saves them as another version. Versions are immutable, so you can compare what changed and keep the prior one as a record.
None of this removes judgement. It removes the manual re-plumbing, so the judgement goes where it counts: approving a merge, accepting a rule, deciding which system wins a field.
When you do not need an insurance ontology, and Foundry's trade-offs
You don't need an ontology if one system already holds the truth for your question. A small MGA whose policy admin system also handles claims and billing may be well served by a view and a few reports. If your question is "how many policies did we bind this month", a query on one table answers it.
You do need one when the question crosses systems, when the same customer lives under different IDs, when AI agents will act on the data and need to be right, or when an auditor will ask where a number came from.
Foundry's trade-offs, plainly:
It drafts, you review. The ontology agent proposes types, links and mappings. Someone who understands your business has to approve them. Budget time for that review.
Data goes to a model. Generation sends synced tables and recent documents to Foundry's agent. Check this against your data-protection obligations before connecting sensitive records.
Local install is single-user. The self-hosted install is single-owner and intended to stay on localhost, but it authenticates the owner with a site token; no OAuth sign-in is required.
Start narrow. One line of business and one question first. An ontology across every product on day one will stall.
If you want a comparison with another route, our piece on an open-source alternative to Palantir Foundry for ontologies covers how the approaches differ.
Start with one line of business and one cross-system question
An insurance ontology earns its keep when it answers one real question that spans systems, such as claims outside their policy period, and shows where each value came from. Pick one line of business, list the six entities, write the five rules above, then clone helix-foundry, run docker compose up -d --wait, and connect your policy admin and claims databases. Review the first draft version, load it into HelixDB, and see how many violations your data already contains. The repo is at github.com/helixdb/helix-foundry, and a star helps others find it.