Motor Insurance

This guide walks you through issuing motor insurance policies using the Inshuwa API.

Overview

The motor insurance workflow involves these steps:

1. Create a policyholder and register their vehicle
2. Select an insurance product
3. Generate a quotation (optional)
4. Pay the premium
5. Issue the policy
6. Download policy documents

Step 1: Create a Policyholder and Add Vehicles

Register the client and their vehicle:

POST /api/v1/policyholders/individuals
POST /api/v1/policyholders/{id}/vehicles

Provide personal information (name, ID number, phone), vehicle details (make, model, year, registration number, chassis number), and the motorRiskCategoryId.

Get available risk categories:

GET /api/v1/policies/motor/risk-categories

Step 2: Select an Insurance Product

Browse available motor products:

GET /api/v1/products/motor

The response includes thirdPartyRates and comprehensiveRates arrays. Note the product id for use when creating a quotation.

Step 3: Generate a Quotation

Create a motor quotation:

POST /api/v1/quotations/motor

Or compare premiums across multiple products:

POST /api/v1/quotations/motor/comparison

The response contains a quoteId used in subsequent steps.

Step 4: Pay the Premium

Initiate payment for the quotation:

POST /api/v1/payments/{quoteId}/pay

Check payment status:

GET /api/v1/payments/transactions/{reference}/status

Understanding Cover Duration

Each motor product has a durationType field returned by GET /api/v1/products/motor. This determines how the duration value you send when issuing a cover is interpreted.

durationType	What to send as duration	Examples
Days	Number of days	7 = 7 days, 30 = 30 days
Months	Number of months	1 = 1 month, 6 = 6 months, 12 = 12 months
Years	Number of years	1 = 1 year, 2 = 2 years
Quarters	Number of quarters	1 = 3 months, 2 = 6 months, 3 = 9 months, 4 = 12 months

TIP

Always check durationType on the product before issuing. Send the duration field in your issue/pay request with a value that matches the rules above.

Example: If the product's durationType is Months and you want 3 months of cover, send "duration": 3. If durationType is Quarters and you want 6 months of cover, send "duration": 2 (2 quarters = 6 months).

Step 5: Issue the Policy

Once payment is confirmed, issue the policy:

POST /api/v1/policies/motor/{quoteId}/issue

Include the duration field in the request body based on the product's durationType (see Understanding Cover Duration).

Instant Issue (One Step)

To create, pay, and issue in a single API call:

POST /api/v1/policies/motor/instant/issue/pay

Include the duration field based on the product's durationType.

Step 6: Download Documents

After policy issuance, download documents:

Document	Endpoint
Policy Schedule	GET /api/v1/policies/motor/{id}/documents/schedule
Insurance Certificate	GET /api/v1/policies/motor/{id}/documents/certificate
Payment Receipt	GET /api/v1/policies/motor/{id}/documents/receipt

Policy Renewal

Renew an existing motor policy:

POST /api/v1/policies/motor/{policyId}/renew/pay

Policy Extension

Extend a motor policy's coverage period:

POST /api/v1/policies/motor/{policyId}/extend/pay