Islamic Finance Guide

Sukuk and Takaful API guide

Query curated GCC Sukuk reference records and request an indicative Takaful contribution estimate using the authenticated finance APIs.

Authentication and scopes

Send your key as a Bearer token. Sukuk requests require finance:sukuk; Takaful requests require finance:takaful. Keep API keys on your server and grant only the scopes your application needs.

Sukuk reference API

Use GET /api/v1/sukuk/list. Filters include country, type, status, sector, currency, min_size, and max_size. The type filter is a Sukuk structure such as Ijara or Wakala; there is no rating filter. Use id for a single record or types=true for structure definitions.

bash
# List active UAE Ijara sukuk in the Banking sector
curl "https://khaleejiapi.dev/api/v1/sukuk/list?country=AE&type=Ijara&status=active&sector=Banking" \
  -H "Authorization: Bearer $KHALEEJI_API_KEY"
 
# Return the supported Sukuk structure definitions
curl "https://khaleejiapi.dev/api/v1/sukuk/list?types=true" \
  -H "Authorization: Bearer $KHALEEJI_API_KEY"
 
# Look up one record by its id
curl "https://khaleejiapi.dev/api/v1/sukuk/list?id=sukuk-sa-sovereign-2030" \
  -H "Authorization: Bearer $KHALEEJI_API_KEY"

Indicative Takaful estimate

Use GET /api/v1/takaful/calculate with required type and positive coverage. Optional parameters include currency, country, model, age, dependents, vehicle_age, property_type, trip_days, destination, employees, and industry. Supported types are health, motor, property, life, travel, and business. Use models=true to inspect available models and supported values.

bash
curl "https://khaleejiapi.dev/api/v1/takaful/calculate?type=health&coverage=150000&currency=AED&country=AE&model=wakalah_mudarabah&age=35&dependents=1" \
  -H "Authorization: Bearer $KHALEEJI_API_KEY"
 
# Return available models, types, and supported countries
curl "https://khaleejiapi.dev/api/v1/takaful/calculate?models=true" \
  -H "Authorization: Bearer $KHALEEJI_API_KEY"

Node.js

typescript
const apiKey = process.env.KHALEEJI_API_KEY
const baseUrl = "https://khaleejiapi.dev/api/v1"
 
async function get(path: string) {
  const response = await fetch(`${baseUrl}${path}`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  })
  if (!response.ok) throw new Error(`API returned ${response.status}`)
  return (await response.json()).data
}
 
const sukuk = await get("/sukuk/list?country=AE&type=Ijara&status=active")
const takaful = await get("/takaful/calculate?type=health&coverage=150000&currency=AED&country=AE&age=35")
console.log(sukuk.summary.total, takaful.estimate.annualContribution)

Python (standard library)

python
import json
import os
from urllib.parse import urlencode
from urllib.request import Request, urlopen
 
BASE_URL = "https://khaleejiapi.dev/api/v1"
 
def get(path, params):
    url = f"{BASE_URL}{path}?{urlencode(params)}"
    request = Request(url, headers={"Authorization": f"Bearer {os.environ['KHALEEJI_API_KEY']}"})
    with urlopen(request, timeout=10) as response:
        return json.load(response)["data"]
 
sukuk = get("/sukuk/list", {"country": "AE", "type": "Ijara", "status": "active"})
takaful = get("/takaful/calculate", {
    "type": "health", "coverage": 150000, "currency": "AED", "country": "AE", "age": 35
})
print(sukuk["summary"]["total"], takaful["estimate"]["annualContribution"])

Response data

text
Sukuk list: data.sukuk[], data.summary, data.filters
Sukuk lookup: data.sukuk, data.structureType
Takaful estimate: data.estimate, data.model, data.adjustments, data.regulator, data.disclaimer
Takaful models: data.models[], data.types[], data.countries[]