Skip to main content
POST
/
screen
Screen instruments
curl --request POST \
  --url https://api.halal.sh/v1/screen \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "symbols": [
    "AAPL",
    "MSFT",
    "NVDA",
    "JPM"
  ],
  "status": "compliant",
  "sector": "<string>",
  "market_cap": "small",
  "health": "fragile",
  "limit": 50,
  "offset": 0
}
'
{
  "data": [
    {
      "symbol": "<string>",
      "company_name": "<string>",
      "compliance_status": "compliant",
      "health_status": "fragile",
      "market_data": {
        "current_price": 123,
        "change_24h": 123,
        "change_percent_24h": 123
      }
    }
  ],
  "meta": {
    "request_id": "req_abc123",
    "methodology": "aaoifi-ss21@2024",
    "as_of": "2026-03-08T12:00:00Z",
    "retry_after": 120,
    "total": 123,
    "limit": 123,
    "offset": 123,
    "requested": 123
  }
}

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
symbols
string[]

Specific symbols to screen. Max 50. When provided, returns compliance status for those symbols. Mutually exclusive with filter parameters.

Maximum array length: 50
Example:
["AAPL", "MSFT", "NVDA", "JPM"]
​
status

Filter by compliance status. Can be a string or array of strings.

Available options:
compliant,
non-compliant,
pending
​
sector
string

Filter by sector (e.g., "Technology").

​
market_cap

Filter by market cap category. Can be a string or array of strings.

Available options:
small,
mid,
large,
mega
​
health

Filter by financial health status. Can be a string or array of strings.

Available options:
fragile,
robust,
antifragile
​
limit
integer
default:50
Required range: x <= 100
​
offset
integer
default:0

Response

Screening results (empty results array if no matches)

​
data
object[]

Array of screening results. When using symbols, returns compliance card data. When using filters, returns discovery results with sector and fundamentals.

​
meta
object