Overview
The halal.sh API screens public equities against AAOIFI Shari’ah Standard No. 21 (2021 Revision), identified everywhere asaaoifi-ss21 and versioned as aaoifi-ss21@2026.1. Every determination on an operating company rests on two kinds of screen:
Business activity
Is the company’s core business permissible? A qualitative
pass/fail.Financial ratios
Three numeric screens — debt, cash, and prohibited revenue — each compared against an AAOIFI threshold.
Business-activity screen
The first screen evaluates whether the company’s core business is permissible. Unlike the financial screens, it is qualitative — there is no ratio.
A passing company can still carry
concerns — activities worth awareness that don’t, on their own, fail the screen (e.g. a retailer with incidental alcohol sales). The screen also returns the reported business segments behind the result, so you can see what the company actually does and how prohibited-income exposure breaks down by line of business:
revenue_percentage, a qualitative prohibited_revenue_impact (negligible, minor, major), and its revenue significance. The list is empty when segment data isn’t available.
Financial-ratio screens
Three ratios are evaluated against AAOIFI thresholds. The screen keys are exactlydebt_to_market_cap, cash_to_market_cap, and prohibited_revenue.
Each financial screen is the same shape — a
result, the calculated value, the threshold, the comparison operator, and a buffer:
prohibited_revenue can be not_applicable. AAOIFI’s prohibited-income screen (Rule 3/4/4) measures incidental prohibited income for a company whose core business is permissible. When the core business is itself non-permissible (a bank, casino, conventional lender, dedicated entertainment producer, etc.), the business_activity screen already decides, so prohibited_revenue.result is not_applicable (deferred to business activity) with value and buffer set to null. Such a stock is still non-compliant, and its debt_to_market_cap / cash_to_market_cap ratios are reported normally — a non-permissible business with a clean balance sheet shows those passing while failing on business_activity.Market-cap basis
AAOIFI Standard 21 uses market capitalization as the denominator for the debt and cash ratios. The methodology’s calculation basis is reported asmarket_capitalization by the methodology endpoint.
Trailing twelve months (TTM)
Theprohibited_revenue numerator and denominator use trailing twelve months — the most recent annual filing plus any subsequent quarterly filings — so the income picture stays current. The exact filing set behind a determination is reported in filing (with a deterministic hash).
Walking through a /compliance response
determination
The verdict: status (compliant, non-compliant, or pending), a confidence score from 0 to 1, and a Markdown explanation.
screens
The four screens keyed by name: business_activity, debt_to_market_cap, cash_to_market_cap, and prohibited_revenue. Every screen reports its outcome as result: "pass" | "fail", or not_applicable where the methodology does not apply the screen. A pooled vehicle carries a fifth key, structural.
revenue
The full revenue breakdown: total, the permissible and prohibited splits (amount plus percentage), and a per-category breakdown of prohibited revenue (interest income, gambling, alcohol, weapons, tobacco, adult entertainment) in the reporting currency. other holds prohibited revenue in none of those, such as a conventional bank’s underwriting, card and deposit fees or a music streaming service, so the categories sum to the prohibited amount. A category other than interest income is filled only when the analysis recorded it separately; otherwise that revenue is in other.
purification
A compliant company can still earn a little prohibited income, typically interest on cash, and a shareholder gives that part away. purification.required flags whether any applies, and purification.percentage is the company’s prohibited-income rate (prohibited revenue ÷ total revenue). The method halal.sh applies is AAOIFI Standard 21, clause 3/4/6/4: the company’s prohibited income divided by its shares outstanding, times the shares held at the end of its financial period, whether or not a dividend was paid. That per-share figure needs the share count and is on the stock page and the purification calculator; the rate here is its input, never a multiplier for market value. purification.amount_per_1000 expresses the rate per 1,000 units of dividends received, for tooling that works from distributions.
stability
A quick read on how likely the status is to change: a rating of stable, watch, or borderline, plus drivers explaining why. See Stability metrics for the full signal in the Evidence Packet.
filing
The filing set behind the determination — a human-readable summary, a deterministic hash for reproducibility, and the individual filings with their accession numbers.
Pooled vehicles: the structural screen
A gold trust holds bars in a vault; a physical-metal ETC is a secured note over allocated bars; a futures pool holds contracts. None of them has a debt ratio worth reading (the stored ratios are zero by construction), so the API decides them on the structure of the vehicle, under the standard the ETF taxonomy routes them to:
Such a response keeps the documented shape. The three ratio screens are present with
result: "not_applicable" and value: null, business_activity reports as usual, and screens.structural carries the checklist:
result is one of four values, and each carries an evidence obligation:
key matches metric on the methodology’s screen definitions, so GET /methodologies/aaoifi-ss57 is the reference for what each criterion tests. revenue and purification report the vehicle’s own figures (zero for a vehicle that holds only metal), and the Evidence Packet carries one screen per criterion with the same quotes.
Confidence
determination.confidence is a 0–1 score reflecting data quality. The Evidence Packet’s confidence_detail shows how it was built: the base confidence and each penalty or boost applied.
When a stock hasn’t been analysed
If a stock has no analysis yet,determination.status is pending and screens, revenue, purification, stability, and filing are all null.
pending simply means the instrument has not been analysed yet — the endpoint does not queue analysis. Treat any unknown future status value as pending.When we analysed it and hold the verdict back
A few instruments staypending because we worked them and the methodology does not allow a verdict yet, or because we hold no usable data for them. For these, determination.withheld says which, and when we recorded it. On every other response it is null.
analysed: true means we screened the instrument from its primary documents: an Islamic bank whose liquidity screen straddles the 30% limit on securities it does not classify (screen_unresolved), or an issuer that publishes no figure for an input a screen needs (input_not_disclosed). analysed: false means we could not screen it at all (no_data_source, data_out_of_date, data_not_credible). GET /instruments/{symbol} carries the same object as compliance.withheld.
Ethical screening
Separate from AAOIFI financial compliance, the instrument resource carries anethical_screening object flagging involvement in areas such as occupation or weapons, aggregated from independent research sources. It reports a status (flagged, cleared, or not_screened), a worst-case severity, and the flagged_areas with their per-area severities. This is an independent signal — a stock can be AAOIFI-compliant and still be flagged here, or vice versa.