screening

Screen Symbol

Screen a single symbol for Shariah compliance.

Performs a full Shariah compliance analysis on the given ticker, including business activity screening and financial ratio checks against AAOIFI, DJIM, FTSE, MSCI, and S&P methodologies.

Both GET and POST are accepted; POST is canonical and appears in all examples, while GET is provided as a forgiveness alias so clients that intuitively reach for GET (a common mistake) succeed instead of receiving 405. There is no request body on either method; the only input is the path parameter.

Costs 5 tokens per call. Results are cached for 7 days: a call within that window returns the cached verdict (still 5 tokens — use GET /api/result/{symbol} at 1 token if the cache is all you need). Pass ?force_refresh=true to bypass the cache and re-run the full screen — useful after a methodology code change or upstream financial-data correction. Defaults to false so normal traffic remains served from cache. force_refresh is honored on Enterprise plans only; on other plans it is accepted and has no effect, and a verdict older than 7 days is recomputed automatically. A recomputed verdict carries a new last_checked_at. A first-ever screen of an uncached symbol performs live data collection and can take several seconds; subsequent calls are fast.

curl example:

curl -X POST "https://api.halalterminal.com/api/screen/AAPL" \
     -H "X-API-Key: <API_KEY>"

Python requests example:

import requests

resp = requests.post(
    "https://api.halalterminal.com/api/screen/AAPL",
    headers={"X-API-Key": "<API_KEY>"},
)
print(resp.json())

get/api/screen/{symbol}

Request

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

Path parameters

symbolstring required

Ticker symbol, e.g. AAPL.

Query parameters

force_refreshboolean

Bypass the 7-day result cache and recompute a fresh verdict. Enterprise plans only: on other plans the parameter is accepted and has no effect.

Response

Freshly computed Shariah compliance screening result

symbolstring required

namestring nullable

Issuer / fund display name.

asset_typestring nullable

Asset class label derived during screening: 'Equity', 'ETF', 'ClosedEndFund', 'REIT', etc. Drives downstream methodology dispatch.

is_staleboolean nullable

True when last_checked_at is older than the 7-day refresh policy (SCREENING_STALENESS_HOURS, default 168). The platform re-screens cached results nightly, most-requested symbols first.

is_compliantboolean nullable

Overall Shariah compliance verdict (True = compliant under at least one methodology)

shariah_compliance_status'compliant' | 'non_compliant' | 'insufficient_data' nullable

Canonical string mirror of is_compliant in lowercase vocabulary (matches the ETF response and MethodologyVerdict). Synthesized by the service normalizer if absent on cached rows.

business_screen_passboolean nullable

Whether the company's primary business activities are permissible

business_screen_reasonstring nullable

Human-readable explanation for the business screen verdict

financial_screen_passboolean nullable

Whether the company passes all financial ratio thresholds

errorstring nullable

error_messagestring nullable

sectorstring nullable

industrystring nullable

countrystring nullable

websitestring nullable

long_business_summarystring nullable

total_assetsnumber nullable

total_debtnumber nullable

cash_and_equivalentsnumber nullable

accounts_receivablenumber nullable

total_revenuenumber nullable

interest_incomenumber nullable

debt_to_assets_rationumber nullable

Total debt / total assets — must be below threshold (e.g. 33% for AAOIFI)

cash_to_assets_rationumber nullable

Cash and equivalents / total assets

accounts_receivable_to_assets_rationumber nullable

Accounts receivable / total assets

interest_income_to_revenue_rationumber nullable

Interest income / total revenue — measures impermissible income proportion

debt_to_market_cap_rationumber nullable

Total debt / market capitalization — the AAOIFI debt screen since June 2026, and an input to DJIM and S&P. Computed on the same capitalization the AAOIFI verdict was rendered against: spot market cap by default, or the trailing average when a trailing basis is in force for that screen.

cash_to_market_cap_rationumber nullable

receivables_to_market_cap_rationumber nullable

liquidity_to_market_cap_rationumber nullable

liquidity_to_assets_rationumber nullable

purification_ratenumber nullable

Percentage of dividend income to purify (donate) due to impermissible revenue

aaoifi_compliantboolean nullable

