Introduction

One request returns a stock’s Shariah compliance status under AAOIFI Shari’ah Standard No. 21, with the three ratio screens and 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"

With the screens and filings behind each determination, and the date we screened it, you can show your users why a stock passes or fails.

What you can do

Screen stocks

Get the compliance status, financial-ratio screens, and business-activity screen for any analyzed company, with a stability rating that flags a stock close to a limit.

Evidence Packets

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

Analyze ETFs

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

Track history

Follow a company’s compliance determination across filing periods.

Base URL

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

https://api.halal.sh/v1

Authentication

Authenticate each request with an API key in the X-API-Key header. Create a key: sandbox keys are free and instant. See Authentication for rate limits and the sandbox.

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 and thresholds are decimals (0.020616 is 2.06%, 0.30 is 30%). The example is trimmed: every field is in Get compliance screening. methodology names the screening rules and their version, and the version changes whenever the rules do. See Methodology versioning.

Client libraries

The API is plain REST, so any HTTP client works:

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

Analyze ETFs

Track history

Base URL

Authentication

The response

Client libraries

Get started

Support

​What you can do

Screen stocks

Evidence Packets

Analyze ETFs

Track history

​Base URL

​Authentication

​The response

​Client libraries

Get started

Support

What you can do

Base URL

Authentication

The response

Client libraries