etf

Screen Etf

Run a Shariah compliance screening on an ETF.

Screens every holding in the ETF against Shariah compliance criteria and returns an overall compliance status, a weighted-average purification rate, a compliance summary (counts and weights), and per-holding screening results. Pass force_refresh=true to bypass cached results — available only for enterprise and internal plans; for other plans the flag is silently treated as False.

curl example:

curl -X POST "http://localhost:8000/api/etf/VTI/screen?force_refresh=false"

Python requests example:

import requests
resp = requests.post("http://localhost:8000/api/etf/VTI/screen", params={"force_refresh": False})
result = resp.json()
print(result["compliance_status"], "- compliant weight:", result["summary"]["compliant_weight"])
post/api/etf/{symbol}/screen

Request

  • Base URL: https://api.halalterminal.com
  • URL: https://api.halalterminal.com/api/etf/{symbol}/screen
  • Auth: API key in header X-API-Key

Path parameters

symbolstring required

ETF ticker symbol.

Query parameters

force_refreshboolean

Bypass cached results when true. Only enterprise and internal plans honor this; other plans treat it as false.

Response

Full Shariah screening result with per-holding compliance details.

symbolstring required

ETF ticker symbol.

namestring

ETF fund name.

is_compliantboolean nullable

Always null for ETFs (v2 spec §10.3). Use disposition or compute from summary.non_compliant_weight instead.

compliance_statusstring

Holdings-based bucket label kept for backwards compatibility: 'compliant', 'non_compliant', 'insufficient_data', 'unscreened'. For the verdict-shaped client signal, read disposition instead.

dispositionstring nullable

Non-verdict summary derived from scholar attestations + holdings analysis: 'scholar_certified', 'data_quality_flag', 'contested', 'unrated'. See spec §11.

scholar_attestationsobject[]

List of scholar-board attestations carrying methodology, position, verified_on, and source_url. Empty when no attestation is on file.

non_compliant_thresholdnumber

Maximum non-compliant weight allowed, as a fraction: 0.05 means 5%. The weight fields are in percent, so the test the engine runs is summary.non_compliant_weight / 100 against this threshold.

purification_ratenumber nullable

Weighted-average purification rate in percent, computed over the compliant, rated holdings ONLY: non-compliant and unscreened weight is excluded from both the numerator and the denominator. Use purification_weight_covered to see what share of the fund that average speaks for. For a figure covering the whole fund, which charges every non-compliant or unscreened holding at 100% by prudence, call POST /api/etf/{symbol}/purification and read etf_purification_rate. On a fund holding non-compliant names the two differ by several multiples, and the whole-fund figure is the one to show an investor.

purification_basisstring

Denominator behind purification_rate. Always 'compliant_rated_holdings' on this endpoint, against 'whole_fund_conservative' on the purification endpoint.

purification_weight_coverednumber nullable

Share of the fund, in percent, that purification_rate averages over. The gap to 100 is the non-compliant, unscreened and unrated weight that this average ignores.

data_sourcestring

Data provider used for screening.

Example response

{
  "compliance_status": "non_compliant",
  "data_source": "issuer",
  "disposition": "scholar_certified",
  "holdings": [],
  "name": "Wahed FTSE USA Shariah ETF",
  "non_compliant_threshold": 0.05,
  "purification_basis": "compliant_rated_holdings",
  "purification_rate": 0,
  "purification_weight_covered": 92.83,
  "scholar_attestations": [
    {
      "authority": "Yasaar Research Inc.",
      "methodology": "FTSE",
      "position": "compliant",
      "source_url": "https://www.sec.gov/Archives/edgar/data/1683471/...",
      "stale": false,
      "verified_on": "2026-05-08"
    }
  ],
  "summary": {
    "compliant_count": 146,
    "compliant_weight": 92.83,
    "non_compliant_count": 40,
    "non_compliant_weight": 5.99,
    "screened_count": 186,
    "total_holdings": 197,
    "unscreened_count": 11,
    "unscreened_weight": 0.65
  },
  "symbol": "HLAL"
}

Changes

No recorded changes to this operation across all 1 revision of this API.