Key Concepts

Authentication

Connect to the API using the authentication token provided during signup. Every API call must include a valid API key in the Authorization request header. See Authentication for details.

Policyholders

A policyholder is the entity (individual or corporate) that holds an insurance policy. You must create a policyholder before issuing any policy. The returned id is used in all subsequent API calls.

Quotation Inquiry

A quotation enables you to obtain quick premium estimates on products from partner insurers. This lets you check premiums before committing to a policy. Quotations can be created for motor, travel, life, and general insurance.

Issuance flows

There is more than one way to put a risk on cover, and two independent choices decide which endpoints you call.

Do you raise a quotation first? A quotation gives you a quoteId the customer can accept, and it persists. Instant issue skips it — one call carries the client, the risk and the product.

Who collects the premium? Either Inshuwa collects it through a gateway (prepaid), or your account settles it another way (PayLater or external settlement). You choose per request by sending payment details or leaving them out, but only within what your account is configured for.

Paying a quotation issues it

On the prepaid path there is no separate "issue" call. POST /payments/{quoteId}/pay initiates the collection and issues the policy automatically once the payment confirms. Poll the reference — the transaction status carries the issued policy once it settles.

The four flows

	Prepaid — Inshuwa collects	Account-settled — PayLater / external
Quotation first	A. quotation → POST /payments/{quoteId}/pay → issued on confirmation	C. quotation → POST .../{quoteId}/issue → issued immediately
Instant (one call)	B. POST .../instant/issue/pay → issued on confirmation	D. POST .../instant/issue → issued immediately

Flow A is for a customer who accepts a price before paying. Flow B is for high-volume selling where no quotation is ever shown — USSD, an app checkout, an agent tool. Flows C and D are the same two shapes for partners who do not settle through the platform: Inshuwa bills you (PayLater), or you collect from the customer and remit to the insurer yourself (external settlement).

Prepaid flows always settle asynchronously — mobile money needs the payer to approve on their handset, so the response is Pending and the policy is issued when the callback lands. "One call" is about the number of requests you make, not how fast the money moves.

How the settlement mode is chosen

For any issuing endpoint the API resolves it in this order:

1. mobileMoneyAccountNumber present → mobile money collection.
2. cardDetails present, or your account is configured for external settlement → external.
3. Your account is configured for PayLater → PayLater.

So the same endpoint can be prepaid or account-settled depending on what you send. If you send nothing and your account has no external or PayLater arrangement, the request is rejected.

Which flow each product supports

Product	A. Quote, prepaid	B. Instant, prepaid	C. Quote, account-settled	D. Instant, account-settled
Motor	✅	✅	✅	✅
Life	✅	✅	✅	—
Travel	✅	✅	✅	—
General	✅	—	✅	✅
Credit life	— rates are the insurer's	✅ prepaid policy	—	✅ remittance policy

On life and travel there is one issue endpoint per quotation, POST /policies/{life\|travel}/{quoteId}/issue, and it covers both A and C: send payment details for prepaid, omit them for account-settled. On general the issue endpoints are always account-settled — pay the quotation through /payments/{quoteId}/pay for the prepaid path.

Renewals and extensions follow the same split: /renew and /extend apply the change on your account's terms; /renew/pay and /extend/pay collect the premium through the gateway.

Payments

Payment processing enables premium payments for policies. Supported payment methods:

• Mobile Money — Airtel Money, MTN Mobile Money, Zamtel Kwacha
• Card — Visa and Mastercard
• Mobile Banking — Local banking platforms

Pagination

List endpoints return paginated results. Use PageNumber and PageSize query parameters to navigate pages. Responses include totalItems, pageSize, pageNumber, and totalPages.

Documents

After issuing a policy, you can download:

• Policy Schedule — Detailed policy terms
• Insurance Certificate — Proof of insurance
• Payment Receipt — Proof of premium payment