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

# Introduction

> Shariah compliance data for every public company — with full provenance.

The halal.sh API provides programmatic access to Shariah compliance screening
for public equities and ETFs, based on **AAOIFI Shari'ah Standard No. 21**.

Unlike providers that return a single black-box verdict, halal.sh exposes **every
screen, ratio, threshold, and source filing** behind each determination. Every
number traces back to an SEC filing and an XBRL tag.

## What you can do

<CardGroup cols={2}>
  <Card title="Screen stocks" icon="filter">
    Get the compliance status, financial-ratio screens, and business-activity
    screen for any analysed company.
  </Card>

  <Card title="Evidence Packets" icon="file-certificate">
    Pull an audit-ready bundle with full provenance — accession numbers, XBRL
    tags, and extraction strategies for every metric.
  </Card>

  <Card title="Analyse ETFs" icon="chart-pie">
    Get an ETF's Shariah purity and a per-holding compliance breakdown.
  </Card>

  <Card title="Track history" icon="clock-rotate-left">
    Follow a company's compliance determination across filing periods, with a
    stability signal.
  </Card>
</CardGroup>

## Why halal.sh

|                                                       | halal.sh | Typical provider |
| ----------------------------------------------------- | -------- | ---------------- |
| Individual screen results (debt, revenue, liquidity)  | Yes      | Verdict only     |
| Filing-level provenance (accession number, XBRL tags) | Yes      | No               |
| Extraction-strategy transparency                      | Yes      | No               |
| Versioned methodology                                 | Yes      | No               |
| Stability metrics (threshold distance, trend)         | Yes      | No               |

## Base URL

All requests use a single base URL, with the version in the path:

```
https://api.halal.sh/v1
```

## Authentication

Every request is authenticated with an API key passed in the `X-API-Key`
header. [Create a key](https://halal.sh/account/api) — sandbox keys are free and
instant. See [Authentication](/authentication) for details.

## Quick example

```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-05-03T08:10:09.622Z",
    "determination": {
      "status": "compliant",
      "confidence": 0.95,
      "explanation": "Apple Inc. (AAPL) is **COMPLIANT** with AAOIFI Standard 21…"
    },
    "screens": {
      "business_activity": {
        "result": "pass",
        "activities": [],
        "prohibited_activities": [],
        "concerns": []
      },
      "debt_to_market_cap":  { "result": "pass", "value": 0.020616, "threshold": 0.30, "operator": "<=", "buffer": 27.94 },
      "cash_to_market_cap":  { "result": "pass", "value": 0.035677, "threshold": 0.30, "operator": "<=", "buffer": 26.43 },
      "prohibited_revenue":  { "result": "pass", "value": 0.010120, "threshold": 0.05, "operator": "<=", "buffer": 3.99 }
    },
    "purification": { "required": true, "percentage": 1.012 }
  },
  "meta": {
    "request_id": "req_C7F0xXgmN",
    "as_of": "2026-05-03T08:10:10.000Z",
    "methodology": "aaoifi-ss21@2026.1"
  }
}
```

Ratios are decimals (`0.020616` = 2.06%); thresholds are decimals too (`0.30` =
30%). The full response also includes `revenue`, `stability`, and `filing`. See
[Get compliance screening](/api-reference/instruments/get-compliance).

## Client libraries

Official SDKs are on the way. Until then, the API is plain REST and works with
any HTTP client:

<CodeGroup>
  ```javascript Node.js theme={null}
  const res = await fetch(
    "https://api.halal.sh/v1/instruments/AAPL/compliance",
    { headers: { "X-API-Key": process.env.HALALSH_API_KEY } }
  );
  const { data } = await res.json();
  console.log(data.determination.status); // "compliant"
  ```

  ```python Python theme={null}
  import requests

  data = requests.get(
      "https://api.halal.sh/v1/instruments/AAPL/compliance",
      headers={"X-API-Key": API_KEY},
  ).json()["data"]

  print(data["determination"]["status"])  # "compliant"
  ```
</CodeGroup>

<CardGroup cols={2}>
  <Card title="Get started" icon="rocket" href="/quickstart">
    Create a key and make your first request in under two minutes.
  </Card>

  <Card title="Support" icon="life-ring" href="https://halal.sh/contact">
    Questions, or a result that looks off? Get in touch.
  </Card>
</CardGroup>