API reference

All endpoints take and return JSON, except /api/ussd, which speaks the aggregator’s form-encoded dialect and replies in plain text. Authenticate with your partner key in the Authorization header.

POST/api/quote

Underwrite a worker and return a personalised weekly premium.

Request

{
  "phone": "08012345678",
  "incomePerDay": 4000,
  "productType": "rider_shield",
  "age": 29
}

Response

{
  "quoteId": "b1f0…",
  "productName": "Rider Shield",
  "premiumWeekly": 500,
  "coverageLimit": 80000,
  "dailyBenefit": 1500,
  "explanation": "You pay ₦500 every week…",
  "riskBand": "standard",
  "expiresAt": "2026-07-15T09:12:00.000Z"
}

POST/api/enroll

Convert an accepted quote into an active policy and a certificate.

Request

{
  "quoteId": "b1f0…",
  "paymentConfirmation": "txn_9f2b…",
  "name": "Chinedu Okafor"
}

Response

{
  "policyId": "9c2e…",
  "policyNumber": "KV-2026-104829",
  "premiumWeekly": 500,
  "coverageLimit": 80000,
  "renewalDate": "2027-07-14",
  "certificateUrl": "https://…"
}

POST/api/claim

File a claim. Triage runs asynchronously; poll the claim for a decision.

Request

{
  "policyNumber": "KV-2026-104829",
  "claimType": "medical",
  "amountClaimed": 15000,
  "description": "A car hit me at Ojuelegba…",
  "documentS3Keys": ["claims/…/receipt.jpg"]
}

Response

{
  "claimId": "4d81…",
  "status": "approved",
  "amount": 15000,
  "eta": "within 2 hours"
}

GET/api/claim/:id

Poll a claim for its current status and settled amount.

Request

—

Response

{
  "claimId": "4d81…",
  "status": "settled",
  "amountClaimed": 15000,
  "amountApproved": 15000,
  "settledAt": "2026-07-14T11:47:00.000Z"
}

POST/api/ussd

USSD session handler for aggregators. Form-encoded or JSON. Returns text/plain, CON or END prefixed.

Request

sessionId=abc123
phoneNumber=%2B2348012345678
text=1*4000*1

Response

CON Your quote:
N500/week
Cover up to N80,000

1. Confirm
0. Cancel