Compliance screening

Overview

The halal.sh API screens public equities against AAOIFI Shari’ah Standard No. 21 (2021 Revision), identified everywhere as aaoifi-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.

A stock is compliant only when the business-activity screen passes and all three financial ratios pass. A pooled vehicle we screen as a stock (a gold or silver trust, a London-listed physical-metal ETC, a futures pool) has no operating business for the ratios to measure, so we decide it on a structural checklist instead, under a different methodology. See Pooled vehicles below.

Business-activity screen

The first screen is a qualitative judgment of whether the company’s core business is permissible. It has no ratio.

`result`	Meaning
`pass`	Core business is permissible (e.g. technology, healthcare, manufacturing).
`fail`	Core business involves prohibited activities (e.g. conventional banking, gambling, alcohol production).

A passing company can still have concerns: activities that do not fail the screen on their own but are worth knowing about, such as a retailer’s incidental alcohol sales. The screen also returns the company’s reported business segments, so you can see what it does and how its prohibited-income exposure splits by line of business:

{
  "result": "pass",
  "activities": ["Consumer Electronics", "Software & Services"],
  "prohibited_activities": [],
  "concerns": [],
  "segments": [
    { "name": "iPhone",   "revenue_percentage": 50, "prohibited_revenue_impact": "negligible", "significance": "major" },
    { "name": "Services", "revenue_percentage": 26, "prohibited_revenue_impact": "negligible", "significance": "major" }
  ]
}

Each segment has its revenue_percentage, a qualitative prohibited_revenue_impact (negligible, minor, major), and its significance, which follows from its size: major above 30% of revenue or US$50B, `moderate` above 10% or US$10B, otherwise minor, and unknown when the segment’s size is not measured. The list is empty when segment data isn’t available.

Financial-ratio screens

Three ratios are evaluated against AAOIFI thresholds. The screen keys are exactly debt_to_market_cap, cash_to_market_cap, and prohibited_revenue.

Screen key	What it measures	Threshold
`debt_to_market_cap`	Interest-bearing debt divided by market cap	≤ 30% (`0.30`)
`cash_to_market_cap`	Cash and interest-bearing securities divided by market cap	≤ 30% (`0.30`)
`prohibited_revenue`	Income from prohibited sources divided by total revenue	≤ 5% (`0.05`)

Each financial screen has the same shape: a result, the calculated value, the threshold, the comparison operator and a buffer:

{
  "result": "pass",
  "value": 0.020616,
  "threshold": 0.30,
  "operator": "<=",
  "buffer": 27.9384
}

value and threshold are decimals: 0.020616 is 2.06%, 0.30 is 30%. The buffer is the distance to the threshold in percentage points: positive when passing, negative when failing.

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 and cash_to_market_cap ratios are reported as usual: a non-permissible business with little debt or cash passes those two and still fails on business_activity.

Market-cap basis

AAOIFI Standard 21 uses market capitalization as the denominator for the debt and cash ratios. The methodology endpoint reports this calculation basis as market_capitalization.

Trailing twelve months (TTM)

The prohibited_revenue numerator and denominator cover the trailing twelve months: the most recent annual filing plus any quarterly filings since. filing names the exact filing set behind a determination, with a deterministic hash.

Walking through a `/compliance` response

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

