Resources

Policies

Look up an active policy, manage renewals, and process cancellations.

Retrieve a policy#

GET/v1/policies/:id

200 OK

json

{
  "policy_id": "pf_pol_01HX...",
  "status": "active",
  "member": { "member_id": "pf_mem_01HX...", "name": "Amaka Okeke" },
  "plan": { "plan_id": "pf_plan_silver_ind", "name": "Silver Plan" },
  "effective_date": "2026-06-01",
  "renewal_date":  "2027-06-01",
  "lapse_risk_score": 0.12,
  "premium": { "amount": 9350, "frequency": "monthly", "next_due": "2026-07-01" }
}

Renewals#

A daily job identifies policies expiring within 30 days. With auto-renew enabled, collection runs 3 days before expiry. Successful renewals fire policy.renewed; failures enter the grace period and fire premium.failed.

Cancellations#

DELETE/v1/policies/:id

Termination is end-of-billing-period by default; pass { "effective": "immediate" } to terminate immediately. Unused premium is refunded when applicable.

Commission clawback

If a policy is cancelled within 90 days of issue, the corresponding commission entry is reversed automatically. Your ledger will reflect this on the next settlement cycle.