Two auth tiers — User-facing endpoints (preview, create, get, list) use JWT Bearer. Admin endpoints (list all, update) require an admin-api-key header.

​
Overview

An insurance policy ties a primary user to an insurance-type benefit and a set of dependants to be covered. The SELF dependant (the primary user themselves) is always auto-included in the covered members — you do not need to add it manually to dependant_ids. Premiums are calculated per member (including SELF) based on age and gender, stored in minor units (INR paise). The purchase flow has two steps:
  1. Preview — compute the premium breakdown without creating a record
  2. Create — purchase the policy; status starts as pending
At creation time, the server also auto-creates MRN records for each covered dependant at the benefit’s provider. The resulting mapping is stored in the policy’s metadata.dependant_mrn_map. Activation (status → active) is done by an admin once the external insurer issues a policy number.

​
Purchase Flow

​
Auth Guards by Endpoint

EndpointJWT userAdmin keyNotes
POST /users/{id}/insurance_policies/preview✓—Dependants must belong to the token user
POST /users/{id}/insurance_policies✓—One active policy per user+benefit
GET /users/{id}/insurance_policies/{pid}✓—Returns 404 for wrong user
GET /users/{id}/insurance_policies✓—Filters by status, benefit_id
GET /insurance_policies—✓Filter by user, benefit, status, time range
PATCH /insurance_policies/{pid}—✓Set status, external_policy_id, dates

​
Key Concepts

​
Premium Calculation

Premiums are calculated per dependant based on age bracket and gender:
Age bracketMonthly (INR)
0–18₹150
19–35₹250
36–50₹350
51–65₹500
66+₹650
Female dependants receive a 5% discount. Daily premium = ⌈monthly × 12 / 365⌉.

​
Policy Status Lifecycle

pending → active → requires_customer_renewal_in_grace
                ↓
         requires_policy_reissuance
                ↓
         requires_customer_renewal
                ↓
              expired

​
Endpoints

POST .../preview

Preview the premium breakdown for a set of dependants without creating a policy.

POST .../insurance_policies

Purchase an insurance policy. Status starts as pending.

GET .../insurance_policies/{id}

Fetch a single policy by its internal UUID.

GET .../insurance_policies

List the authenticated user’s policies. Filter by status or benefit_id.

GET /insurance_policies (admin)

Admin: list all policies with full filtering including time range and user.

PATCH /insurance_policies/{id} (admin)

Admin: set status, external policy ID, start/end dates.

​
Request / Response Examples

curl -X POST http://localhost:8080/users/USER_ID/insurance_policies/preview \
  -H 'Authorization: Bearer eyJhbGci...' \
  -H 'Content-Type: application/json' \
  -d '{
    "benefit_id": "018f4c2a-1b3e-7d8f-9a0b-2c3d4e5f6a7b",
    "dependant_ids": ["01926b3a-7c2e-7d4f-a1b2-c3d4e5f60001"]
  }'
The SELF dependant is always auto-included in dependant_ids — you do not need to add it. The members array in the preview response and dependant_ids in the create response will both include SELF automatically.

​
nominee_details — Tagged Union

The nominee_details field is a JSONB tagged union. Use one of two variants:
VariantFieldsDescription
dependanttype, dependant_idNominee is an existing dependant on the user’s profile
externaltype, name, relationship, date_of_birth, gender, phoneNominee is a person not registered as a dependant

​
Preview members Array

The preview response returns a unified members array of MemberDetail objects instead of separate primary_member and dependants fields:
FieldTypeDescription
dependant_iduuidThe dependant’s internal ID
first_namestringFirst name
last_namestringLast name
salutationstringTitle (mr, mrs, ms, master)
ageintegerAge computed from date of birth
genderstringmale or female
relationshipstringRelationship to the primary user (self, spouse, child, etc.)
monthly_premiumMoneyPer-member monthly premium in minor units

​
MRN Auto-Creation

When a policy is created, the server automatically creates one MRN record per covered dependant at the benefit’s provider. The metadata.dependant_mrn_map field maps each dependant ID to its newly created MRN ID.

​
Error Codes

CodeHTTPDescription
IP-1000500Internal server error
IP-1001404Insurance policy not found
IP-1002404Benefit not found or inactive
IP-1003400Benefit is not of type insurance_policy
IP-1004400Benefit is missing a required insurance field
IP-1005404Dependant not found or inactive
IP-1006400Dependant does not belong to the requesting user
IP-1007404Nominee dependant not found or inactive
IP-1008409User already has an active policy for this benefit
IP-1009400Requested dependant count exceeds benefit’s max_dependants
IP-1010400Validation error
IP-1011400Invalid UUID in request
IP-1012403Forbidden