Screen a Portfolio

Overview

POST /v1/screen checks compliance for up to 50 symbols in one request. It’s the fastest way to screen a portfolio, validate a watchlist, or power a compliance dashboard without making one call per stock. Each result carries a compliance_status you can read directly. Need the underlying ratios? Enrich any symbol with a follow-up call to /compliance (see Enrich with per-stock screens below).

Screen a list of symbols

Pass a symbols array. The sandbox key works against the 12 pre-analysed sandbox instruments.

curl -X POST https://api.halal.sh/v1/screen \
  -H "X-API-Key: hsh_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "symbols": ["AAPL", "MSFT", "NVDA", "JPM", "TSLA"]
  }'

const response = await fetch("https://api.halal.sh/v1/screen", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.HALALSH_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    symbols: ["AAPL", "MSFT", "NVDA", "JPM", "TSLA"],
  }),
});

const { data } = await response.json();

Response

data is a flat array — every entry includes a compliance_status of compliant, non-compliant, or pending.

{
  "data": [
    { "symbol": "AAPL", "name": "Apple Inc.", "compliance_status": "compliant", "health_status": "antifragile", "market_data": { "price": 315.02, "change_24h": 8.71, "change_percent_24h": 2.84 } },
    { "symbol": "MSFT", "name": "Microsoft Corporation", "compliance_status": "compliant", "health_status": "antifragile", "market_data": { "price": 441.45, "change_24h": -19.10, "change_percent_24h": -4.15 } },
    { "symbol": "JPM", "name": "JPMorgan Chase & Co.", "compliance_status": "non-compliant", "health_status": "fragile", "market_data": { "price": 301.00, "change_24h": 4.42, "change_percent_24h": 1.49 } }
  ],
  "meta": { "total": 3, "requested": 3, "not_found": [] }
}

/screen screens stocks. Unknown tickers — and ETF tickers, which belong to GET /etfs/{symbol} — are returned in meta.not_found rather than as fabricated rows. On a sandbox key, any requested symbol outside the sandbox universe is returned in meta.sandbox_restricted (present only when non-empty) instead of being silently dropped. Read the status straight off each result:

const { data } = await response.json();

const compliant = data.filter(
  (r) => r.compliance_status === "compliant"
);

console.log(`${compliant.length} of ${data.length} symbols are compliant`);

A compliance_status of pending means the instrument hasn’t been analysed yet — its screens aren’t available. See Handle Pending Analysis for how to treat these gracefully.

Enrich with per-stock screens

POST /screen gives you the verdict per symbol. To show why a stock passed or failed, fetch the three financial screens from GET /instruments/{symbol}/compliance for the symbols you want to drill into.

async function enrich(symbol) {
  const res = await fetch(`https://api.halal.sh/v1/instruments/${symbol}/compliance`, {
    headers: { "X-API-Key": process.env.HALALSH_API_KEY },
  });
  const { data } = await res.json();
  const { screens } = data;

  return {
    symbol,
    status: data.determination.status,
    debtOk: screens.debt_to_market_cap.result === "pass",
    cashOk: screens.cash_to_market_cap.result === "pass",
    revenueOk: screens.prohibited_revenue.result === "pass",
  };
}

Each financial screen exposes a result of "pass" or "fail" — there is no boolean passes field. Check screens.debt_to_market_cap.result === "pass", not screens.debt_to_market_cap.passes. The three financial screen keys are always:

Key	What it measures
`debt_to_market_cap`	Interest-bearing debt as a share of market cap
`cash_to_market_cap`	Cash and interest-bearing securities as a share of market cap
`prohibited_revenue`	Revenue from non-permissible activities

value and threshold are decimals (0.30 = 30%) and buffer is in percentage points.

Limits

A single /screen request accepts at most 50 symbols. Split larger portfolios into batches of 50.

Filter mode is a Plus capability. On Plus you can screen the analysed universe by attributes (status, sector, and similar) instead of listing symbols. On the sandbox and free tiers, always pass an explicit symbols array.

Getting Started

Core Concepts

Guides

Overview

Screen a list of symbols

Response

Enrich with per-stock screens

Limits

​Overview

​Screen a list of symbols

​Response

​Enrich with per-stock screens

​Limits

Overview

Screen a list of symbols

Response

Enrich with per-stock screens

Limits