> ## Documentation Index
> Fetch the complete documentation index at: https://docs.halal.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Compliance screening

> How AAOIFI Standard 21 screening works and what the /compliance endpoint returns.

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

<CardGroup cols={2}>
  <Card title="Business activity" icon="briefcase">
    Is the company's core business permissible? A qualitative `pass`/`fail`.
  </Card>

  <Card title="Financial ratios" icon="calculator">
    Three numeric screens — debt, cash, and prohibited revenue — each compared against an AAOIFI threshold.
  </Card>
</CardGroup>

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:

```json theme={null}
{
  "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`:

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

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

<Note>
  **`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`.
</Note>

### 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](/api-reference/methodology/get-methodology).

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

```bash theme={null}
curl https://api.halal.sh/v1/instruments/AAPL/compliance \
  -H "X-API-Key: hsh_sandbox_your_key"
```

```json theme={null}
{
  "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](/concepts/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`.

```json theme={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
  }
}
```

<Note>
  `pending` simply means the instrument has not been analysed yet — the endpoint does not queue analysis. Treat any unknown future status value as `pending`.
</Note>

## Ethical screening

Separate from AAOIFI financial compliance, the [instrument](/api-reference/instruments/get-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](/concepts/evidence-packets).