Claim mapping

A host maps its own claim object onto the Claim contract, in the browser, before handing it to the element. Eight fields are required. Everything else is optional, and each section switches on specific capabilities.

What each section switches on

Map this	And get
the required eight	Free-form Q&A, Validate policy, a basic Summary
financials, payments	Reserve estimation, Data insights, money questions
diary	Timeline, QA review, Complaints guidance, vulnerability signals
documents	Summarise documents, and searching the file
tasks, compliance	Next actions with real deadlines
riskFlags, serviceProviders, reimbursements	A Fraud check worth the name
litigation	Litigation risk, Settlement guidance
involvements	Draft a document, Call assist, Field visit briefing
client.slaDays, client.handlingRules	SLA measurement inside QA review

A capability with nothing to work from says so rather than inventing anything, but it will not be much use. The quality of answers tracks the quality of the mapping, and nothing in the product warns that a section is missing.

The complete field list, with types, defaults and descriptions, is the generated Claim schema.

Mapping well

• Write narrative where the contract asks for it. incident.description, diary content and document summary are what the assistant reasons over. Structured fields tell it what; narrative tells it why.
• Documents are summaries. The assistant reads documents[].summary, not the file. A summary that says what the document establishes ("Engineer confirms the inlet hose failed; no evidence of long-term leak") is worth far more than a title.
• Use the host's own ids. Diary entries, documents, tasks and payments each carry an id. The assistant quotes them back as evidence, so ids a handler recognises make answers checkable.
• Dates are YYYY-MM-DD. Comparisons are string comparisons. Convert at the boundary.
• Money is a number in the claim's currency. No symbols, no thousands separators, no minor units.
• Do not invent to fill gaps. Leave a section out rather than sending a plausible placeholder. The defaults are designed to read as "nothing recorded".
• Map incrementally. Start with the eight, then add diary and documents (the biggest gain), then money, then the rest. Watch which capabilities improve.

A mapping function

Keep the mapping in one function the host owns and tests:

import type { Claim } from './claimpilot-claim'; // the type, if we have supplied a typed package

export function toClaimpilotClaim(c: HostClaim): Claim {
  return {
    id: c.reference,
    lineOfBusiness: mapLine(c.productCode),
    title: `${c.claimant.displayName} v ${c.insuredName}`,
    status: mapStatus(c.state),
    currency: c.currency === 'USD' ? 'USD' : 'GBP',
    claimant: { name: c.claimant.displayName, type: c.claimant.isCompany ? 'organisation' : 'individual' },
    incident: { dateOfLoss: isoDate(c.lossDate), dateReported: isoDate(c.notifiedDate), cause: c.causeText, description: c.circumstances },
    policy: {
      policyNumber: c.policy.number,
      effectiveFrom: isoDate(c.policy.start),
      effectiveTo: isoDate(c.policy.end),
      state: c.policy.isLive ? 'active' : 'lapsed',
      policyholder: { name: c.insuredName, type: 'organisation' },
      coverages: c.policy.sections.map((s) => ({ code: s.code, name: s.name, limit: s.limit, deductible: s.excess })),
    },
    diary: c.notes.map((n) => ({ id: n.id, date: isoDate(n.created), author: n.by, type: 'note', content: n.text })),
    documents: c.documents.map((d) => ({ id: d.id, date: isoDate(d.received), direction: d.inbound ? 'inbound' : 'outbound', type: d.kind, title: d.name, from: d.from, to: d.to, summary: d.abstract })),
  };
}

Validate it in the host's own tests against the JSON Schema in the Claim schema, or with the zod schema itself if the host runs JavaScript: Claim.safeParse(toClaimpilotClaim(sample)).

What the assistant does with a thin claim

It answers from what is there and says what is not. Asked for a fraud check on a claim with no payments, it says no payments are recorded rather than declaring the claim clean. That is correct behaviour, and it is also why nothing in the product will flag a thin mapping: watch the answers.