Skip to main content

​
Overview

The halal.sh API screens public equities against AAOIFI Standard No. 21 (2021 Revision) — the most widely adopted Shariah screening standard for equities. Every determination is based on two categories of screens: business activity and financial ratios.

​
Business activity screen

The first screen evaluates whether the company’s core business is permissible under Islamic law.
ResultMeaning
passCore business is permissible (e.g., technology, healthcare, manufacturing)
failCore business involves prohibited activities (e.g., conventional banking, gambling, alcohol production)
Companies with permissible core businesses that have minor exposure to questionable activities (e.g., a retailer that sells alcohol, a defense contractor) receive a pass with concerns noted in the response.

​
Financial ratio screens

Three financial ratios are evaluated against thresholds defined by AAOIFI Standard 21:
ScreenFormulaThresholdWhat it measures
Debt to market capTotal interest-bearing debt / 12-month avg market cap≤ 30%Leverage from conventional debt
Prohibited revenue(Interest income + other prohibited income) / Total revenue (TTM)≤ 5%Income from prohibited sources (interest, gambling, alcohol, etc.)
Cash & receivables to market cap(Cash + receivables) / 12-month avg market cap≤ 30%Concentration of interest-bearing assets

​
Market cap basis

AAOIFI Standard 21 specifies the use of 12-month trailing average market capitalization as the denominator for debt and cash ratios. This smooths out short-term price volatility. When 12-month average data is insufficient (e.g., recent IPOs), the API falls back to spot market cap and signals this in the confidence score and extraction_metadata.

​
Trailing twelve months (TTM)

Revenue and interest income use trailing twelve months (TTM) — the most recent annual filing plus subsequent quarterly filings. This ensures the most current picture of the company’s income.

​
Determination logic

IF business_activity == fail:
  → non-compliant (regardless of ratios)

IF all three financial ratios pass:
  → compliant

IF any financial ratio fails:
  → non-compliant

​
Confidence score

Every determination includes a confidence score (0–1.0) reflecting data quality:
RangeLevelMeaning
0.85–1.0HighRecent filings, clean extraction, validated data
0.70–0.84MediumMinor data gaps or older filings
Below 0.70LowSignificant estimation, missing data, or stale filings
Confidence penalties are applied for:
  • Stale filings (>180 days since last filing)
  • Extraction fallbacks used (e.g., component sum instead of primary fields)
  • Missing XBRL data requiring estimation
  • Recent IPO with limited price history

​
Purification

When a compliant company has minor prohibited income (e.g., interest on cash deposits), shareholders must purify that portion of their dividends by donating it to charity. The API returns:
  • purification.required — whether purification is needed
  • purification.percentage — the percentage of dividends to purify (based on prohibited income / total revenue)

​
Auto-analysis

If you query a stock that hasn’t been analyzed yet, the API automatically queues analysis and returns status: "pending". Poll the same endpoint — analysis typically completes within a few minutes. 
{
  "data": {
    "symbol": "PLTR",
    "name": "Palantir Technologies Inc.",
    "determination": { "status": "pending" }
  },
  "meta": {
    "request_id": "req_xyz789",
    "retry_after": 120
  }
}
Once analysis completes, the same endpoint returns the full compliance determination with screens, ratios, and provenance.

​
Data sources

All financial data is extracted from SEC filings (10-K, 10-Q, 20-F, 40-F) via XBRL structured data. Market data comes from Polygon.io. The API response traces every number back to its source filing and XBRL tag.