Evidence Packets

What is an Evidence Packet?

An Evidence Packet is the compliance record for a single instrument, in one response: the determination, every screen with its calculation, the values it used and the filing each came from, a confidence breakdown, and the stability signal. Use a packet to:

Document for Shariah boards

Show the exact filings, values, and ratios behind each verdict.

Satisfy audits

Recompute every ratio from the values and filings in the packet.

Build client reports

Pull structured numerator/denominator data straight into reports.

Watch the closest limit

See which ratio is nearest its limit, and by how much.

An Evidence Packet exists only once a stock has been analyzed. While determination.status is pending, GET /instruments/{symbol}/evidence returns 404.

Fetching a packet

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

Structure

{
  "data": {
    "instrument": {
      "symbol": "NVDA",
      "instrument_id": "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"
          },
          "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": [],
            "extraction_strategy": "unknown",
            "raw_values": {
              "TotalDebt": 11520000000
            }
          }
        ]
      }
    ],

    "confidence_detail": {
      "score": 0.94,
      "base_confidence": 1.0,
      "extraction_strategies_used": [],
      "fallbacks_used": [],
      "penalties": [],
      "boosts": []
    },

    "stability": {
      "closest_threshold": {
        "screen": "prohibited_revenue",
        "current_distance": 0.032
      },
      "stability_rating": "stable",
      "stability_drivers": [
        {
          "code": "COMFORTABLE_BUFFERS",
          "message": "All financial ratios are well within limits",
          "severity": "info"
        }
      ]
    },

    "disclosures": [
      "The debt and cash ratios divide by the spot market capitalization at the time of analysis. AAOIFI Standard 21 sets no averaging period.",
      "All financial figures are in USD. Figures a filing reports in another currency are converted to USD."
    ]
  },
  "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. A pooled vehicle names the standard its checklist applied (aaoifi-ss57, aaoifi-ss20 or halal-sh-etf-taxonomy). See Methodology versioning.

`determination`

The verdict: status, confidence, machine-readable reason_codes, and purification (required plus the prohibited-income percentage, the input to the per-share method).

`screens[]`

One entry per screen, keyed by name: business_activity, debt_to_market_cap, cash_to_market_cap, or prohibited_revenue; for a pooled vehicle, business_activity and then one entry per criterion of its structural screen (entitlement, physical_backing, allocated, …), with no ratio screens. Every entry has its result and one of three payloads:

Business-activity screen
Financial-ratio screens
Structural criteria

A detail object: primary_activities, prohibited_activities, activity_compliance (permissible or non-permissible), and concerns.

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.

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

A structural object: the criterion name, its verdict (pass, pass_with_note, not_disclosed or fail), the verbatim evidence it rests on, the source document and section, and a note for what could not be closed. Its sources[] entry gives the issuer document set (filing_type such as ETC-AR) and extraction_strategy: structural_screen. See Pooled vehicles.

`sources[]`

Where each screen’s values came from:

Field	What it is
`filing_type`	10-K, 10-Q, 20-F, or 40-F; for a non-SEC basis, the report type (`ESEF-AR`, `ETC-AR`, …).
`accession_number`	The SEC EDGAR unique filing identifier, or our identifier for a non-SEC basis.
`period_end` / `filing_date`	The reporting period and when it was filed.
`xbrl_tags`	The XBRL concepts whose dollar facts, for the period each value measures, add up to each value in `raw_values` exactly. A source with two values (cash and securities; interest income and revenue) lists the concepts behind both in one list, without saying which value each backs. A figure is checked against the filing it was read from, which can be the annual report rather than the filing this source names, and a trailing-twelve-month figure against the annual and the latest interim report together. Names are as the filing gives them (`LongTermDebtNoncurrent`), with no taxonomy prefix, because a name can come from US GAAP, IFRS or the filer’s own extension. Empty when a value could not be rebuilt that way, rests on a subtraction (a finance lease taken out of a debt total), came from another source, or belongs to a result analyzed before this field was introduced (see the September 2026 changelog).
`extraction_strategy`	How the value was obtained (e.g. `ComponentSum`), or `unknown` when the extraction did not record it.
`raw_values`	The values the screen used, as extracted, keyed by name.

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

stability_rating and stability_drivers, the same rating and drivers as stability on /compliance, and closest_threshold: the passing ratio screen nearest its limit, with its current_distance. See Stability metrics. The object also has four deprecated fields with no data in them (quarters_compliant, quarters_total, flip_rate and closest_threshold.trend), which will be removed in the next major version: see Deprecated fields.

`disclosures[]`

Plain-language notes on how the determination was calculated, such as the market-cap denominator and the currency.

Getting Started

Core Concepts

Guides

What is an Evidence Packet?

Document for Shariah boards

Satisfy audits

Build client reports

Watch the closest limit

Fetching a packet

Structure

Field reference

`methodology`

`determination`

`screens[]`

`sources[]`

`confidence_detail`

`stability`

`disclosures[]`