{
  "data": {
    "symbol": "AAPL",
    "instrument_id": "AAPL",
    "name": "Apple Inc.",
    "methodology": "aaoifi-ss21@2026.1",
    "as_of": "2026-06-01T00:00:00Z",
    "determination": {
      "status": "compliant",
      "confidence": 0.95,
      "explanation": "All financial ratios are well within AAOIFI limits..."
    },
    "screens": {
      "business_activity": {
        "result": "pass",
        "activities": ["Consumer Electronics", "Software & Services"],
        "prohibited_activities": [],
        "concerns": []
      },
      "debt_to_market_cap": {
        "result": "pass",
        "value": 0.020616,
        "threshold": 0.30,
        "operator": "<=",
        "buffer": 27.9384
      },
      "cash_to_market_cap": {
        "result": "pass",
        "value": 0.018,
        "threshold": 0.30,
        "operator": "<=",
        "buffer": 28.2
      },
      "prohibited_revenue": {
        "result": "pass",
        "value": 0.01012,
        "threshold": 0.05,
        "operator": "<=",
        "buffer": 3.988
      }
    },
    "revenue": {
      "total": 451442000000,
      "total_income": 456010490000,
      "permissible": { "amount": 451442000000, "percentage": 98.998 },
      "prohibited": {
        "amount": 4568490000,
        "percentage": 1.002,
        "breakdown": {
          "interest_income": 4568490000,
          "gambling": 0,
          "alcohol": 0,
          "weapons": 0,
          "tobacco": 0,
          "adult_entertainment": 0,
          "other": 0
        }
      }
    },
    "purification": { "required": true, "percentage": 1.012, "amount_per_1000": 10.12 },
    "stability": {
      "rating": "stable",
      "drivers": [
        {
          "code": "COMFORTABLE_BUFFERS",
          "message": "All financial ratios are well within limits",
          "severity": "info"
        }
      ]
    },
    "filing": {
      "summary": "10-K(2025-10-31) + 10-Q(2026-05-01)",
      "hash": "a1b2c3...",
      "filings": [
        {
          "type": "10-K",
          "period_end": "2025-09-27",
          "filing_date": "2025-10-31",
          "accession_number": "0000320193-25-000079"
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "methodology": "aaoifi-ss21@2026.1"
  }
}

`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 has a fifth key, structural.

`revenue`

The full revenue breakdown: total (reported revenue), total_income, the permissible and prohibited splits (amount plus percentage), and a per-category breakdown of prohibited revenue (interest income, gambling, alcohol, weapons, tobacco, adult entertainment). total_income is what the percentages divide: reported revenue plus any interest reported outside it, so the two amounts add up to it. Amounts are in US dollars, converted for a company that reports in another 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, which a shareholder gives away. purification.required says whether any applies, and purification.percentage is the company’s prohibited-income rate (prohibited revenue ÷ total revenue). We apply 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 is the rate per 1,000 units of dividends received, for tooling that works from distributions.

`stability`

How close the ratios sit to their limits, and how firm the data behind them is: a rating of stable, watch or borderline, and the drivers behind it. See Stability metrics.

`filing`

The filing set behind the determination: a readable summary, a deterministic hash, 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, so we decide them on the structure of the vehicle, under the standard the ETF taxonomy assigns them:

`methodology`	Vehicle	Decided on
`aaoifi-ss57@2026.1`	Physical gold and silver: a US grantor trust (`GLD`, `SLV`) or an ETC (`LON:SGLN`, `LON:RMAP`)	Eight criteria from Standard No. 57 on possession, custody and trading, one per rule, each resting on quoted text from the prospectus, the annual report or the custody agreement
`aaoifi-ss20@2026.1`	A futures pool (`USO`)	Clause 5/1/2 of Standard No. 20: a vehicle whose exposure is built through futures contracts is non-compliant
`halal-sh-etf-taxonomy@2026.1`	A crypto ETP, or a vehicle screened before its checklist was published with the result	The taxonomy’s asset, wrapper and yield questions; the `explanation` carries the criteria in prose

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:

{
  "methodology": "aaoifi-ss57@2026.1",
  "determination": { "status": "compliant", "confidence": 0.85, "explanation": "..." },
  "screens": {
    "business_activity": { "result": "pass", "activities": ["Holding allocated gold"], "prohibited_activities": [], "concerns": [], "segments": [] },
    "debt_to_market_cap": { "result": "not_applicable", "value": null, "threshold": 0.30, "operator": "<=", "buffer": null },
    "cash_to_market_cap": { "result": "not_applicable", "value": null, "threshold": 0.30, "operator": "<=", "buffer": null },
    "prohibited_revenue": { "result": "not_applicable", "value": null, "threshold": 0.05, "operator": "<=", "buffer": null },
    "structural": {
      "standard": "AAOIFI SS 57 (Gold and Its Trading Controls)",
      "instrument_type": "physical_gold_etc",
      "wrapper": "etc",
      "criteria": [
        {
          "key": "entitlement",
          "name": "Entitlement to the metal (the ETC wrapper)",
          "result": "pass_with_note",
          "evidence": "The Securities constitute secured, limited recourse obligations of the Issuer issued in Series in the form of debt securities ... Each Security will have a metal entitlement expressed as an amount in weight of the Metal.",
          "source": "iShares Physical Metals plc Base Prospectus 2026, Overview of the Programme",
          "note": "The holder owns a secured note whose value is the metal, not a share of the bars. Only authorised participants can take delivery of gold; every other holder is paid in cash from a sale of the metal."
        },
        {
          "key": "physical_backing",
          "name": "Physical backing",
          "result": "pass",
          "evidence": "The ETC securities are backed by fully-allocated physical holdings of the relevant precious metal custodied in secured vaults.",
          "source": "iShares Physical Metals plc Annual Report, financial year ended 30 April 2026, Directors' Report",
          "note": null
        }
      ]
    }
  }
}

Each criterion’s result is one of four values, and each has its own evidence requirement:

`result`	What it rests on
`pass`	A verbatim quote (`evidence`) from the named document (`source`).
`pass_with_note`	A quote that establishes the criterion in part, plus what could not be closed (`note`).
`not_disclosed`	No document addressed the criterion; `evidence` lists the searches run. One such criterion caps `confidence` at 0.75.
`fail`	A document contradicts the criterion. The vehicle is non-compliant.

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 has one screen per criterion with the same quotes.

Confidence

determination.confidence is a score from 0 to 1 for the quality of the data behind the determination. The Evidence Packet’s confidence_detail shows how it was built: the base confidence and each penalty or boost applied.

`confidence`	Evidence Packet `reason_codes`	Read
0.9 and above	`high_data_quality`	Recent filings, with the values read from them directly.
0.7 to under 0.9	`moderate_data_quality`	Minor data gaps or older filings.
Below 0.7	`low_data_quality`	Estimated or missing values, or stale filings.

When a stock hasn’t been analyzed

If a stock has no analysis yet, determination.status is pending and screens, revenue, purification, stability, and filing are all null.

{
  "data": {
    "symbol": "ACME",
    "name": "Acme Corp.",
    "methodology": "aaoifi-ss21@2026.1",
    "determination": { "status": "pending", "confidence": null, "explanation": null },
    "screens": null,
    "revenue": null,
    "purification": null,
    "stability": null,
    "filing": null
  }
}

pending means we have no published determination for the instrument. The endpoint does not queue an analysis. Treat any unknown future status value as pending.

When we analyzed it and hold the verdict back

A few instruments stay pending because we analyzed 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.

"determination": {
  "status": "pending",
  "confidence": null,
  "explanation": null,
  "withheld": { "reason": "screen_unresolved", "analysed": true, "since": "2026-09-16" }
}

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 an ethical_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. The two signals are independent: a stock can be AAOIFI-compliant and still be flagged here, or the reverse.

Data sources

For a company that files with the SEC, financial data comes from the XBRL data in its 10-K, 10-Q, 20-F and 40-F filings. For a listing outside the US, it comes from the annual report filed in its home market (ESEF in the UK and EU, EDINET in Japan, DART in Korea), or from a market-data provider’s annual figures where no such filing is available. The Evidence Packet traces every number in a determination to its source: the type, the accession number (or our identifier for a non-SEC source) and the period.

Getting Started

Core Concepts

Guides

Overview

Business activity

Financial ratios

Business-activity screen

Financial-ratio screens

Market-cap basis

Trailing twelve months (TTM)

Walking through a `/compliance` response

`determination`

`screens`

`revenue`

`purification`

`stability`

`filing`

Pooled vehicles: the structural screen

Confidence

When a stock hasn’t been analyzed

When we analyzed it and hold the verdict back

Ethical screening

Data sources

Overview

Business activity

Financial ratios

Business-activity screen

Financial-ratio screens

Market-cap basis

Trailing twelve months (TTM)

Walking through a /compliance response

determination

screens

revenue

purification

stability

filing

Pooled vehicles: the structural screen

Confidence

When a stock hasn’t been analyzed

When we analyzed it and hold the verdict back

Ethical screening

Data sources

Walking through a `/compliance` response

`determination`

`screens`

`revenue`

`purification`

`stability`

`filing`