Insurance Management API
Complete REST API for managing insurance operations
📖 Introduction
The Lion Insurance Management System API provides programmatic access to manage customers, policies, claims, and financial transactions.
🔒 Secure
JWT authentication with role-based access
📊 Comprehensive
Complete policy lifecycle management
🔔 Real-time
Webhook notifications for events
💰 Multi-currency
Support for ZMW and USD
🔐 Authentication
All requests require JWT authentication. Obtain a token by providing credentials.
Request
{
"username": "api_user",
"password": "your_password",
"environment": 1
}Response
{
"status": "success",
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
"expires_in": 3600,
"token_type": "Bearer"
}
}Authorization: Bearer YOUR_TOKEN
⚠️ Error Handling
HTTP Status Codes
| Code | Description |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
| 422 | Validation Error |
| 500 | Server Error |
Error Format
{
"status": "error",
"message": "Validation failed",
"error_code": "VAL_001",
"errors": ["Field is required"]
}👥 Insured Management
Create new customer
{
"f_name": "John",
"l_name": "Doe",
"phone": "+260971234567",
"nrc": "123456/78/9",
"address": "Plot 123, Lusaka",
"email": "john@example.com"
}Get customer details
Search customers
📋 Policy Management
Create new policy
{
"insured_id": 12345,
"company_id": 1,
"prod_id": 1,
"currency": 1,
"start_date": "2025-11-07",
"end_date": "2026-11-07",
"vehicle_reg": "ABC1234",
"sum_insured": "50000",
"basic_premium": "2500.00",
"levy": "375.00"
}Get policy details
Approve policy
Cancel policy
🔧 Claims Management
File new claim
{
"insured_id": 12345,
"policy_id": 5678,
"vehicle_reg": "ABC1234",
"date_of_loss": "2025-11-05",
"claim_amount": 5000,
"currency": 1
}Upload claim documents
Content-Type: multipart/form-data
Approve claim
📄 Document Generation
Generate policy certificate PDF
{
"policy_id": 5678,
"format": "pdf"
}Generate receipt PDF
Generate account statement
💰 Financial Transactions
Record payment receipt
{
"account_code": "ACC001",
"policy_id": 5678,
"currency": 1,
"paid_amount": "2875.00",
"paid_date": "2025-11-07",
"payment_mode": "Bank Transfer",
"reference": "BNK123456"
}Get account statement
Get current exchange rates
🔔 Webhooks
Receive real-time notifications when events occur.
{
"url": "https://your-system.com/webhook",
"events": ["policy.created", "claim.approved"],
"secret": "your_webhook_secret"
}Supported Events
Webhook Payload
{
"event": "policy.created",
"timestamp": "2025-11-07T10:30:00Z",
"data": {
"policy_id": 5678,
"policy_number": "POL-2025-001"
}
}⏱️ Rate Limits
| Type | Limit |
|---|---|
| Authentication | 10/minute |
| Standard API | 1000/hour |
| Document Generation | 50/hour |
| File Uploads | 20/hour |
💻 Code Examples
PHP Client
$ch = curl_init('https://api.lioninsurance.co.zm/api/v1/insured');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer YOUR_TOKEN'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'f_name' => 'John',
'l_name' => 'Doe',
'phone' => '+260971234567',
'email' => 'john@example.com'
]));
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
print_r($data);JavaScript/Node.js
const axios = require('axios');
const api = axios.create({
baseURL: 'https://api.lioninsurance.co.zm/api/v1',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_TOKEN'
}
});
// Create insured
const response = await api.post('/insured', {
f_name: 'John',
l_name: 'Doe',
phone: '+260971234567',
email: 'john@example.com'
});
console.log(response.data);Python
import requests
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_TOKEN'
}
data = {
'f_name': 'John',
'l_name': 'Doe',
'phone': '+260971234567',
'email': 'john@example.com'
}
response = requests.post(
'https://api.lioninsurance.co.zm/api/v1/insured',
headers=headers,
json=data
)
print(response.json())Database Queries
-- Create Insured
INSERT INTO insured
(insured_code, f_name, l_name, phone, nrc, address,
email, created_date, created_by, blacklist)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0);
-- Get Insured with Stats
SELECT i.*,
COUNT(DISTINCT p.id) as total_policies,
COUNT(DISTINCT c.id) as total_claims,
COALESCE(SUM(CASE WHEN pb.currency = 1
THEN pb.balance ELSE 0 END), 0) as balance_zmw
FROM insured i
LEFT JOIN policies p ON i.id = p.insured_id
LEFT JOIN claims c ON i.id = c.insured_id
LEFT JOIN policy_balance pb ON i.id = pb.insured_id
WHERE i.id = ?
GROUP BY i.id;
-- Create Policy
INSERT INTO policies
(insured_id, user_id, company_id, policy_number,
prod_id, currency, start_date, end_date,
sum_insured, basic_premium, levy, created_date,
approved, outstanding)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, ?);
-- Create Receipt
INSERT INTO receipts
(receipt_number, account_code, policy_id, currency,
paid_amount, paid_date, reference, payment_mode,
user_id, status)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 1);
-- Update Policy Balance
UPDATE policy_balance
SET balance = balance - ?, update_date = NOW()
WHERE policy_id = ?;