Pass/fail for AAOIFI (Shari'ah Standard 21). For ratio, basis and reason, see by_methodology.AAOIFI.

djim_compliantboolean nullable

Pass/fail for the Dow Jones Islamic Market methodology. Detail in by_methodology.DJIM.

ftse_compliantboolean nullable

Pass/fail for the FTSE Shariah methodology. Detail in by_methodology.FTSE.

msci_compliantboolean nullable

Pass/fail for the MSCI Islamic methodology. Detail in by_methodology.MSCI.

sp_compliantboolean nullable

Pass/fail for the S&P Shariah methodology. Detail in by_methodology.SP.

methodology_summaryobject nullable

Mapping of methodology name to compliance verdict: true = compliant, false = non-compliant, null = insufficient data (see data_quality.methodologies_insufficient).

by_methodologyobject nullable

Structured per-methodology block. Mirrors methodology_summary for the verdict but adds an verified audit flag and a reason string. Synthesized by the service normalizer if absent on cached rows.

questionable_businessobject nullable

ADVISORY (does not affect the verdict): {flag, reasons} when the issuer's video-game portfolio includes simulated-gambling content (social casino, slots, poker). Video gaming itself passes the business screen; this flag marks the scholars-differ cases the way analyst-based screeners label them 'questionable'.

ifi_exemptboolean nullable

True when the issuer is a certified Islamic financial institution (curated registry / regulated name markers): exempt from the conventional-finance exclusion and the accounting screens per the DJIM/MSCI/S&P IFI carve-outs. Null for ordinary issuers.

business_incomeobject nullable

ADVISORY (does not affect the verdict): per-segment revenue breakdown extracted from the issuer's latest 10-K, with each segment classified permissible / impermissible / questionable / unknown by a versioned rules map. Includes the combined impure ratio (interest + impermissible) and a separate with-questionable figure — the split where reputable screeners legitimately differ. Null when no segment analysis exists yet.

fx_normalizationobject nullable

Present when the issuer reports financials in a different currency than its listing (ADR-style): {rate, from, to} used to convert the market-cap-ratio numerators into the listing currency. Null when no mismatch existed or no rate could be resolved (in which case MC-basis methodologies abstain).

compliance_explanationstring nullable

Plain-English summary of the compliance verdict: which methodologies pass, which fail, and which ratio tripped the failures. Empty for ticker_unknown or rows where the financial screen could not run.

return_on_equitynumber nullable

net_profit_marginnumber nullable

revenue_growthnumber nullable

pe_rationumber nullable

pb_rationumber nullable

intrinsic_valuenumber nullable

dcf_upside_percentagenumber nullable

Upside/downside percentage based on DCF intrinsic value vs current price

momentum_trendstring nullable

rsi_statusstring nullable

current_rationumber nullable

market_capnumber nullable

betanumber nullable

dividend_yieldnumber nullable

dispositionstring nullable

ETF-only. Non-verdict scholar-derived label: 'scholar_certified', 'data_quality_flag', 'contested', 'unrated'. See v2 cert spec §11.

scholar_attestationsobject[] nullable

ETF-only. List of scholar-board attestations; empty list when none on file.

holdings_analysisobject nullable

ETF-only. Aggregate holdings-based compliance metrics (compliant_weight, etc.).

detail_urlstring nullable

ETF-only. Path to the richer first-class ETF endpoint (/api/etf/{symbol}/screen).

Example response

{
  "aaoifi_compliant": true,
  "accounts_receivable": 60932000000,
  "accounts_receivable_to_assets_ratio": 0.173,
  "business_screen_pass": true,
  "business_screen_reason": "Technology hardware and equipment — permissible primary activity",
  "cash_and_equivalents": 29965000000,
  "cash_to_assets_ratio": 0.085,
  "cash_to_market_cap_ratio": 0.009,
  "country": "US",
  "debt_to_assets_ratio": 0.315,
  "debt_to_market_cap_ratio": 0.032,
  "djim_compliant": true,
  "financial_screen_pass": true,
  "ftse_compliant": true,
  "industry": "Consumer Electronics",
  "interest_income": 3999000000,
  "interest_income_to_revenue_ratio": 0.01,
  "is_compliant": true,
  "last_checked_at": "2025-01-15T12:30:00Z",
  "methodology_summary": {
    "aaoifi": true,
    "djim": true,
    "ftse": true,
    "msci": true,
    "sp": true
  },
  "msci_compliant": true,
  "purification_rate": 0.012,
  "sector": "Technology",
  "sp_compliant": true,
  "symbol": "AAPL",
  "total_assets": 352583000000,
  "total_debt": 111088000000,
  "total_revenue": 394328000000
}

Changes

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