S
ShariahAPI DocsOpenAPI JSON
Back to Home

API Reference

Screen any financial asset for Shariah compliance using AAOIFI or SC Malaysia standards.

Base URL

https://your-deployment.vercel.app/api

Demo Key

sk_demo_shariahapi_12345

Authentication

All endpoints require an API key. Pass it via any of:

Authorization Header (preferred)

Authorization: Bearer sk_demo_shariahapi_12345

X-API-Key Header

X-API-Key: sk_demo_shariahapi_12345

Query Parameter

GET /api/asset/AAPL?api_key=sk_demo_shariahapi_12345
POST/api/screen

Screen an asset for Shariah compliance. Returns detailed reasoning, compliance score, and purification guidance.

Request Body

{
  "asset": {
    "symbol": "AAPL",
    "name": "Apple Inc.",
    "sector": "Technology",
    "businessActivities": ["smartphones", "software", "digital services"],
    "financials": {
      "totalAssets": 352583000000,
      "totalDebt": 111088000000,
      "cashAndEquivalents": 29965000000,
      "totalRevenue": 383285000000,
      "nonHalalRevenue": 0,
      "accountsReceivable": 29508000000,
      "interestIncome": 3750000000,
      "fiscalYear": 2023
    }
  },
  "methodology": "AAOIFI"
}

Response

{
  "success": true,
  "data": {
    "assetId": "AAPL",
    "symbol": "AAPL",
    "status": "NON_COMPLIANT",
    "compliant": false,
    "score": 65,
    "screenedAt": "2026-03-22T00:00:00.000Z",
    "reasons": [
      {
        "code": "DEBT_FAIL",
        "rule": "Debt Ratio (AAOIFI)",
        "description": "Debt ratio 31.5% <= 33.0% threshold",
        "severity": "INFO",
        "value": 31.5,
        "threshold": 33,
        "passed": true
      }
    ],
    "purification": { "required": false },
    "summary": "Asset passes all AAOIFI screening criteria.",
    "methodology": "AAOIFI",
    "version": "1.0.0"
  }
}
GET/api/asset/:id

Retrieve the latest screening result for an asset. Add ?history=true to get the full screening history.

Response

// GET /api/asset/AAPL
{
  "success": true,
  "data": { /* ScreeningResult */ }
}

// GET /api/asset/AAPL?history=true
{
  "success": true,
  "data": [ /* ScreeningResult[] */ ]
}
GET/api/compliance-history

Get compliance change events. Shows what changed, when, and why.

Response

// GET /api/compliance-history?assetId=AAPL&limit=10
{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "assetId": "AAPL",
      "changedAt": "2026-03-22T00:00:00.000Z",
      "previousStatus": "COMPLIANT",
      "newStatus": "NON_COMPLIANT",
      "changedRules": ["DEBT_FAIL"],
      "triggeredBy": "api_screen"
    }
  ]
}
POST/api/keys

Create a new API key for your tenant.

Request Body

{ "name": "Production Key", "plan": "STARTER" }

Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "key": "sk_live_...",
    "name": "Production Key",
    "tenantId": "tenant_demo",
    "plan": "STARTER",
    "rateLimit": 1000,
    "createdAt": "2026-03-22T00:00:00.000Z",
    "isActive": true
  }
}

Reason Codes

CodeSeverityDescription
BUS_PROHIBITEDFAILEngages in absolutely prohibited business activity
BUS_DOUBTFULWARNINGOperates in a doubtful sector requiring further review
BUS_PASSINFONo prohibited business activities detected
DEBT_FAILFAILDebt ratio exceeds 33% of total assets (AAOIFI)
DEBT_PASSINFODebt ratio within 33% threshold
CASH_FAILFAILCash & receivables exceed 33% of total assets
CASH_PASSINFOCash & receivables within threshold
INCOME_FAILFAILNon-halal income exceeds 5% of total revenue
INCOME_PASSINFONon-halal income within 5% threshold
INTEREST_FAILFAILInterest income exceeds 5% of total revenue
INTEREST_PASSINFOInterest income within threshold