API Reference

Base URL: /api — All requests and responses use JSON.

Entitlement State Machine

Issued → Active → Triggered → Claim Initiated → Evidence Submitted → Assessed → Approved / Part Approved / Declined → Paid / Settled → Closed

Dispute flow: Any assessable state → Disputed → Resolved (upheld / overturned / adjusted) → Closed

Containers (Policies)

POST /api/containers Create a policy container

Creates a new entitlement container (insurance policy).

Body Parameters

Name	Type		Description
policy_number	string	required	Unique policy identifier
product_type	string	required	e.g. travel_comprehensive, home_buildings
status	string	optional	draft \| active \| expired \| cancelled (default: draft)
policyholder_name	string	optional	Full name of policyholder
policyholder_email	string	optional	Email of policyholder
term_start	datetime	optional	Policy start date
term_end	datetime	optional	Policy end date
territory	string	optional	Coverage territory
trip_details	object	optional	Trip-specific data (JSON)

{
  "policy_number": "POL-2026-001",
  "product_type": "travel_comprehensive",
  "status": "active",
  "policyholder_name": "James Wilson",
  "policyholder_email": "james@example.com",
  "term_start": "2026-03-01",
  "term_end": "2026-03-15",
  "territory": "EU"
}

GET /api/containers List all policies

Returns paginated list of policy containers.

Query Parameters

Name	Type	Description
status	string	Filter by status
limit	integer	Max results (default: 50)
offset	integer	Pagination offset

GET /api/containers/:id Get policy with all entitlements

Returns the full policy container with nested entitlements, sub-entitlements, and open dispute count.

Incidents

POST /api/incidents Create an incident

Creates a new incident. Incidents are scenario anchors that can be referenced by multiple claims.

Body Parameters

Name	Type		Description
incident_type	string	required	medical_event \| baggage_loss \| trip_cancellation \| trip_delay \| missed_connection \| accommodation_issue \| other
incident_date	datetime	required	When the incident occurred
location	string	optional	Location of incident
narrative_summary	text	optional	Description of what happened
involved_parties	object	optional	JSON object with parties (airline, provider, etc.)
evidence_links	array	optional	Array of evidence URLs

{
  "incident_type": "trip_delay",
  "incident_date": "2026-02-28T10:30:00Z",
  "location": "Heathrow Airport, London",
  "narrative_summary": "Flight BA123 delayed 6 hours due to technical issues",
  "involved_parties": {
    "airline": "British Airways",
    "flight": "BA123",
    "booking_ref": "ABC123"
  },
  "evidence_links": ["https://example.com/delay-report.pdf"]
}

GET /api/incidents List all incidents

Returns paginated list of incidents.

Query Parameters

Name	Type	Description
incident_type	string	Filter by type
limit	integer	Max results (default: 50)
offset	integer	Pagination offset

GET /api/incidents/:id Get incident details

Returns incident with all related claims.

PUT /api/incidents/:id Update incident

Updates incident details. Any provided fields will be updated.

DELETE /api/incidents/:id Delete incident

Deletes an incident. Fails if incident has associated claims.

Claims

Open → Awaiting Evidence → Assessing → Settled → Closed

POST /api/claims Create a claim

Creates a new claim. Claims represent requests for payment and adjudication against one or more entitlements.

Body Parameters

Name	Type		Description
policy_id	uuid	required	Container/policy ID
claimant_id	string	required	Unique claimant identifier
incident_id	uuid	optional	Link to incident (if applicable)
claimant_name	string	optional	Claimant full name
claimant_email	string	optional	Claimant email
channel	string	optional	customer \| agent \| provider (default: customer)
claim_lines	array	optional	Array of claim line objects

Claim Line Object

Name	Type	Description
entitlement_id	uuid	Entitlement being claimed against
requested_amount	integer	Amount in pence/cents
currency	string	Currency code (default: GBP)

{
  "policy_id": "abc123...",
  "claimant_id": "user_456",
  "claimant_name": "James Wilson",
  "claimant_email": "james@example.com",
  "incident_id": "def789...",
  "channel": "customer",
  "claim_lines": [
    {
      "entitlement_id": "ent_xyz...",
      "requested_amount": 50000,
      "currency": "GBP"
    }
  ]
}

GET /api/claims List all claims

Returns paginated list of claims with policy and incident info.

Query Parameters

Name	Type	Description
policy_id	uuid	Filter by policy
status	string	Filter by status
limit	integer	Max results (default: 50)
offset	integer	Pagination offset

