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

# Evidence Packets

> Audit-ready compliance bundles with full provenance — the data that makes halal.sh a system of record.

## What is an Evidence Packet?

An Evidence Packet is a self-contained compliance audit bundle for a single instrument. It carries the determination, every screen with its calculation, the source filings and XBRL tags each number came from, a confidence breakdown, and stability metrics — everything needed to reproduce and defend a screening decision.

This is what turns a screening result into a **defensible compliance decision**. ETF issuers, advisors, and fund managers use Evidence Packets to:

<CardGroup cols={2}>
  <Card title="Document for Shariah boards" icon="file-signature">
    Show the exact filings, tags, and ratios behind each verdict.
  </Card>

  <Card title="Satisfy audits" icon="clipboard-check">
    Reproduce any determination from its filing set and methodology version.
  </Card>

  <Card title="Build client reports" icon="chart-pie">
    Pull structured numerator/denominator data straight into reports.
  </Card>

  <Card title="Track threshold proximity" icon="gauge">
    Watch how close a holding sits to flipping over time.
  </Card>
</CardGroup>

<Note>
  Evidence is available only after a stock has been analysed. While `determination.status` is `pending`, `GET /instruments/{symbol}/evidence` returns `404`.
</Note>

## Fetching a packet

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

## Structure

```json theme={null}
{
  "data": {
    "instrument": {
      "symbol": "NVDA",
      "name": "NVIDIA Corporation",
      "exchange": "Nasdaq"
    },
    "as_of": "2026-03-08",
    "period": "FY2026",
    "currency": "USD",

    "methodology": {
      "id": "aaoifi-ss21",
      "version": "2026.1",
      "name": "AAOIFI Shariah Standard No. 21"
    },

    "determination": {
      "status": "compliant",
      "confidence": 0.94,
      "reason_codes": ["all_screens_pass", "high_data_quality"],
      "purification": { "required": true, "percentage": 1.8 }
    },

    "screens": [
      {
        "name": "business_activity",
        "result": "pass",
        "detail": {
          "primary_activities": ["Semiconductors", "GPU Computing"],
          "prohibited_activities": [],
          "activity_compliance": "permissible",
          "concerns": []
        }
      },
      {
        "name": "debt_to_market_cap",
        "result": "pass",
        "metric": {
          "value": 0.082,
          "threshold": 0.30,
          "operator": "<=",
          "formula": "total_interest_bearing_debt / market_cap",
          "numerator": {
            "value": 11520000000,
            "label": "Total Interest-Bearing Debt",
            "components": {
              "long_term_debt": 9709000000,
              "current_portion": 1811000000
            }
          },
          "denominator": {
            "value": 140400000000,
            "label": "Spot Market Cap",
            "method": "spot"
          }
        },
        "sources": [
          {
            "filing_type": "10-K",
            "accession_number": "0001045810-26-000032",
            "period_end": "2026-01-26",
            "filing_date": "2026-02-26",
            "xbrl_tags": [
              "us-gaap:LongTermDebt",
              "us-gaap:ShortTermBorrowings"
            ],
            "extraction_strategy": "PrimaryFields",
            "raw_values": {
              "LongTermDebt": 9709000000,
              "ShortTermBorrowings": 1811000000
            }
          }
        ]
      }
    ],

    "confidence_detail": {
      "score": 0.94,
      "base_confidence": 1.0,
      "extraction_strategies_used": ["PrimaryFields"],
      "fallbacks_used": [],
      "penalties": [],
      "boosts": [
        {
          "type": "xbrl_validated",
          "impact": 0.02,
          "reason": "XBRL data cross-validated against filing text"
        }
      ]
    },

    "stability": {
      "quarters_compliant": 8,
      "quarters_total": 8,
      "flip_rate": 0.0,
      "closest_threshold": {
        "screen": "prohibited_revenue",
        "current_distance": 0.041,
        "trend": "stable"
      },
      "stability_rating": "stable",
      "stability_drivers": [
        {
          "code": "consistent_compliance",
          "message": "Compliant for 8 consecutive quarters",
          "severity": "info"
        }
      ]
    },

    "disclosures": [
      "Market cap is used as the denominator for the debt and cash ratios per AAOIFI Standard 21.",
      "Prohibited revenue is trailing twelve months (TTM) from 10-K FY2026 + subsequent 10-Qs.",
      "Interest income extracted from the income statement using the PrimaryFields strategy."
    ]
  },
  "meta": {
    "request_id": "req_abc123",
    "methodology": "aaoifi-ss21@2026.1"
  }
}
```

## Field reference

### `methodology`

The exact ruleset, as separate `id` (`aaoifi-ss21`) and `version` (`2026.1`) fields, plus a human-readable `name`. Combined, this is the `aaoifi-ss21@2026.1` reference you'll also see in `meta.methodology`. See [Methodology versioning](/concepts/methodology-versioning).

### `determination`

The verdict — `status`, `confidence`, machine-readable `reason_codes`, and `purification` (`required` plus the `percentage` of dividends to purify).

### `screens[]`

One entry per screen, keyed by `name`: `business_activity`, `debt_to_market_cap`, `cash_to_market_cap`, or `prohibited_revenue`. Every entry reports `result: "pass" | "fail"`, and then carries one of two payloads:

<Tabs>
  <Tab title="Business-activity screen">
    Carries a `detail` object — `primary_activities`, `prohibited_activities`, `activity_compliance` (`permissible` or `non-permissible`), and `concerns`.
  </Tab>

  <Tab title="Financial-ratio screens">
    Carry a `metric` object — the `value`, `threshold`, `operator`, `formula`, and a fully decomposed `numerator` and `denominator`. The `denominator` has a `value`, `label`, and `method` (`spot` or `12-month-avg`; the latter adds `months_used`); the `numerator` adds `components` where it's a sum.

    <Warning>
      `value` and `threshold` are **decimals** (`0.082` = 8.2%, `0.30` = 30%), matching the `/compliance` response. When a ratio is undefined (e.g. a pre-revenue issuer earning interest income on \$0 operating revenue), `value` is `null` and a `note` explains why.
    </Warning>
  </Tab>
</Tabs>

### `sources[]`

The provenance for each screen — what makes a packet reproducible. Every source ties the numbers back to a filing:

| Field                        | What it is                                                         |
| ---------------------------- | ------------------------------------------------------------------ |
| `filing_type`                | 10-K, 10-Q, 20-F, or 40-F.                                         |
| `accession_number`           | The SEC EDGAR unique filing identifier.                            |
| `period_end` / `filing_date` | The reporting period and when it was filed.                        |
| `xbrl_tags`                  | The exact taxonomy elements used (e.g. `us-gaap:LongTermDebt`).    |
| `extraction_strategy`        | How the value was obtained (e.g. `PrimaryFields`, `ComponentSum`). |
| `raw_values`                 | The numbers as they appear in the filing.                          |

### `confidence_detail`

How the confidence `score` was built: the `base_confidence` it started from, the `extraction_strategies_used`, any `fallbacks_used`, and each `penalty` or `boost` (`type`, `impact`, `reason`) applied along the way.

### `stability`

The full stability signal — `quarters_compliant`, `quarters_total`, `flip_rate`, the `closest_threshold` it's nearest to breaching (one of the four screen names, e.g. `prohibited_revenue`, with its `current_distance` and `trend`), a `stability_rating`, and `stability_drivers`. See [Stability metrics](/concepts/stability-metrics).

### `disclosures[]`

Plain-language notes on the calculation basis, periods, and any assumptions behind the determination.