Skip to main content

​
1. Get your API key

Sign up at halal.sh/developers to get your sandbox API key instantly — no credit card required. Sandbox keys give you access to 10 popular stocks with real data and identical response schemas.

​
2. Make your first request

curl https://api.halal.sh/v1/instruments/AAPL/compliance \
  -H "X-API-Key: your_api_key"

​
3. Understand the response

Every compliance response includes:
FieldDescription
determination.statuscompliant, non-compliant, or pending
determination.confidence0–1.0 confidence score
screens.business_activitypass or fail — whether core business is permissible
screens.debt_to_market_capInterest-bearing debt / market cap (threshold: ≤ 30%)
screens.prohibited_revenueProhibited income / revenue (threshold: ≤ 5%)
screens.cash_receivables_to_market_cap(Cash + receivables) / market cap (threshold: ≤ 30%)
purification.percentagePercentage of dividends to purify

​
4. Screen a portfolio

Check multiple stocks at once: 
curl -X POST https://api.halal.sh/v1/screen \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "symbols": ["AAPL", "MSFT", "NVDA", "JPM", "LLY"],
    "include": ["determination", "screens"]
  }'

{
  "data": {
    "results": [
      { "symbol": "AAPL", "status": "compliant", "confidence": 0.92 },
      { "symbol": "MSFT", "status": "compliant", "confidence": 0.95 },
      { "symbol": "NVDA", "status": "compliant", "confidence": 0.94 },
      { "symbol": "JPM", "status": "non-compliant", "confidence": 0.98 },
      { "symbol": "LLY", "status": "compliant", "confidence": 0.91 }
    ],
    "summary": {
      "total": 5,
      "compliant": 4,
      "non_compliant": 1
    }
  }
}

​
5. Get an Evidence Packet

For audit-ready compliance documentation with full provenance: 
curl https://api.halal.sh/v1/instruments/NVDA/evidence \
  -H "X-API-Key: your_api_key"
This returns a complete audit bundle including filing references, XBRL tags, extraction strategies, and stability metrics. See Evidence Packets for the full schema.

​
Next steps

Authentication

API key management, rate limits, and security.

Compliance concepts

How AAOIFI Standard 21 screening works.

Evidence Packets

The full audit bundle schema and what makes it unique.

API Reference

Complete endpoint documentation.