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 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.

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.

`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 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:

{
  "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 reports its 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 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 relative to size	≤ 30% (`0.30`)
`cash_to_market_cap`	Cash and interest-bearing assets relative to size	≤ 30% (`0.30`)
`prohibited_revenue`	Income from prohibited sources relative to total revenue	≤ 5% (`0.05`)

Each financial screen is 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 / 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 as market_capitalization by the methodology endpoint.

Trailing twelve months (TTM)

The prohibited_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

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

{
  "data": {
    "symbol": "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,
      "permissible": { "amount": 446873510000, "percentage": 98.988 },
      "prohibited": {
        "amount": 4568490000,
        "percentage": 1.012,
        "breakdown": {
          "interest_income": 4568490000,
          "gambling": 0,
          "alcohol": 0,
          "weapons": 0,
          "tobacco": 0,
          "adult_entertainment": 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".

`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.

`purification`

When a compliant company earns minor prohibited income (typically interest on cash), shareholders purify that share of their dividends by giving it to charity. purification.required flags whether purification applies; purification.percentage is the share of dividends to purify (prohibited revenue ÷ total revenue); and purification.amount_per_1000 is the amount to purify per 1,000 units of dividends received — a ready-to-use figure for portfolio tooling.

`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.

Confidence

determination.confidence is a 0–1 score reflecting data quality. The Evidence Packet’s confidence_detail shows exactly how it was built — the base confidence, the extraction strategies and any fallbacks used, and each penalty or boost applied.

Range	Read
0.85–1.0	High — recent filings, clean extraction, validated data.
0.70–0.84	Medium — minor data gaps or older filings.
Below 0.70	Low — significant estimation, missing data, or stale filings.

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.

{
  "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 simply means the instrument has not been analysed yet — the endpoint does not queue analysis. Treat any unknown future status value as pending.

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. This is an independent signal — a stock can be AAOIFI-compliant and still be flagged here, or vice versa.

Data sources

Financial data is extracted from SEC filings (10-K, 10-Q, 20-F, 40-F) via XBRL structured data. Every number in a determination traces back to its source filing — accession number, XBRL tags, and extraction strategy — in the Evidence Packet.

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`

Confidence

When a stock hasn’t been analysed

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

​Confidence

​When a stock hasn’t been analysed

​Ethical screening

​Data sources

Overview

Business-activity screen

Financial-ratio screens

Market-cap basis

Trailing twelve months (TTM)

Walking through a `/compliance` response

`determination`

`screens`

`revenue`

`purification`

`stability`

`filing`

Confidence

When a stock hasn’t been analysed

Ethical screening

Data sources