Evidence Packets

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:

Document for Shariah boards

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

Satisfy audits

Reproduce any determination from its filing set and methodology version.

Build client reports

Pull structured numerator/denominator data straight into reports.

Track threshold proximity

Watch how close a holding sits to flipping over time.

Evidence is available only after a stock has been analysed. 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",
      "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.

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

Business-activity screen
Financial-ratio screens

Carries a detail object — primary_activities, prohibited_activities, activity_compliance (permissible or non-permissible), and concerns.

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.

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.

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

`disclosures[]`

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

Getting Started

Core Concepts

Guides

What is an Evidence Packet?

Document for Shariah boards

Satisfy audits

Build client reports

Track threshold proximity

Fetching a packet

Structure

Field reference

`methodology`

`determination`

`screens[]`

`sources[]`

`confidence_detail`

`stability`

`disclosures[]`

​What is an Evidence Packet?

Document for Shariah boards

Satisfy audits

Build client reports

Track threshold proximity

​Fetching a packet

​Structure

​Field reference

​methodology

​determination

​screens[]

​sources[]

​confidence_detail

​stability

​disclosures[]

What is an Evidence Packet?

Fetching a packet

Structure

Field reference

`methodology`

`determination`

`screens[]`

`sources[]`

`confidence_detail`

`stability`

`disclosures[]`