Definite Assurance API Documentation

📖 Overview

This API Documentation provides a comprehensive suite of endpoints for managing insurance proposals, clients, products, and payments. All endpoints are secured with vendor authentication and return JSON responses.

Base URL: https://uat.definiteassurance.com/api/v1

                        ⚡ Important: All endpoints require vendor authentication via basic auth headers. The API enforces rate limiting and requires valid requests to be processed sequentially.
                    

🔐 Authentication

All API endpoints are protected using User Authentication (basic auth). Include the authorization header in your requests:

Authorization: Basic <credentials>
Content-Type: application/json

To request test credentials, please email ict@definiteassurance.com.

🔌 API Endpoints

GET /checkClient

🔒 Requires User Auth

Check if a client exists in the system using their identification number.

Query Parameters

IDNumber string REQUIRED

Client identification number

Response

✅ Success (200)

{
  "success": true,
  "FirstName": "John",
  "OtherNames": "Peter",
  "Surname": "Doe",
  "OID": 123
}

200 Client found successfully

404 Client not found in database

POST /createClient

🔒 Requires User Auth

Create a new client in the system with complete details.

Request Body (JSON)

firstName string REQUIRED

Client first name

lastName string REQUIRED

Client last name

otherNames string OPTIONAL

Client other names

phone string REQUIRED

Client phone number

email string REQUIRED

Client email address

idNumber string REQUIRED

Client identification number (unique)

pin string REQUIRED

Client PIN (unique)

Response

✅ Success (200)

{
  "success": true,
  "exists": false,
  "OID": 456
}

200 Client created successfully

409 Client already exists with provided email/ID/PIN

GET /products

🔒 Requires User Auth

Retrieve all available insurance products with their cover options.

Response

✅ Success (200)

{
  "success": true,
  "data": [
    {
      "product": {
        "ProductOID": 3617,
        "ProductDescription": "MOTOR PRIVATE - PORTAL"
      },
      "coverOptions": [
        {
          "CoverOptionOID": 3378,
          "CoverOption": "TPO"
        },
        {
          "CoverOptionOID": 3529,
          "CoverOption": "COMP"
        }
      ]
    }
  ]
}

200 Products retrieved successfully

GET /makes

🔒 Requires User Auth

Retrieve all vehicle makes with their corresponding models.

Response

✅ Success (200)

{
  "success": true,
  "data": [
    {
      "make": {
        "MakeOID": 1,
        "Make": "Toyota"
      },
      "models": [
        {
          "ModelOID": 10,
          "Model": "Corolla"
        }
      ]
    }
  ]
}

GET /calculatePremium

🔒 Requires User Auth

Calculate insurance premium based on vehicle details and cover options.

Query Parameters

sumInsured number REQUIRED

Sum insured value

capacity number REQUIRED

Vehicle seating capacity

tonnage number REQUIRED

Vehicle tonnage

coverPeriod number REQUIRED

Cover period in days

product number REQUIRED

Product OID

coverOption number REQUIRED

Cover option OID

Response

✅ Success (200)

{
  "basicPremium": 5000,
  "grossPremium": 5500,
  "commission": 500,
  "netPremium": 4800
}

GET /checkIntermediary

🔒 Requires User Auth

Check if an intermediary/agent exists using their identification number.

Query Parameters

identification string REQUIRED

Intermediary identification number

Response

✅ Success (200)

{
  "success": true,
  "OID": 789,
  "AgentName": "John Agent",
  "message": "Intermediary with the provided identification number exists."
}

POST /registerIntermediary

🔒 Requires User Auth

Request Body (JSON)

name string REQUIRED

Intermediary full name

email string REQUIRED

Intermediary email

phone string REQUIRED

Intermediary phone number

identification string REQUIRED

Intermediary identification number

krapin string REQUIRED

KRA PIN

Response

✅ Success (200)

{
  "success": true,
  "OID": 789,
  "message": "Intermediary registered successfully"
}

GET /checkPolicy

🔒 Requires User Auth

Check if an active policy exists for a vehicle registration number.

Query Parameters

registration string REQUIRED

Vehicle registration number

Response

✅ Success (200)

{
  "exists": true,
  "ExpiryDate": "2026-12-31",
  "ProposalNo": "PR-2026-1234",
  "OID": 555
}

POST /newproposal

🔒 Requires User Auth

Create a new insurance proposal with complete vehicle and coverage details.

