Introduction

One request tells you whether a stock is Shariah compliant under AAOIFI Shari’ah Standard No. 21, and returns the three ratio screens with their values and thresholds, the business-activity screen, the purification percentage, and the filings the numbers came from:

curl https://api.halal.sh/v1/instruments/AAPL/compliance \
  -H "X-API-Key: hsh_sandbox_your_key"

The verdict is the least of it. halal.sh returns every screen, ratio, threshold and source filing behind each determination, so you can show your own users why, not just what. Every number traces back to the filing it came from, and every determination carries the date it was screened.

What you can do

Screen stocks

Get the compliance status, financial-ratio screens, and business-activity screen for any analysed company.

Evidence Packets

Pull an audit-ready bundle with full provenance: each screen’s calculation, the values it used and the filing they came from.

Analyse ETFs

Get an ETF’s Shariah purity and a per-holding compliance breakdown.

Track history

Follow a company’s compliance determination across filing periods, with a stability signal.

Why halal.sh

	halal.sh	Typical provider
Individual screen results (debt, revenue, liquidity)	Yes	Verdict only
Filing-level provenance (filing, accession number, values used)	Yes	No
Versioned methodology	Yes	No
Stability metrics (threshold distance, trend)	Yes	No

Base URL

All requests use a single base URL, with the version in the path:

https://api.halal.sh/v1

Authentication

Every request is authenticated with an API key passed in the X-API-Key header. Create a key; sandbox keys are free and instant. See Authentication for details.

The response

The request above returns:

{
  "data": {
    "symbol": "AAPL",
    "name": "Apple Inc.",
    "methodology": "aaoifi-ss21@2026.1",
    "as_of": "2026-05-03T08:10:09.622Z",
    "determination": {
      "status": "compliant",
      "confidence": 0.95,
      "explanation": "Apple Inc. (AAPL) is **COMPLIANT** with AAOIFI Standard 21…"
    },
    "screens": {
      "business_activity": {
        "result": "pass",
        "activities": [],
        "prohibited_activities": [],
        "concerns": []
      },
      "debt_to_market_cap":  { "result": "pass", "value": 0.020616, "threshold": 0.30, "operator": "<=", "buffer": 27.94 },
      "cash_to_market_cap":  { "result": "pass", "value": 0.035677, "threshold": 0.30, "operator": "<=", "buffer": 26.43 },
      "prohibited_revenue":  { "result": "pass", "value": 0.010120, "threshold": 0.05, "operator": "<=", "buffer": 3.99 }
    },
    "purification": { "required": true, "percentage": 1.012 }
  },
  "meta": {
    "request_id": "req_C7F0xXgmN",
    "as_of": "2026-05-03T08:10:10.000Z",
    "methodology": "aaoifi-ss21@2026.1"
  }
}

Ratios are decimals (0.020616 = 2.06%); thresholds are decimals too (0.30 = 30%). The full response also includes revenue, stability, and filing. See Get compliance screening.

Client libraries

Official SDKs are on the way. Until then, the API is plain REST and works with any HTTP client:

const res = await fetch(
  "https://api.halal.sh/v1/instruments/AAPL/compliance",
  { headers: { "X-API-Key": process.env.HALALSH_API_KEY } }
);
const { data } = await res.json();
console.log(data.determination.status); // "compliant"

import requests

data = requests.get(
    "https://api.halal.sh/v1/instruments/AAPL/compliance",
    headers={"X-API-Key": API_KEY},
).json()["data"]

print(data["determination"]["status"])  # "compliant"

Get started

Create a key and make your first request in under two minutes.

Support

Questions, or a result that looks off? Get in touch.

Getting Started

Core Concepts

Guides

What you can do

Screen stocks

Evidence Packets

Analyse ETFs

Track history

Why halal.sh

Base URL

Authentication

The response

Client libraries

Get started

Support

​What you can do

Screen stocks

Evidence Packets

Analyse ETFs

Track history

​Why halal.sh

​Base URL

​Authentication

​The response

​Client libraries

Get started

Support

What you can do

Why halal.sh

Base URL

Authentication

The response

Client libraries