Insurance Management API

Complete REST API for managing insurance operations

https://api.lioninsurance.co.zm/api/v1

📖 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.

POST /auth/token

Request

{
  "username": "api_user",
  "password": "your_password",
  "environment": 1
}

Response

{
  "status": "success",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "expires_in": 3600,
    "token_type": "Bearer"
  }
}
Using the Token: Include in all requests:
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

POST /insured

Create new customer

{
  "f_name": "John",
  "l_name": "Doe",
  "phone": "+260971234567",
  "nrc": "123456/78/9",
  "address": "Plot 123, Lusaka",
  "email": "john@example.com"
}
GET /insured/{id}

Get customer details

GET /insured/search?q=name

Search customers

📋 Policy Management

POST /policies

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 /policies/{id}

Get policy details

POST /policies/{id}/approve

Approve policy

POST /policies/{id}/cancel

Cancel policy

🔧 Claims Management

POST /claims

File new claim

{
  "insured_id": 12345,
  "policy_id": 5678,
  "vehicle_reg": "ABC1234",
  "date_of_loss": "2025-11-05",
  "claim_amount": 5000,
  "currency": 1
}
POST /claims/{id}/documents

Upload claim documents

Content-Type: multipart/form-data

POST /claims/{id}/approve

Approve claim

📄 Document Generation

POST /documents/policy-certificate

Generate policy certificate PDF

{
  "policy_id": 5678,
  "format": "pdf"
}
POST /documents/receipt

Generate receipt PDF

POST /documents/statement

Generate account statement

💰 Financial Transactions

POST /receipts

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 /accounts/{code}/statement

Get account statement

GET /exchange-rates

Get current exchange rates

🔔 Webhooks

Receive real-time notifications when events occur.

POST /webhooks/subscribe
{
  "url": "https://your-system.com/webhook",
  "events": ["policy.created", "claim.approved"],
  "secret": "your_webhook_secret"
}

Supported Events

insured.created - New customer created
policy.created - New policy issued
policy.approved - Policy approved
claim.created - New claim filed
receipt.created - Payment received

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
Rate Limit Headers: Each response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

💻 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 = ?;