Request Body (JSON)

Client number REQUIRED

Client OID

agent number REQUIRED

Agent/Intermediary OID

CommencementDate string REQUIRED

Policy start date (YYYY-MM-DD)

PaymentInterval number REQUIRED

Payment interval in days

Product number REQUIRED

Product OID

CoverOption number REQUIRED

Cover option OID

Registration string REQUIRED

Vehicle registration number

MakeCode number REQUIRED

Vehicle make OID

ModelCode number REQUIRED

Vehicle model OID

Capacity number REQUIRED

Seating capacity

YOM number REQUIRED

Year of manufacture

SumInsured number REQUIRED

Sum insured amount

ChassisNumber string REQUIRED

Vehicle chassis number

EngineNumber string REQUIRED

Vehicle engine number

Response

✅ Success (200)

{
  "success": true,
  "ProposalNo": "PR-2026-5678",
  "PolicyNo": "DA/047/PRD-001/5678/2026",
  "OID": 999
}

POST /initiatePayment

🔒 Requires User Auth

Initiate payment process for an insurance proposal.

Request Body (JSON)

InsuredItem number REQUIRED

Insured item OID

CommencementDate string REQUIRED

Policy start date

ExpiryDate string REQUIRED

Policy expiry date

Proposal number REQUIRED

Proposal OID

PhoneNumber string REQUIRED

Customer phone number for payment

APIUser string REQUIRED

API user identifier

Response

✅ Success (200)

{
  "success": true,
  "message": "Payment initiated successfully",
  "amount": 5500,
  "transactionId": "TXN123456"
}

⚠️ Error Handling

The API uses standard HTTP status codes to indicate the success or failure of an API request. Errors are returned in JSON format with descriptive messages.

200 Request successful - The request was processed successfully

201 Resource created - A new resource was successfully created

400 Bad request - Invalid parameters or malformed request

401 Unauthorized - Authentication failed or invalid credentials

403 Forbidden - Access denied to the requested resource

404 Not found - Resource does not exist

409 Conflict - Resource already exists

500 Server error - Internal server error occurred

Error Response Format:{
  "success": false,
  "message": "Descriptive error message",
  "errorCode": "ERROR_CODE"
}

💡 Usage Examples

Creating a New Client (cURL)

curl -X POST https://uat.definiteassurance.com/api/v1/createClient \
  -H "Authorization: Basic YOUR_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "otherNames": "Peter",
    "phone": "+254712345678",
    "email": "john@example.com",
    "idNumber": "12345678",
    "pin": "A001B002"
  }'

Creating a New Proposal (JavaScript/Fetch)

fetch('https://uat.definiteassurance.com/api/v1/newproposal', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic YOUR_CREDENTIALS',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    Client: 123,
    agent: 456,
    CommencementDate: '2026-04-22',
    PaymentInterval: 365,
    Product: 3617,
    CoverOption: 3378,
    Registration: 'KAA 123A',
    MakeCode: 1,
    ModelCode: 10,
    Capacity: 5,
    YOM: 2020,
    SumInsured: 1500000,
    ChassisNumber: 'ABC123',
    EngineNumber: 'XYZ789'
  })
})
.then(response => response.json())
.then(data => console.log(data));

Checking Policy Status (Python/Requests)

import requests

headers = {
    'Authorization': 'Basic YOUR_CREDENTIALS',
    'Content-Type': 'application/json'
}

params = {
    'registration': 'KAA 123A'
}

response = requests.get(
    'https://uat.definiteassurance.com/api/v1/checkPolicy',
    headers=headers,
    params=params
)

print(response.json())

🚀 Go Live

                        Production Access: Upon approval of your integration and successful testing in UAT, you will be provided with new production credentials and the production base URL. Please ensure all your integration steps are complete and validated before requesting production access.
                    

Definite Assurance API

📋 Endpoints

📖 Overview

🔐 Authentication

🔌 API Endpoints

✅ Success (200)

✅ Success (200)

✅ Success (200)

✅ Success (200)

✅ Success (200)

✅ Success (200)

✅ Success (200)

✅ Success (200)

✅ Success (200)

✅ Success (200)

⚠️ Error Handling

💡 Usage Examples

Creating a New Client (cURL)

Creating a New Proposal (JavaScript/Fetch)

Checking Policy Status (Python/Requests)

🚀 Go Live