Screen a portfolio

Overview

POST /v1/screen checks compliance for up to 50 symbols in one request, so you can screen a portfolio or a watchlist without one call per stock. Each result has a compliance_status. For the ratios behind it, call /compliance for that symbol (see Enrich with per-stock screens).

Screen a list of symbols

Pass a symbols array. A sandbox key works with the 12 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", "JPM"]
  }'

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", "JPM"],
  }),
});

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

Response

data is an array with one row per screened stock, each with 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": "non-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 only. Unknown tickers and ETF tickers come back in meta.not_found, and meta.etfs lists the ETF tickers among them, to look up with GET /etfs/{symbol}. On the sandbox, requested symbols outside the sandbox universe come back in meta.sandbox_restricted. Both meta.etfs and meta.sandbox_restricted are present only when they have symbols. Filter on the status:

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 we haven’t analyzed the instrument yet, so it has no screens. Handle pending analysis shows how to treat these.

Enrich with per-stock screens

POST /screen returns the status per symbol. To show why a stock passed or failed, fetch its three financial screens from GET /instruments/{symbol}/compliance.

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 has a result of "pass", "fail" or "not_applicable". There is no boolean passes field, so check screens.debt_to_market_cap.result === "pass". 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`	Prohibited income as a share of total revenue

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.

With the Plus or Developer plan, you can also screen the analyzed universe by filter (compliance status, sector, market cap, financial health or country) instead of listing symbols. On the sandbox, pass a symbols array.

Getting Started

Core Concepts

Guides

Overview

Screen a list of symbols

Response

Enrich with per-stock screens

Limits