Life Insurance
This guide walks you through issuing life insurance policies using the Inshuwa API.
Every step below is runnable. Set your key once, fill in the request, press Try it out, and read the real response without leaving the page — see Running requests from the guide.
Set it once and every Try it out below is authenticated. It stays in this browser's local storage and is never sent anywhere but the API.
Choose your issuance flow
Life supports three of the four issuance flows.
| Prepaid — Inshuwa collects | Account-settled — PayLater / external | |
|---|---|---|
| Quotation first | A. POST /quotations/life → issue with payment details | C. POST /quotations/life → issue without them |
| Instant (one call) | B. POST /policies/life/instant-issue | — |
One issue endpoint, two flows
POST /policies/life/{quoteId}/issue covers both A and C. Send mobileMoneyAccountNumber or cardDetails and it initiates a collection — the policy is issued when the payment confirms. Omit them and your account's PayLater or external arrangement applies, and the policy is issued immediately.
POST /payments/{quoteId}/pay does the same thing as the payment-carrying form, so use one or the other — it is not a step before issuing.
Client registration, product selection, documents and renewal are shared by every flow.
Step 1: Register a Client
Create an individual policyholder. Keep the id from the response — it is the clientId when you create the quotation, and on the one-shot call.
Step 2: Select a Product and Package
Each product contains packages with benefit tiers, coverage amounts, and premium rates. Note the packageId you want.
/products/life/{productId}Playground
Authorization
Variables
Flow A / C: Quote, then issue
1. Create a quotation
Request body includes:
packageId— Selected packageclientId— Client's IDstartDate— Policy start datepolicyHolder— Policyholder detailsnextOfKin— Next of kin informationbeneficiaries— List of beneficiariesbeneficiaryAddonAmmount— Additional beneficiary coverage amount
The response contains the quoteId.
/quotations/{quoteId}/lifePlayground
Authorization
Variables
2. Issue it
Send reference plus mobileMoneyAccountNumber or cardDetails for the prepaid path (flow A), or reference alone if your account settles externally (flow C).
/policies/life/{quoteId}/issuePlayground
Authorization
Variables
Body
3. Poll, if you paid through the gateway
On flow A the response is Pending until the payer approves on their handset. The policy is issued when the payment confirms, and the transaction status carries it.
/payments/transactions/{reference}/statusPlayground
Authorization
Variables
The generic POST /payments/{quoteId}/pay is an alternative to step 2 for the prepaid path — it also issues the policy on confirmation. Use one or the other.
/payments/{quoteId}/payPlayground
Authorization
Variables
Body
Flow B: Instant issue and pay (prepaid)
Quote, issue and initiate payment in a single call. clientId, packageId, startDate and reference are required.
/policies/life/instant-issuePlayground
Authorization
Body
One call, not instant settlement
The policy is created immediately but mobile money settles asynchronously. Poll GET /payments/transactions/{reference}/status or handle the webhook before you treat the sale as complete.
Policy Documents
/policies/life/{policyId}/certificatePlayground
Authorization
Variables
Policy Renewal
Renewal collects the premium in the same call.
/policies/life/{quoteId}/renew/payPlayground
Authorization
Variables
Body
View Life Policies
/policies/life/{policyId}