GET /api/claims/:id Get claim details

Returns claim with all claim lines and status history.

POST /api/claims/:id/transition Change claim status

Advances claim through the state machine with validation.

Body Parameters

Name	Type	Description
to_status	string	Target status (must be valid transition)
reason	string	Reason for transition
evidence	object	Supporting evidence (JSON)
transitioned_by	string	Who made the transition

POST /api/claims/:id/assess Assess and decide claim

Performs claim assessment with decision on claim lines. Claim must be in "assessing" status.

Body Parameters

Name	Type	Description
decision	string	approve \| partial \| decline
decision_notes	text	Assessment notes
line_assessments	array	Array of line assessment objects
transitioned_by	string	Assessor identifier

{
  "decision": "partial",
  "decision_notes": "Approved medical expenses, declined accommodation upgrade",
  "line_assessments": [
    {
      "line_id": "line_abc...",
      "approved_amount": 45000,
      "line_status": "approved",
      "decision_reason": "Within policy limits"
    },
    {
      "line_id": "line_def...",
      "approved_amount": 0,
      "line_status": "declined",
      "decision_reason": "Not covered under policy"
    }
  ],
  "transitioned_by": "assessor_123"
}

GET /api/claims/:id/history Get claim audit trail

Returns complete status transition history for the claim.

POST /api/claims/:id/lines Add line to claim

Adds a new claim line to an existing claim. Claim must not be closed.

Body Parameters

Name	Type	Description
entitlement_id	uuid	Entitlement to claim against
requested_amount	integer	Amount in pence/cents
currency	string	Currency code

PUT /api/claim-lines/:id Update claim line

Updates a claim line. Can modify requested amount, approved amount, status, or decision reason.

Entitlements (Coverage)

POST /api/containers/:id/entitlements Add coverage to a policy

Adds a coverage entitlement to a policy container. Supports nested entitlements (sub-limits and add-ons).

Body Parameters

Name	Type		Description
coverage_type	string	required	e.g. medical_expenses, baggage, cancellation
limit_max_claim	integer	optional	Maximum claim limit in minor units (pence/cents)
limit_per_item_cap	integer	optional	Per-item cap in minor units
limit_excess	integer	optional	Excess/deductible in minor units
currency	string	optional	GBP, EUR, USD (default: GBP)
exclusions	array	optional	List of exclusion strings
required_evidence	array	optional	Required evidence for claims
waiting_period_days	integer	optional	Waiting period before coverage activates
parent_entitlement_id	uuid	optional	Parent ID for sub-limits/add-ons

{
  "coverage_type": "medical_expenses",
  "limit_max_claim": 10000000,
  "limit_excess": 10000,
  "currency": "GBP",
  "exclusions": ["pre-existing conditions", "extreme sports"],
  "required_evidence": ["medical report", "receipts"]
}

State Transitions

POST /api/entitlements/:id/transition Advance entitlement state

Transitions an entitlement to the next valid state. Returns the updated entitlement and transition record.

Body Parameters

Name	Type		Description
to_state	string	required	Target state (must be valid transition)
reason	string	optional	Reason for transition
evidence	object	optional	Supporting evidence (JSON)
transitioned_by	string	optional	Who initiated the transition

{
  "to_state": "active",
  "reason": "Policy activated after payment confirmed",
  "transitioned_by": "underwriting_system"
}

Disputes

POST /api/entitlements/:id/dispute Raise a dispute

Raises a dispute against an entitlement. Moves the entitlement to disputed state. Only available for entitlements in assessable/decision states.

Body Parameters

Name	Type		Description
reason	string	required	Reason for the dispute
evidence	object	optional	Supporting evidence (JSON)

POST /api/disputes/:id/resolve Resolve a dispute

Resolves an open dispute. Moves the entitlement to resolved state.

Body Parameters

Name	Type		Description
resolution	string	required	resolved_upheld \| resolved_overturned \| resolved_adjusted
resolution_notes	string	optional	Notes about the resolution

History & Audit

GET /api/entitlements/:id/history Full state transition audit trail

Returns the complete audit trail for an entitlement: all state transitions and disputes in chronological order.

GET /api/stats Dashboard statistics

Returns aggregate statistics: total containers, active containers, total entitlements, active claims, open disputes, total transitions, and state distribution.

GET /api/recent-activity Recent state transitions

Returns recent state transitions with policy and coverage context. Use ?limit=N to control result count.